Ultra Image Server

A production grade docker-compose example for imgproxy with nginx caching.

Author: Mai Nhut Tan shin@shin.company
Copyright: 2021 AppSeeds https://code.shin.company/

Support my activities

If you like this repository, please hit the star button to follow further updates. Or buy me a coffee.

Why it's good

Just download and run.
Serve local files as well as ANY public origin.
High performance with nginx caching.
No complex Image URL signature settings but stay secure.
Auto convert to .webp or .avif format if browser supports.
Customizable image presets without exposing imgproxy options.
Customizable origin server for every URL.
Customizable fallback image for every URL.
Supports SSL and HTTP/2 (with your own SSL certs).

Getting started

Put your files

Please put your files to be served in the folder www.

There are some sample files here (such the watermark, or some noimage fallback images).

Start the server

docker-compose up -d --build --remove-orphans --force-recreate

That's all.

Configurations

All settings for handling image URLs are writen in the imgproxy.conf file using Nginx's map directives.

$use_imgproxy
Indicates that the request should be proceeded by imgproxy.

$imgproxy_cache
Default cache zone for imgproxy.

$origin_name
Parse origin name from the URI. Origin name starts with an @ symbol (Eg. @pinterest).

$preset_name
Parse preset name from the URI. Preset name may start with a dash (_) symbol (such as _thumb or _w300).

$original_host
Select origin base URL from parsed origin name.

$original_uri
Parse real origin URI of the file, omit origin name and preset name in the URI if they exist.

$fallback_uri
Select fallback file (which is stored in the www folder) to serve when requested URI is unavailable (Eg: /noimage.jpg).

$imgproxy_options
Define imgproxy options for each preset name.

$imgproxy_extension
Detect WEBP or AVIF supports from a request header called Accept.

$imgproxy_rewrite
Generate final imgproxy URL. Without using URL signature, it may help boosting the performance a little.

$debug_imgproxy_rewrite
For debugging the value of $imgproxy_rewrite.

I keep the configurations in very simple variables. You can also make your own version from this base.

If you like this repository, please hit the star button or support my works.

Enabling SSL

Put server.crt and server.key for your domain in the folder certs.

Open the file nginx/nginx.conf and uncomment 4 lines right after the # SSL line.

# SSL
listen 443 ssl http2 reuseport;
listen [::]:443 ssl http2 reuseport;
ssl_certificate     /etc/nginx/certs/server.crt;
ssl_certificate_key /etc/nginx/certs/server.key;

Then run the command in the Start the server section to recreate the web server again.

Example

Note: the image source is from Pinterest, it may be unavailable in the future.

Image with no preset (it is resized to max-width=1600 as default). http://localhost/@pinterest/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

The image with preset _w200 applied. http://localhost/@pinterest/_w200/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

The image with preset _thumb applied. http://localhost/@pinterest/_thumb/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

The image with preset _small applied. http://localhost/@pinterest/_small/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

The image with preset _square applied. http://localhost/@pinterest/_square/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

The image with preset _medium applied. http://localhost/@pinterest/_medium/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg

Custom URL parameters:

We can use a URL query to modify some requests.

skip=1
Skip the request from imgproxy processing. This works with local files.

nocache=1
By pass Nginx caching for current request.

bypass=1
Disable Nginx caching for current request.

Debugging

You can add a query ?debug=1 to your image URL for debugging imgproxy's options.

For example:

curl -Isk 'http://localhost/@pinterest/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg?debug=1'

And you will see an X-Debug header contains parameters that were passed to imgproxy.

HTTP/1.1 200 OK
Server: nginx
Content-Type: image/webp
X-Debug: /unsafe/s:1600:0:0:0/preset:logo/plain/https://i.pinimg.com/originals/fe/85/88/fe85885e1fba1a778c53ea43d694368f--fuji-mirror-mirror.jpg@webp

Flushing cache files

Just remove the folder cache then run the command in the Start the server section to restart the web server again.

From Vietnam 🇻🇳 with love.

phamquocbuu/docker-imgproxy