Skip to content
Projects

niiknow/docker-nginx-image-proxy

View on GitHub

niiknow/docker-nginx-image-proxy has 111 GitHub stars and 32 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 21:59 UTC. Last push 2026-11-13.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

on the fly image cropping with gravity, resize and compression microservice

Developer Tools

README.md

Original

nginx image proxy

High Performance and Low Resource Utilization Microservice

image cropping with gravity, resize and compress on the fly with nginx image_filter module. A tiny docker container to build your own Cloudinary-like service.

Nginx module - https://github.com/niiknow/docker-nginx-image-proxy/blob/master/build/ngx_http_image_filter_module.c

Original File - https://github.com/niiknow/docker-nginx-image-proxy/blob/master/build/src/http/modules/ngx_http_image_filter_module.c

Patch creation: diff -u build/src/http/modules/ngx_http_image_filter_module.c build/ngx_http_image_filter_module.c > build/image_filter.patch

Patch apply with: patch src/http/modules/ngx_http_image_filter_module.c image_filter.patch

Features:

  • image crop offset, credit: https://github.com/bobrik/nginx_image_filter
  • /healthcheck endpoint
  • empty gif on other errors: 403, 404, 415, 422, 500, 502, 503, 504 - the original status code is kept so <img onerror> handlers still fire; remove the error_page ... @empty_gif line in sites-enabled/1-resize.conf to return plain errors instead
  • precise image errors, with the reason in the X-ImageProxy-Error response header:
    • 502 - origin did not return an image (e.g. an HTML login/error page)
    • 415 - origin returned an image format that cannot be processed (e.g. svg, avif, heic); supported formats are jpeg, png, gif, webp, bmp and tiff
    • 422 - supported format, but the image is corrupt or larger than image_filter_buffer
  • origin urls are passed through exactly as encoded by the client, so +, %2B, %20, = etc. in origin paths and query strings are preserved
  • convert/force output to another format, support formats: bmp, jpg, png, gif, webp, and tiff
  • use custom ssl and saved config when you mount '/app' volume. nginx logs has also been redirect so you can backup, such as aws s3 sync. Just delete the default redirect to stdout/access.log and stderr/error.log files.
  • support international characters in URL
  • automatically follow redirect at origin
  • overridable nginx config - easily add secure link or additional nginx config
  • watermark with
# file must be png
image_filter_water_image /path/to/file/watermark.png;

# optional watermark positioning
image_filter_water_pos [ top-left | top-right | center | bottom-left | bottom-right (default)];

TIP: The implementation of watermark feature, at the moment, is a very naive one. Due to limited functionality, it add watermark after the image has been resized. It work best when resize to smaller image/thumbnail and use in combination of a smaller watermark image. We may expand on the functionality in the future, if we have time.

  • resize support image scale (enlarge image)
# optional scale max ratio, default 1
# becareful not to set this too high or it will use too much memory.
# 
# For example (during testing) a 200KB JPEG file (1024x768) will take up 4MB of memory 
# when loaded; but when resampled to twice (2x) of image size, the memory use jumps to 20.1MB
# Mathematically make sense: 4MB * 2(Dimensions xy) = 4MB * 2 * 2 = 16MB (new) + 4MB (original) = 20MB
image_filter_scale_max 3;

What does this solve?

You have a huge repository of images that need dynamic resize and cropping. Cloudinary can be expensive and redundant if you run your own CDN in front of this microservice.

And what it doesn't?

Unlike other libraries, this does not try to do every image transformation and/or caching.

  1. For more advanced features such as: animated gif, face detection, auto image optimization, and others; we recommend using Cloudinary or similar service.
  2. Outside of disk cache, there is no plan for other Caching methods. We recommend putting a CDN in front, such as (MaxCDN/StackPath/KeyCDN), to provide caching and easy SSL. We love StackPath/MaxCDN EdgeRules™.
  3. If you want thumbnail caching to s3, just write a lambda function and use this server to generate your thumbnail. Upload the result to s3 with the same function.

build

To achieve smaller/tiny microservice, this container utilize multi-stage build introduced in Docker 17.06; therefore, Docker 17.06+ is required to build.

docker build -t nginx-image-proxy .

The image is built for linux/amd64 only (the platform is pinned in the Dockerfile), so it runs on x86 servers. On an Apple Silicon Mac the build runs under emulation: in Docker Desktop turn off Settings > General > Use Rosetta for x86_64/amd64 emulation first, because Rosetta cannot run the Ubuntu 26.04 tar used during the build (QEMU can). Expect the build to be slower than a native one.

run

docker run -d --restart=always -p 80:80 niiknow/nginx-image-proxy --env SERVER_CONF='https://gist.githubusercontent.com/...'

web

Example: http://imageproxy.yourdomain.com/rx/url-options/http://remote-host.com/image-path/image.jpg

or http as protocol default: http://imageproxy.yourdomain.com/rx/url-options/remote-host.com/image-path/image.jpg

Option Keys:

code: name - valid values - default
  q: quality - 1..100 - 96 (default to best in case it's previously optimized) 
  w: width - uint - null
  h: height - uint - null
  c: crop - null, 1 - null
  rz: resize - null, 1 - 1
  g: gravity - NorthWest, North, NorthEast, West, Center, East, SouthWest, South, SouthEast *case-sensitive* - NorthWest
  e: sharpen - 1..100 - 0
  r: rotate - 0, 90, 180, 270 - 0
  ofmt: bmp, jpg, jpeg, png, gif, webp - force output format

Options Usages:

Options are a subset of Cloudinary. It's also very flexible and customizable.

  • Like Cloudinary with underscore (_) as separator: OptionKey_OptionValue - g_Center, w_100, h_100
  • Or without any separator: OptionKeyOptionValue - gCenter, w100, h100
  • Or in a QueryString: ?g=Center&w=100&h=100

And if that doesn't work, you can always use your custom nginx config by passing the config url into docker environment variable: SERVER_CONF

If the SERVER_CONF url cannot be downloaded (404, unreachable, ...), the container stops at startup with an error message instead of running with a broken config.

Site configuration

Image resizing is a shared internal service in sites-enabled/1-resize.conf (listening on 127.0.0.1:9082), the same way GeoIP is served by sites-enabled/1-geoip.conf. It holds everything that is not site specific: option parsing, cache, redirects, error handling and the origin host allow-list.

A site only needs its own server block (listen, ssl, server_name, ...) and one include to expose /rx/<options>/<image url>:

server {
    listen      80;
    server_name images.example.com;

    include /etc/nginx/resize.conf;
}

See sites-enabled/server-conf.example. All sites share the same resize cache. An older all-in-one server.conf (with its own /rx/ location) keeps working alongside 1-resize.conf.

Security: restrict origin hosts

Out of the box, the resize service (sites-enabled/1-resize.conf) will fetch and resize images from any host given in the URL. That makes it an open proxy, and it can also reach hosts that should not be public, such as 127.0.0.1, private networks (10.x, 172.16.x, 192.168.x) or cloud metadata endpoints (169.254.169.254). Responses that are not images are rejected (502), but internal images can still be fetched and the requests themselves are still made.

For production, enable the host allow-list in sites-enabled/1-resize.conf (it applies to every site) and list only your own origin hosts:

if ($myhost !~ ".*(images.example.com|cdn.example.org)$") {
    set $image_uri "";
    set $debugkey "$myhost=denied";
    return 403;
}

Example

December 2021 Update

We're still using this project so maintenance and security update continues until further notice, but we're no longer adding new feature. We're also taking down example server so demo images above may not work in the future.

Point of Interest

  • images.weserv.nl is another great project to look at if you need additional features with image resizing. The original purpose of this library (nginx-image-proxy) is to provide high performance and low resource utilization image private microservice. We searched high and low but did not find a good solution. At that time, we saw great potential with images.weserv.nl, but was held back because it was using php. Since July 2018, it was rewritten with lua and direct c binding; as a result, it has became the next best solution and continue to improve. The authors also generiously provide free endpoint for public use. This help prove their implementation to be well battle-tested for use in any production environment.

Update, as of September 2019, images.weserv.nl was rewritten again as C++ so it has now became the better/best choice. We are now sun-setting this project, only maintenance and security support - no new feature, for the future date of December 2021 or 2 years from December 2019.

MIT