Image Filter in NGINX: The Complete Guide

Introduction

NGINX, known as a high-performance web server, also provides the capability to manipulate images on-the-fly before serving them to clients. This functionality facilitates various image transformations including resizing, cropping, and rotating without the need for additional server-side image processing tools. In this tutorial, we will explore how to leverage NGINX’s image filter module to apply dynamic image transformations.

Prerequisites

• An installed version of NGINX with the image filter module. If your build of NGINX does not include the module, you may need to compile NGINX from source with the --with-http_image_filter_module configuration flag.
• Basic understanding of NGINX configuration.
• Image files that you would like to manipulate.

Enabling the Image Filter Module

Before proceeding, you need to ensure that the image filter module is installed with your NGINX. To check if the module is installed, run:

nginx -V 2>&1 | grep --color -o http_image_filter

If you see ‘http_image_filter’ in the output, the module is installed. If not, you will have to recompile NGINX as shown below:

# Step 1: Install Dependencies
sudo apt-get update
sudo apt-get install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev

# Step 2: Download NGINX Source
wget http://nginx.org/download/nginx-1.20.1.tar.gz
tar -xzvf nginx-1.20.1.tar.gz
cd nginx-1.20.1/

# Step 3: Configure NGINX with Image Filter Module
./configure --with-http_image_filter_module

# Step 4: Compile and Install NGINX
make
sudo make install

# Step 5: Start NGINX
sudo /usr/local/nginx/sbin/nginx

# Step 6: Verify Installation
/usr/local/nginx/sbin/nginx -V 2>&1 | grep --color -o http_image_filter

Basic Configuration

Let’s start by setting up a simple configuration that applies a predefined set of image transformations to every image in a given directory.

http {
    server {
        location /images/ {
            image_filter resize 300 200;
        }
    }
}

This snippet configures NGINX to resize all images in the ‘/images/’ directory to 300×200 pixels.

Advanced Configuration

You can also apply different transformations based on arguments in the request URL. For example, to dynamically resize images:

location ~* ^/dynamic-images/(?<width>\d+)-(?<height>\d+)/(?<file>.+)\.(?<extension>jpeg|jpg|gif|png)$ {
    set $width $arg_width;
    set $height $arg_height;
    image_filter resize $width $height;
}

With this configuration, a request to ‘/dynamic-images/300-200/photo.jpg’ will serve ‘photo.jpg’ resized to 300×200 pixels.

Caching Image Responses

To optimize performance, it’s important to cache the processed images. Here is an example of how to set up caching:

http {
    proxy_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=1g use_temp_path=off;

    server {
        location /images/ {
            image_filter resize 300 200;
            image_filter_jpeg_quality 90;
            image_filter_buffer 10M;

            proxy_cache my_cache;
            proxy_cache_valid 200 1d;
            proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
            proxy_cache_lock on;
            add_header X-Cache-Status $upstream_cache_status;
        }
    }
}

The above configuration sets up a cache zone, applies image transformations, enables caching of transformed images, and sets the cache validity.

Error Handling

In cases where image processing fails, you can specify a behavior such as returning a 404 error or falling back to the original image. For example:

location /images/ {
    image_filter resize 300 200;
    image_filter_buffer 10M;
    error_page 415 = /empty.gif;
}

This configuration returns an ’empty.gif’ whenever an image cannot be processed.

Testing Your Setup

After updating your NGINX configuration, you should test to make sure there are no syntax errors:

nginx -t

If the configuration test is successful, reload NGINX to apply the changes:

nginx -s reload

Finally, you can test your image transformations by accessing your images via the defined URLs to see the effects in real time.

Conclusion

Setting up image filters in NGINX provides a powerful way to serve optimized images to your users without relying on additional services or tools. Whether you need to accelerate your website’s speed by serving images of lower resolution or dynamically adjust images to fit different designs, NGINX’s image filter module can be an invaluable resource.