Hosting

Let’s see how would you run thumbor in different environments.

Development Environment

For local development, put thumbor.conf in the current working directory, the current user’s home directory, or /etc/thumbor.conf. If no file exists in those locations, thumbor uses the configuration bundled with the installed package. You can select another file with -c or --conf; see Configuration for the complete lookup order.

To verify if you have thumbor, just type:

thumbor --version

It should return the version you’ve installed. Starting thumbor is as easy as:

thumbor

For more options check the Configuration page.

Production Environment

Other than having the proper Configuration file for your environment, we have some recommendations on how to run thumbor in production.

Our first recommendation is to run more than one instance of it. You can specify different ports using thumbor easily. This will make sure that your service stays responsive even if one of the processes die.

We also recommend having some form of load balance that distributes the load between the aforementioned processes. We are using NGINX to do it, but there are more sophisticated load balance softwares around. thumbor supports health checking under the /healthcheck URI if you need to use it.

Other than that, you run it using the thumbor console app specifying the arguments, like this:

thumbor --port=8888 --conf="$HOME/mythumbor.conf"

We recommend using an application such as Supervisor (http://supervisord.org/index.html) to monitor your services. An example of a supervisord.conf file would be:

[supervisord]
logfile = /home/thumbor/logs/supervisord.log
logfile_maxbytes = 50MB
logfile_backups=10
loglevel = info
pidfile = /home/thumbor/supervisord.pid
user = thumbor

[program:thumbor]
command=thumbor --port=800%(process_num)s --conf=/etc/thumbor800%(process_num)s.conf
process_name=thumbor800%(process_num)s
numprocs=4
user=thumbor
directory=/home/thumbor/
autostart=true
autorestart=true
startretries=3
stopsignal=TERM
stdout_logfile=/home/thumbor/logs/thumbor800%(process_num)s.stdout.log
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=10
stderr_logfile=/home/thumbor/logs/thumbor800%(process_num)s.stderr.log
stderr_logfile_maxbytes=1MB
stderr_logfile_backups=10

This configuration file makes sure that supervisor starts 4 processes of thumbor on the 8000, 8001, 8002 and 8003 ports, each with a different configuration file (thumbor8000.conf, thumbor8001.conf, thumbor8002.conf, thumbor8003.conf all under /etc folder). The other settings are optional, but if you need help with supervisor’s settings it has extensive documentation online (http://supervisord.org/introduction.html).

Thumbor in the Cloud

Running with Docker

Running thumbor with an official Docker image is very straightforward. An official image is built and hosted on GitHub Container Registry.

docker run -p 8888:8888 ghcr.io/thumbor/thumbor:latest

To verify thumbor is running, you can check the health endpoint:

curl http://localhost:8888/healthcheck

For more information about the official Docker image, visit the GitHub Container Registry.

Configuring the Docker Image

The official image uses thumbor as its entry point. Pass thumbor command-line arguments after the image name.

To use a configuration file, mount it at one of thumbor’s normal lookup locations:

docker run -p 8888:8888 \
  -v /path/to/thumbor.conf:/etc/thumbor.conf:ro \
  ghcr.io/thumbor/thumbor:latest

Alternatively, mount it at another location and select it explicitly:

docker run -p 8888:8888 \
  -v /path/to/thumbor.conf:/opt/thumbor/thumbor.conf:ro \
  ghcr.io/thumbor/thumbor:latest \
  --conf=/opt/thumbor/thumbor.conf

The official image does not translate THUMBOR_* environment variables into thumbor configuration. If you explicitly enable the core legacy environment mode, use exact, unprefixed configuration names and remember that their values remain strings; see Configuration.

Generate a template with thumbor-config > thumbor.conf on an installed copy of thumbor.

For more detailed configuration options, see the Configuration documentation.

Docker Compose configuration

For string settings, enable environment overrides in Compose with:

services:
  thumbor:
    image: ghcr.io/thumbor/thumbor:latest
    ports:
      - "8888:8888"
    command: ["--use-environment=True"]
    environment:
      SECURITY_KEY: "replace-with-your-own-key"

The command list supplies arguments to the image’s thumbor entrypoint. Quote environment values so Compose treats them as strings.

For settings that need other types, use the Python configuration example in Converting environment values and mount it as follows:

services:
  thumbor:
    image: ghcr.io/thumbor/thumbor:latest
    ports:
      - "8888:8888"
    command: ["-c", "/etc/thumbor.conf"]
    environment:
      SECURITY_KEY: "replace-with-your-own-key"
      UPLOAD_ENABLED: "true"
      UPLOAD_DELETE_ALLOWED: "false"
      UPLOAD_PUT_ALLOWED: "false"
      QUALITY: "85"
    volumes:
      - ./thumbor.conf:/etc/thumbor.conf:ro

Here the file reads SECURITY_KEY as a string and converts the other values to Python booleans and integers. Keep --use-environment out of this command to preserve those types.

Thumbor on OpenShift

Warning

This may be outdated since thumbor moved to python 3.

There’s a project showing how to deploy a working version on OpenShift https://github.com/rafaelcaricio/thumbor-openshift-example

Thumbor behind CloudFront

Warning

This may be outdated since thumbor moved to python 3.

The awesome people at yipit are using thumbor behind the CloudFront CDN at Amazon.

The detailed information on how to do it can be seen at this blog post.