Deploying an Open-Source Image Cropping Service: Thumbor with Docker

Thumbor is an intelligent image service open-sourced on GitHub that supports on-demand cropping, resizing, filter application, and image optimization. Users familiar with object storage services know that providers often offer additional image processing features like cropping and watermarking. With Thumbor, you can build a similar image processing service yourself.

Thumbor is developed in Python 3 and offers multiple installation methods. This article shares how to deploy an open-source image cropping service using Docker.

Preparation & Installing Docker

If you haven't installed Docker yet, refer to my previous article: Installing Docker and Common Docker Commands on Linux.

It is also recommended to install Docker Compose for easier maintenance:

# Download docker-compose
curl -L "https://github.com/docker/compose/releases/download/1.25.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# Add execution permissions
chmod +x /usr/local/bin/docker-compose
# Create a symbolic link
ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

Installing Thumbor with Docker

The official documentation provides a very simple command to run Docker Thumbor with just one line:

docker run -p 8888:80 minimalcompact/thumbor

After successful execution, you can visit http://IP:8888/unsafe/275x0/https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png to crop an image. Here:

• 275 refers to the cropped width in pixels.
• 0 refers to the cropped height, where 0 means adaptive.
• The final part is the URL of the image to be cropped, in this case, Baidu's logo.

However, for normal usage, I do not recommend using the command above directly. Although simple, it lacks many custom parameter settings. Next, I will organize some parameters I use for your reference.

Installing Thumbor with Docker Compose

For easier maintenance, it is recommended to use Docker Compose. First, create a directory mkdir thumbor.

Then, create a Thumbor configuration file named thumbor.conf in this directory with the following parameters:

# Maximum cropping width, meaning cropped images will not exceed this pixel value, default is 0 (no limit)
MAX_WIDTH = 1200
# Maximum cropping height, meaning cropped images will not exceed this pixel value, default is 0 (no limit)
MAX_HEIGHT = 800
# Minimum cropping width, meaning cropped images will not be lower than this pixel value, default is 1
MIN_WIDTH = 50
# Minimum cropping height, meaning cropped images will not be lower than this pixel value, default is 1
MIN_HEIGHT = 50
# Allowed domains for cropping images, supports regular expressions and multiple images
ALLOWED_SOURCES = ['.+\.baidu\.com', '.+\.bmp\.ovh']
# Image quality, default is 80
QUALITY = 80
# Number of seconds the image should be kept in browser cache. It is directly related to Expires and Cache-Control headers
MAX_AGE = 7 * 24 * 60 * 60
# It is convenient to set a much lower expiration time for the image cache when errors or delayed queuing occur during detection. This allows browsers to request the correct image faster.
MAX_AGE_TEMP_IMAGE = 60
# Which engine to save the cropped image to, below refers to saving to local storage for caching
RESULT_STORAGE = 'thumbor.result_storages.file_storage'
# Original image storage time
STORAGE_EXPIRATION_SECONDS = 864000
# Cropped image storage time
RESULT_STORAGE_EXPIRATION_SECONDS = 864000
# Where to save the cropped image
RESULT_STORAGE_FILE_STORAGE_ROOT_PATH = '/tmp/thumbor/result_storage'
# Enable result cache (cache for cropped images)
RESULT_STORAGE_STORES_UNSAFE = True

Thumbor has many other configurations; interested users can refer to the official documentation: https://thumbor.readthedocs.io/en/latest/configuration.html

Next, create a docker-compose.yml file in the thumbor directory with the following content:

version: '3.3'
services:
    thumbor:
        ports:
            - '8888:80'
        restart: always
        container_name: thumbor
        volumes:
            - './thumbor.conf:/app/thumbor.conf'
            - './result_storage:/tmp/thumbor/result_storage'
            - './storage:/tmp/thumbor/storage'
        image: minimalcompact/thumbor

Then run the command docker-compose up -d to start the container. You can now use the method mentioned above to crop images by visiting http://IP:8888/unsafe/275x0/https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png.

Nginx Reverse Proxy

After deploying the above method, access is done via IP + Port, which obviously does not meet production requirements. We can use Nginx reverse proxy to access via domain name and image mirroring. An example configuration is as follows:

server {
        listen 80;
        server_name youdomain.com;

        access_log /data/wwwlogs/youdomain.com_nginx.log combined;

        location / {
                proxy_http_version 1.1;
                proxy_set_header Connection "";
                #chunked_transfer_encoding off;
        proxy_pass http://127.0.0.1:8888;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
}

Additionally, you can configure anti-leech rules in Nginx based on actual requirements. Reference: Nginx Setting Image Anti-Leech (Whitelist and Blacklist).

Summary

• Thumbor offers multiple installation methods; deploying via Docker is simple and easy to maintain.
• For production use, customize Thumbor parameters according to your scenario.
• You can configure domain access and anti-leech restrictions via Nginx reverse proxy.

---

• Thumbor Official Website: http://www.thumbor.org/
• Thumbor Documentation: https://thumbor.readthedocs.io/en/latest/
• Thumbor Project Address: https://github.com/thumbor/thumbor

Similar services include: https://docs.imgproxy.net/