Home

ngx_small_light

ngx_small_light is a dynamic image transformation module for nginx. And ngx_small_light is written for using as the same way as mod_small_light as possible in nginx.(mod_small_light is a Apache module)

Install

Install Dependencies

Before install ngx_small_light( and nginx), install following dependencies.

• PCRE (required)
• ImageMagick (required)
• Imlib2 (optional)
• GD (optional)

Install ngx_small_light

cd ${ngx_small_light_src_dir}
./setup
cd {$nginx_src_dir}
./configure --add-module=${ngx_small_light_src_dir}
make
sudo make install

If you want to enable the libraries expect ImageMagick in ngx_small_light, add following options when executing setup. (ImageMagick is always enabled)

./setup --with-imlib2           # enable ImageMagick and Imlib2
./setup --with-gd               # enable ImageMagick and GD
./setup --with-imlib2 --with-gd # enable ImageMagick and Imlib2 and GD

Quick Start

Add following configuration to some server context in nginx.conf and start nginx.

small_light on;
location ~ small_light[^/]*/(.+)$ {
    set $file $1;
    rewrite ^ /$file;
}

If you can get the original image of image.jpg from following URL,

http://$host:$port/img/image.jpg

you will be able to get the converted image of image.jpg from following URL.

http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg

Configuration

The configuration guide explains how to describe a configuration to nginx.conf and about configuratve parameters.

Supporting Formats

ngx_small_light supports JPEG, GIF, PNG, WebP.

But the translation by Imlib2 does not support to write GIF-image. Because Imlib2 has the function for loading GIF-image but does not have the function for saving. And the translation by Imlib2 does not support to write and read WebP-image.

So of=gif and e=imlib2 are not enabled to specify at once.

If these are specified, ngx_small_light return 415(Unsupported Media Type).

Using GET parameters

ngx_small_light supports to convert image not only by a specific pattern-url of small_light but by GET paramenters from v0.5.0. You need to set both small_light and small_light_getparam_mode 'on' to enable this feature. At the expense of enabling this feature, a specific pattern-url of small_light is disabled.

small_light on;
small_light_getparam_mode on;

In above configuration, the following url does not return converted image.

http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg

Instead the following url returns converted image expected by right.

http://localhost:8000/img/image.jpg?dw=200&dh=200

Optimizing Tips

When the output format is JPEG and image-converting engine is ImageMagick or Imlib2, you may give 'y' to the parameter jpeghint. The speed of processing images is improved dramatically.

And when image-converting engine is ImageMagick, giving 1 to OMP_NUM_THREADS in nginx.conf is recommended strongly. Because OpenMP is enabled in ImageMagick by default and ImageMagick enabled OpenMP is very slow on multi-process environment.

env OMP_NUM_THREADS=1;