modjpeg-nginx

Nginx filter module for adding overlays on JPEGs on-the-fly with libmodjpeg.

With libmodjpeg you can overlay a (masked) image onto an existing JPEG as lossless as possible. Changes in the JPEG only take place where the overlayed image is applied. All modifications happen in the DCT domain, thus the JPEG is decoded and encoded losslessly.

Typical Uses
Try it out
Installation
Compatibility
Synopsis
Directives
License
Acknowledgement

Typical Uses

This filter module can add overlays (e.g. a logo, visual watermark) on JPEGs when they are requested.

A few ideas:

Consider you are a photographer and have a image gallery on your website. Without hardcoding your logo (brand, watermark, ...) into these images you can apply it the moment the image is requested. Whenever you update your logo, just update the nginx configuration and it's done. No need to re-process all your images.
You have an online shop with thousands of product images. With just configuring nginx you can add your logo to all of the product images. You don't have to process all product images.
You have a paid service. Add a watermark to all images if the user is not subscribed. If the user is subscribed, don't apply the watermark or put just a small logo on the images without touching the original images.
On your website, registered users can upload images. Add the avatar of the user to the image who uploaded the image without processing it after the upload. If the user changes her avatar, all her images will automatically have the new avatar on them.

Try it out

In order to try out this filter module, pull the docker image

docker pull ioppermann/modjpeg-nginx:latest

The docker container exposes TCP port 80 and expects a directory with images mounted on /images, e.g.

docker run -it --rm --name=modjpeg-nginx \
   --mount type=bind,src=$PWD/images,dst=/images,readonly \
   -p 8080:80 \
   ioppermann/modjpeg-nginx:latest

Now you can browse to http://localhost:8080/ and click on the listed images. The modjpeg logo will be applied in the top left corner. By default only images that are smaller than 10MB are processed by the filter. Stop the container by pressing Ctrl-c.

The filter can be controlled by these environment variables:

Name	Default	Description
MJ_GRACEFUL	on	See jpeg_filter_graceful
MJ_BUFFER	10M	See jpeg_filter_buffer
MJ_MAX_PIXEL	0	See jpeg_filter_max_pixel
MJ_DROPON_ALIGN	"top left"	See jpeg_filter_dropon_align
MJ_DROPON_OFFSET	"0 0"	See jpeg_filter_dropon_offset
MJ_DROPON_FILE	"/usr/local/nginx/conf/dropon.png"	See jpeg_filter_dropon_file

The following example will allow images with up to 150 megapixel (MJ_MAX_PIXEL) and 100MB in file size (MJ_BUFFER). The logo will be placed in bottom right corner (MJ_DROPON_ALIGN) with an offset of -15px horizontally and vertically (MJ_DROPON_OFFSET).

docker run -it --rm --name=modjpeg-nginx \
   --mount type=bind,src=$PWD/images,dst=/images,readonly \
   -p 8080:80 \
   -e MJ_MAX_PIXEL=150000000 \
   -e MJ_BUFFER=100M \
   -e MJ_DROPON_ALIGN="bottom right" \
   -e MJ_DROPON_OFFSET="-15 -15" \
   ioppermann/modjpeg-nginx:latest

In order to change the logo, you can mount an additional volume or put it into the directory you already mount, e.g.

docker run -it --rm --name=modjpeg-nginx \
   --mount type=bind,src=$PWD/images,dst=/images,readonly \
   -p 8080:80 \
   -e MJ_DROPON_FILE="/images/logo.png" \
   ioppermann/modjpeg-nginx:latest

Installation

CentOS / RedHat 7 packages

An easy way to use the module in CentOS or RedHat 7, is to use precompiled dynamic nginx module. It is built for nginx stable. The repository includes latest stable nginx, the jpeg module, libmodjpeg and libpng16 dependencies:

yum -y install https://extras.getpagespeed.com/release-el7-latest.rpm
yum install nginx nginx-module-jpeg

Compilation

For using the modjpeg-nginx filter module, follow these steps:

Clone and install libmodjpeg (libjpeg and cmake are required)
Clone this repository
Download and extract the latest nginx
Configure, compile, and install nginx

# Clone and install libmodjpeg
git clone https://github.com/ioppermann/libmodjpeg.git
cd libmodjpeg
cmake .
make
make install
cd ..

# Clone modjpeg-nginx
git clone https://github.com/ioppermann/modjpeg-nginx.git

# Download and install nginx
wget 'http://nginx.org/download/nginx-1.19.2.tar.gz'
tar -xvzf nginx-1.19.2.tar.gz
cd nginx-1.19.2

# Configure as static module, or ...
./configure --add_module=../modjpeg-nginx

# ... configure as dynamic module (as of nginx 1.9.11)
./configure --add_dynamic_module=../modjpeg-nginx

# If the libmodjpeg library is not found, add e.g. '--with-ld-opt=-L/usr/local/lib' to
# the configure options if it was installed to /usr/local/lib

# You may want to use the other './configure' options that are used
# in your current nginx build. Check the output of 'nginx -V'.

make
make install

If you configured modjpeg-nginx as dynamic module, you have to load the module in the beginning of the config

...
load_module modules/ngx_http_jpeg_filter_module.so;
...

Compatibility

This module has been tested with the following versions of nginx:

1.26.2
1.24.0
1.22.1
1.20.2
1.19.2
1.18.0
1.17.6
1.16.1
1.15.3
1.14.0
1.13.10
1.12.2
1.10.3
1.8.1 (only as static module)

Synopsis

   ...

   location /gallery {
      # enable jpeg filter module
      jpeg_filter on;

      # limit image sizes to 9 megapixel
      jpeg_filter_max_pixel 9000000;

      # limit image file size to 5 megabytes
      jpeg_filter_buffer 5M;

      # deliver the images unmodified if one of the limits apply
      jpeg_filter_graceful on;

      # pixelate the image
      jpeg_filter_effect pixelate;

      # add a masked logo in the bottom right corner
      # with a distance of 10 pixel from the border
      jpeg_filter_dropon_align bottom right;
      jpeg_filter_dropon_offset -10 -10;
      jpeg_filter_dropon_file /path/to/logo.jpg /path/to/mask.jpg;
   }

   ...

Or use it with OpenResty's ngx_http_lua_module and a PNG logo:

   ...

   location /gallery {
      set_by_lua_block $valign {
         local a = { 'top', 'center', 'bottom' }
         return a[math.random(#a)]
      }

      set_by_lua_block $halign {
         local a = { 'left', 'center', 'right' }
         return a[math.random(#a)]
      }

      # enable jpeg filter module
      jpeg_filter on;

      # limit image sizes to 9 megapixel
      jpeg_filter_max_pixel 9000000;

      # limit image file size to 5 megabytes
      jpeg_filter_buffer 5M;

      # deliver the images unmodified if one of the limits apply
      jpeg_filter_graceful on;

      # pixelate the image
      jpeg_filter_effect pixelate;

      # add a logo in a random position
      jpeg_filter_dropon_align $valign $halign;
      jpeg_filter_dropon_file /path/to/logo.png;
   }

   ...

Or generate a logo with Lua-GD:

http {
   ...
   lua_package_cpath '/usr/local/lib/lua/5.1/?.so;;';
   ...
   server {
      ...
      location /gallery {
      	   set_by_lua_block $logobytestream {
              local gd = require "gd"

              local im = gd.create(210, 70)
              local white = im:colorAllocate(255, 255, 255)
              local black = im:colorAllocate(0, 0, 0)
              im:filledRectangle(0, 0, 140, 80, white)
              im:string(gd.FONT_LARGE, 10, 10, "Hello modjpeg", black)
              im:string(gd.FONT_LARGE, 10, 40, os.date("%c"), black);
              return im:jpegStr(85)
      	   }

   	   # enable jpeg filter module
   	   jpeg_filter on;

           # limit image sizes to 9 megapixel
           jpeg_filter_max_pixel 9000000;

           # limit image file size to 5 megabytes
           jpeg_filter_buffer 5M;

           # deliver the images unmodified if one of the limits apply
           jpeg_filter_graceful on;

           # pixelate the image
           jpeg_filter_effect pixelate;

           # add a generated logo in the bottom right corner
           # with a distance of 10 pixel from the border
           jpeg_filter_dropon_align bottom right;
           jpeg_filter_dropon_offset -10 -10;
           jpeg_filter_dropon_memory $logobytestream;
      }
      ...
   }
   ...
}

jpeg_filter

Syntax: jpeg_filter on | off

Default: jpeg_filter off

Context: location

Enable the jpeg filter module.

This directive is turned off by default.