jpeg: NGINX JPEG filter module

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

RedHat Enterprise Linux 7, 8, 9
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 and Amazon Linux 2023

CentOS/RHEL 7 and Amazon Linux 2CentOS/RHEL 8, 9 and Fedora Linux, Amazon Linux 2023, etc.

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm 
yum -y install nginx-module-jpeg

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

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_jpeg_filter_module.so;

This document describes nginx-module-jpeg v1.0.1 released on Sep 04 2018.

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
jpeg_filter
jpeg_filter_max_pixel
jpeg_filter_buffer
jpeg_filter_optimize
jpeg_filter_progressive
jpeg_filter_arithmetric
jpeg_filter_graceful
jpeg_filter_effect
jpeg_filter_dropon_align
jpeg_filter_dropon_offset
jpeg_filter_dropon_file
jpeg_filter_dropon_memory
Notes
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

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.15.1.tar.gz' tar -xvzf nginx-1.15.1.tar.gz cd nginx-1.15.1

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

```nginx
...
load_module modules/ngx_http_jpeg_filter_module.so;
...

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 {
   ...
   ...
   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.