This short guide covers the necessary steps to install and use Thumbor in a container. The container can be run using Docker or Podman Container runtime engine. Thumbor is a powerful open-source image processing server that can load images from a MinIO bucket and dynamically resize, crop, or optimize them.
Docker or Podman should be installed in your system. Refer to our external links for the installation process:
You can check for the versions installed using:
- For Docker
docker ---version
- For Podman
podman --version
Output example:
podman version 4.9.3
To start Thumbor container and run it in the background run:
- Docker commands:
podman run -d --name thumbor -p 8000:8000 minimalcompact/thumbor
- Podman commands:
docker run -d --name thumbor -p 8000:8000 minimalcompact/thumbor
Download and container starting process output:
Trying to pull ghcr.io/minimalcompact/thumbor:latest...
Getting image source signatures
Copying blob d870c456a0c1 done |
Copying blob a47cff7f31e9 done |
Copying blob cdd62bf39133 done |
Copying blob 01272fe8adba done |
Copying blob a173f2aee8e9 done |
Copying blob 3abb900560fd done |
Copying blob 3e89315f3326 done |
Copying blob cf1fd6ac8b82 done |
Copying blob f5d1f0fd3b13 done |
Copying blob 6524a480d63a done |
Copying blob 4038c8413a46 done |
Copying blob fdaf785ffc9e done |
Copying blob 4f4fb700ef54 done |
Copying blob e4909b5e91ac done |
Copying config 50ddd4c979 done |
Writing manifest to image destination
6153f5e2016ed99db7dace79a8285d0fef502219cee5c18dfbdda738ae966ce3
User podman ps or docker ps to check container status:
$ podman ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
6153f5e2016e ghcr.io/minimalcompact/thumbor:latest thumbor --port=$T... 14 minutes ago Up 14 minutes 0.0.0.0:8000->80/tcp thumbor
Creating custom configuration / data path
Create data and configuration files directories:
mkdir -p ~/thumbor/{conf,data}
Create configuration file locally that will be mounted to the container:
nano ~/thumbor/conf/thumbor.conf
Inside the container, the configuration file is located in /app/thumbor.conf. The local one should be mapped to relevant path inside the container.
You can customize below Thumbor configuration file to your desired values.
################################### Logging ####################################
## Logging configuration as json
## Defaults to: None
THUMBOR_LOG_CONFIG = None
## Log Format to be used by thumbor when writing log messages.
## Defaults to: %(asctime)s %(name)s:%(levelname)s %(message)s
THUMBOR_LOG_FORMAT = '%(asctime)s %(name)s:%(levelname)s %(message)s'
## Date Format to be used by thumbor when writing log messages.
## Defaults to: %Y-%m-%d %H:%M:%S
THUMBOR_LOG_DATE_FORMAT = '%Y-%m-%d %H:%M:%S'
################################################################################
################################### Imaging ####################################
## Max width in pixels for images read or generated by thumbor
## Defaults to: 0
MAX_WIDTH = 0
## Max height in pixels for images read or generated by thumbor
## Defaults to: 0
MAX_HEIGHT = 0
## Max pixel count for images read by thumbor. Set to prevent decompression bomb DOS attack.
## Defaults to: 75000000 pixels
MAX_PIXELS = 75000000
## Min width in pixels for images read or generated by thumbor
## Defaults to: 1
MIN_WIDTH = 1
## Min width in pixels for images read or generated by thumbor
## Defaults to: 1
MIN_HEIGHT = 1
## Allowed domains for the http loader to download. These are regular
## expressions.
## Defaults to: []
ALLOWED_SOURCES = []
## Quality index used for generated JPEG images
## Defaults to: 80
QUALITY = 80
## Exports JPEG images with the progressive flag set.
## Defaults to: True
PROGRESSIVE_JPEG = True
## Specify subsampling behavior for Pillow (see `subsampling` in
## http://pillow.readthedocs.org/en/latest/handbook/image-file-
## formats.html#jpeg).Be careful to use int for 0,1,2 and string for "4:4:4"
## notation. Will ignore `quality`. Using `keep` will copy the original file's
## subsampling.
## Defaults to: None
PILLOW_JPEG_SUBSAMPLING = None
## Specify quantization tables for Pillow (see `qtables` in
## http://pillow.readthedocs.org/en/latest/handbook/image-file-
## formats.html#jpeg). Will ignore `quality`. Using `keep` will copy the
## original file's qtables.
## Defaults to: None
PILLOW_JPEG_QTABLES = None
## Specify resampling filter for Pillow resize method.One of LANCZOS, NEAREST,
## BILINEAR, BICUBIC, HAMMING (Pillow>=3.4.0).
## Defaults to: 'LANCZOS'
PILLOW_RESAMPLING_FILTER = 'LANCZOS'
## Quality index used for generated WebP images. If not set (None) the same level
## of JPEG quality will be used.
## Defaults to: None
WEBP_QUALITY = None
## Compression level for generated PNG images.
## Defaults to: 6
PNG_COMPRESSION_LEVEL = 6
## Specifies whether WebP format should be used automatically if the request
## accepts it (via Accept header)
## Defaults to: False
AUTO_WEBP = False
## Specifies whether non-transparent PNG images should be automatically converted to JPEG
## Defaults to: False
AUTO_PNG_TO_JPG = False
## Specify the ratio between 1in and 1px for SVG images. This is only used
## whenrasterizing SVG images having their size units in cm or inches.
## Defaults to: 150
SVG_DPI = 150
## Max AGE sent as a header for the image served by thumbor in seconds
## Defaults to: 86400
MAX_AGE = 86400
## Indicates the Max AGE header in seconds for temporary images (images with
## failed smart detection)
## Defaults to: 0
MAX_AGE_TEMP_IMAGE = 0
## Indicates whether thumbor should rotate images that have an Orientation EXIF
## header
## Defaults to: False
RESPECT_ORIENTATION = False
## Ignore errors during smart detections and return image as a temp image (not
## saved in result storage and with MAX_AGE_TEMP_IMAGE age)
## Defaults to: False
IGNORE_SMART_ERRORS = False
## Sends If-Modified-Since & Last-Modified headers; requires support from result
## storage
## Defaults to: False
SEND_IF_MODIFIED_LAST_MODIFIED_HEADERS = False
## Preserves exif information in generated images. Increases image size in
## kbytes, use with caution.
## Defaults to: False
PRESERVE_EXIF_INFO = False
## Indicates whether thumbor should enable the EXPERIMENTAL support for animated
## gifs.
## Defaults to: True
ALLOW_ANIMATED_GIFS = True
## Indicates whether thumbor should use gifsicle engine. Please note that smart
## cropping and filters are not supported for gifs using gifsicle (but won't
## give an error).
## Defaults to: False
USE_GIFSICLE_ENGINE = False
## Indicates whether thumbor should enable blacklist functionality to prevent
## processing certain images.
## Defaults to: False
USE_BLACKLIST = False
## Size of the thread pool used for image transformations. The default value is
## 0 (don't use a threadpoool. Increase this if you are seeing your IOLoop
## getting blocked (often indicated by your upstream HTTP requests timing out)
## Defaults to: 0
ENGINE_THREADPOOL_SIZE = 0
################################################################################
################################ Extensibility #################################
## The metrics backend thumbor should use to measure internal actions. This must
## be the full name of a python module (python must be able to import it)
## Defaults to: 'thumbor.metrics.logger_metrics'
METRICS = 'thumbor.metrics.logger_metrics'
## The loader thumbor should use to load the original image. This must be the
## full name of a python module (python must be able to import it)
## Defaults to: thumbor.loaders.http_loader
LOADER = 'thumbor.loaders.http_loader'
## The file storage thumbor should use to store original images. This must be the
## full name of a python module (python must be able to import it)
## Defaults to: thumbor.storages.file_storage
STORAGE = 'thumbor.storages.file_storage'
STORAGE_BUCKET = ''
RESULT_STORAGE_BUCKET = ''
## The result storage thumbor should use to store generated images. This must be
## the full name of a python module (python must be able to import it)
## Defaults to: None
RESULT_STORAGE = 'thumbor.result_storages.file_storage'
## The imaging engine thumbor should use to perform image operations. This must
## be the full name of a python module (python must be able to import it)
## Defaults to: thumbor.engines.pil
ENGINE = 'thumbor.engines.pil'
## The gif engine thumbor should use to perform image operations. This must be
## the full name of a python module (python must be able to import it)
## Defaults to: 'thumbor.engines.gif'
GIF_ENGINE = 'thumbor.engines.gif'
## The url signer thumbor should use to verify url signatures.This must be the
## full name of a python module (python must be able to import it)
## Defaults to: 'libthumbor.url_signers.base64_hmac_sha1'
URL_SIGNER = 'libthumbor.url_signers.base64_hmac_sha1'
################################################################################
################################### Security ###################################
## The security key thumbor uses to sign image URLs
## Defaults to: MY_SECURE_KEY
SECURITY_KEY = 'MY_SECURE_KEY'
## Indicates if the /unsafe URL should be available
## Defaults to: True
ALLOW_UNSAFE_URL = True
## Indicates if encrypted (old style) URLs should be allowed
## Defaults to: True
ALLOW_OLD_URLS = True
## AWS access keys - used in thumbor_aws storage
AWS_ACCESS_KEY = ''
AWS_SECRET_KEY = ''
################################################################################
##################################### HTTP #####################################
## Enables automatically generated etags
## Defaults to: True
ENABLE_ETAGS = True
################################################################################
################################### Storage ####################################
## Set maximum id length for images when stored
## Defaults to: 32
MAX_ID_LENGTH = 32
################################################################################
################################### Metrics ####################################
## Host to send statsd instrumentation to
## Defaults to: None
## Port to send statsd instrumentation to
## Defaults to: 8125
STATSD_PORT = 8125
## Prefix for statsd
## Defaults to: None
################################################################################
################################# File Loader ##################################
## The root path where the File Loader will try to find images
## Defaults to: /tmp
FILE_LOADER_ROOT_PATH = '/data/loader'
################################################################################
################################# HTTP Loader ##################################
## The maximum number of seconds libcurl can take to connect to an image being
## loaded
## Defaults to: 5
HTTP_LOADER_CONNECT_TIMEOUT = 5
## The maximum number of seconds libcurl can take to download an image
## Defaults to: 20
HTTP_LOADER_REQUEST_TIMEOUT = 20
## Indicates whether libcurl should follow redirects when downloading an image
## Defaults to: True
HTTP_LOADER_FOLLOW_REDIRECTS = True
## Indicates the number of redirects libcurl should follow when downloading an
## image
## Defaults to: 5
HTTP_LOADER_MAX_REDIRECTS = 5
## The maximum number of simultaneous HTTP connections the loader can make before
## queuing
## Defaults to: 10
HTTP_LOADER_MAX_CLIENTS = 10
## Whether thumbor should forward all client headers
## Defaults to: False
HTTP_LOADER_FORWARD_ALL_HEADERS = False
## Indicates whether thumbor should forward the user agent of the requesting user
## Defaults to: False
HTTP_LOADER_FORWARD_USER_AGENT = False
## A list of headers the http loader will forward from the client
## Defaults to: []
HTTP_LOADER_FORWARD_HEADERS_WHITELIST = []
## Default user agent for thumbor http loader requests
## Defaults to: Thumbor/6.3.0
HTTP_LOADER_DEFAULT_USER_AGENT = 'Thumbor/6.3.0'
## The proxy host needed to load images through
## Defaults to: None
HTTP_LOADER_PROXY_HOST = None
## The proxy port for the proxy host
## Defaults to: None
HTTP_LOADER_PROXY_PORT = None
## The proxy username for the proxy host
## Defaults to: None
HTTP_LOADER_PROXY_USERNAME = None
## The proxy password for the proxy host
## Defaults to: None
HTTP_LOADER_PROXY_PASSWORD = None
## The filename of CA certificates in PEM format
## Defaults to: None
HTTP_LOADER_CA_CERTS = None
## Validate the servers certificate for HTTPS requests
## Defaults to: True
HTTP_LOADER_VALIDATE_CERTS = True
## The filename for client SSL key
## Defaults to: None
HTTP_LOADER_CLIENT_KEY = None
## The filename for client SSL certificate
## Defaults to: None
HTTP_LOADER_CLIENT_CERT = None
## If the CurlAsyncHTTPClient should be used
## Defaults to: False
HTTP_LOADER_CURL_ASYNC_HTTP_CLIENT = False
################################################################################
################################# File Storage #################################
## Expiration in seconds for the images in the File Storage. Defaults to one
## month
## Defaults to: 2592000
STORAGE_EXPIRATION_SECONDS = 2592000
## Indicates whether thumbor should store the signing key for each image in the
## file storage. This allows the key to be changed and old images to still be
## properly found
## Defaults to: False
STORES_CRYPTO_KEY_FOR_EACH_IMAGE = False
## The root path where the File Storage will try to find images
## Defaults to: /tmp/thumbor/storage
FILE_STORAGE_ROOT_PATH = '/data/storage'
RESULT_STORAGE_FILE_STORAGE_ROOT_PATH = '/data/result-storage'
################################################################################
#################################### Upload ####################################
## Max size in Kb for images uploaded to thumbor
## Aliases: MAX_SIZE
## Defaults to: 0
UPLOAD_MAX_SIZE = 0
## Indicates whether thumbor should enable File uploads
## Aliases: ENABLE_ORIGINAL_PHOTO_UPLOAD
## Defaults to: False
UPLOAD_ENABLED = False
## The type of storage to store uploaded images with
## Aliases: ORIGINAL_PHOTO_STORAGE
## Defaults to: thumbor.storages.file_storage
UPLOAD_PHOTO_STORAGE = 'thumbor.storages.file_storage'
## Indicates whether image deletion should be allowed
## Aliases: ALLOW_ORIGINAL_PHOTO_DELETION
## Defaults to: False
UPLOAD_DELETE_ALLOWED = False
## Indicates whether image overwrite should be allowed
## Aliases: ALLOW_ORIGINAL_PHOTO_PUTTING
## Defaults to: False
UPLOAD_PUT_ALLOWED = False
## Default filename for image uploaded
## Defaults to: image
UPLOAD_DEFAULT_FILENAME = 'image'
################################################################################
############################### MongoDB Storage ################################
## MongoDB storage server host
## Defaults to: localhost
MONGO_STORAGE_SERVER_HOST = 'mongo'
## MongoDB storage server port
## Defaults to: 27017
MONGO_STORAGE_SERVER_PORT = 27017
## MongoDB storage server database name
## Defaults to: thumbor
MONGO_STORAGE_SERVER_DB = 'thumbor'
## MongoDB storage image collection
## Defaults to: images
MONGO_STORAGE_SERVER_COLLECTION = 'images'
################################################################################
################################ Redis Storage #################################
## Redis storage server host
## Defaults to: localhost
REDIS_STORAGE_SERVER_HOST = 'redis'
## Redis storage server port
## Defaults to: 6379
REDIS_STORAGE_SERVER_PORT = 6379
## Redis storage database index
## Defaults to: 0
REDIS_STORAGE_SERVER_DB = 0
## Redis storage server password
## Defaults to: None
REDIS_STORAGE_SERVER_PASSWORD = None
## Ignore Redis storage errors
## Defaults to: True
REDIS_STORAGE_IGNORE_ERRORS = True
################################################################################
################################ Redis Result Storage #################################
## Redis storage server host
## Defaults to: localhost
REDIS_RESULT_STORAGE_SERVER_HOST = 'redis'
## Redis storage server port
## Defaults to: 6379
REDIS_RESULT_STORAGE_SERVER_PORT = 6379
## Redis storage database index
## Defaults to: 0
REDIS_RESULT_STORAGE_SERVER_DB = 0
## Redis storage server password
## Defaults to: None
REDIS_RESULT_STORAGE_SERVER_PASSWORD = None
## Ignore Redis result storage errors
## Defaults to: True
REDIS_RESULT_STORAGE_IGNORE_ERRORS = True
################################################################################
############################### Memcache Storage ###############################
## List of Memcache storage server hosts
## Defaults to: ['localhost:11211']
MEMCACHE_STORAGE_SERVERS = ['localhost:11211']
################################################################################
################################ Mixed Storage #################################
## Mixed Storage file storage. This must be the full name of a python module
## (python must be able to import it)
## Defaults to: thumbor.storages.no_storage
MIXED_STORAGE_FILE_STORAGE = 'thumbor.storages.no_storage'
## Mixed Storage signing key storage. This must be the full name of a python
## module (python must be able to import it)
## Defaults to: thumbor.storages.no_storage
MIXED_STORAGE_CRYPTO_STORAGE = 'thumbor.storages.no_storage'
## Mixed Storage detector information storage. This must be the full name of a
## python module (python must be able to import it)
## Defaults to: thumbor.storages.no_storage
MIXED_STORAGE_DETECTOR_STORAGE = 'thumbor.storages.no_storage'
################################################################################
##################################### Meta #####################################
## The callback function name that should be used by the META route for JSONP
## access
## Defaults to: None
META_CALLBACK_NAME = None
################################################################################
################################## Detection ###################################
## List of detectors that thumbor should use to find faces and/or features. All
## of them must be full names of python modules (python must be able to import
## it)
## Defaults to: []
#DETECTORS = [
#'thumbor.detectors.queued_detector.queued_complete_detector',
#'thumbor.detectors.queued_detector.queued_face_detector',
#'thumbor.detectors.queued_detector.queued_feature_detector',
#'thumbor.detectors.feature_detector',
#'thumbor.detectors.face_detector',
#]
DETECTORS = []
## The cascade file that opencv will use to detect faces
## Defaults to: haarcascade_frontalface_alt.xml
FACE_DETECTOR_CASCADE_FILE = 'haarcascade_frontalface_alt.xml'
## The cascade file that opencv will use to detect glasses.
## Defaults to: 'haarcascade_eye_tree_eyeglasses.xml'
GLASSES_DETECTOR_CASCADE_FILE = 'haarcascade_eye_tree_eyeglasses.xml'
## The cascade file that opencv will use to detect profile faces.
## Defaults to: 'haarcascade_profileface.xml'
PROFILE_DETECTOR_CASCADE_FILE = 'haarcascade_profileface.xml'
################################################################################
################################## Optimizers ##################################
## List of optimizers that thumbor will use to optimize images
## Defaults to: [] --> ['thumbor.optimizers.jpegtran',]
OPTIMIZERS = []
## Path for the jpegtran binary
## Defaults to: /usr/bin/jpegtran
JPEGTRAN_PATH = '/usr/bin/jpegtran'
# Path for the progressive scans file to use with jpegtran optimizer. Implies progressive jpeg output
JPEGTRAN_SCANS_FILE = ''
PROGRESSIVE_JPEG = True
FFMPEG_PATH = '/usr/bin/ffmpeg' # Default path for the docker installation in debian
################################################################################
################################### Filters ####################################
## List of filters that thumbor will allow to be used in generated images. All of
## them must be full names of python modules (python must be able to import
## it)
## using thumbor's default, unless specified.
################################################################################
################################ Result Storage ################################
## Expiration in seconds of generated images in the result storage
## Defaults to: 0
RESULT_STORAGE_EXPIRATION_SECONDS = 0
## Path where the Result storage will store generated images
## Defaults to: /tmp/thumbor/result_storage
RESULT_STORAGE_FILE_STORAGE_ROOT_PATH = '/data/result_storage'
## Indicates whether unsafe requests should also be stored in the Result Storage
## Defaults to: False
RESULT_STORAGE_STORES_UNSAFE = False
################################################################################
############################ Queued Redis Detector #############################
## Server host for the queued redis detector
## Defaults to: localhost
REDIS_QUEUE_SERVER_HOST = 'redis'
## Server port for the queued redis detector
## Defaults to: 6379
REDIS_QUEUE_SERVER_PORT = 6379
## Server database index for the queued redis detector
## Defaults to: 0
REDIS_QUEUE_SERVER_DB = 0
## Server password for the queued redis detector
## Defaults to: None
REDIS_QUEUE_SERVER_PASSWORD = None
################################################################################
############################# Queued SQS Detector ##############################
## AWS key id
## Defaults to: None
SQS_QUEUE_KEY_ID = None
## AWS key secret
## Defaults to: None
SQS_QUEUE_KEY_SECRET = None
## AWS SQS region
## Defaults to: us-east-1
SQS_QUEUE_REGION = 'us-east-1'
################################################################################
#################################### Errors ####################################
## This configuration indicates whether thumbor should use a custom error
## handler.
## Defaults to: False
USE_CUSTOM_ERROR_HANDLING = False
## Error reporting module. Needs to contain a class called ErrorHandler with a
## handle_error(context, handler, exception) method.
## Defaults to: thumbor.error_handlers.sentry
ERROR_HANDLER_MODULE = 'thumbor.error_handlers.sentry'
## File of error log as json
## Defaults to: None
ERROR_FILE_LOGGER = None
## File of error log name is parametrized with context attribute
## Defaults to: False
ERROR_FILE_NAME_USE_CONTEXT = False
################################################################################
############################### Errors - Sentry ################################
## Sentry thumbor project dsn. i.e.: http://5a63d58ae7b94f1dab3dee740b301d6a:73ee
## a45d3e8649239a973087e8f21f98@localhost:9000/2
## Defaults to:
SENTRY_DSN_URL = ''
################################################################################
################################### General ####################################
# The amount of time to wait before shutting down the server, i.e. stop accepting requests.
MAX_WAIT_SECONDS_BEFORE_SERVER_SHUTDOWN = 0
# The amount of time to waut before shutting down all io, after the server has been stopped
MAX_WAIT_SECONDS_BEFORE_IO_SHUTDOWN = 0
## Custom app class to override ThumborServiceApp. This config value is
## overridden by the -a command-line parameter.
## Defaults to: 'thumbor.app.ThumborServiceApp'
APP_CLASS = 'thumbor.app.ThumborServiceApp'
################################################################################
############################## TC_AWS ##########################################
TC_AWS_REGION = 'eu-west-1' # AWS Region
# Custom S3 endpoint URL (for GCP, Minio, etc.)
TC_AWS_STORAGE_BUCKET = '' # S3 bucket for Storage
TC_AWS_STORAGE_ROOT_PATH = '' # S3 path prefix for Storage bucket
TC_AWS_LOADER_BUCKET = '' #S3 bucket for loader
TC_AWS_LOADER_ROOT_PATH = '' # S3 path prefix for Loader bucket
TC_AWS_RESULT_STORAGE_BUCKET = '' # S3 bucket for result Storage
TC_AWS_RESULT_STORAGE_ROOT_PATH = '' # S3 path prefix for Result storage bucket
# put data into S3 using the Server Side Encryption functionality to
# encrypt data at rest in S3
# https://aws.amazon.com/about-aws/whats-new/2011/10/04/amazon-s3-announces-server-side-encryption-support/
TC_AWS_STORAGE_SSE = False
# put data into S3 with Reduced Redundancy
# https://aws.amazon.com/about-aws/whats-new/2010/05/19/announcing-amazon-s3-reduced-redundancy-storage/
TC_AWS_STORAGE_RRS = False
# Add some randomization in the S3 keys for the Storage and Result Storage.
# Defaults to False for Backwards Compatibility, set it to True for performance.
TC_AWS_RANDOMIZE_KEYS = False
# Enable HTTP Loader as well?
# This would allow you to load watermarks in over your images dynamically through a URI
# E.g.
# http://your-thumbor.com/unsafe/filters:watermark(http://example.com/watermark.png,0,0,50)/s3_bucket/photo.jpg
TC_AWS_ENABLE_HTTP_LOADER = False
TC_AWS_ALLOWED_BUCKETS = False # List of allowed bucket to be requested
TC_AWS_STORE_METADATA = False # Store result with metadata (for instance content-type)
################################################################################
########################## Google Cloud Storage ################################
CLOUD_STORAGE_BUCKET_ID = ''
CLOUD_STORAGE_PROJECT_ID = ''
RESULT_STORAGE_CLOUD_STORAGE_PROJECT_ID = ''
RESULT_STORAGE_CLOUD_STORAGE_BUCKET_ID = ''
################################################################################
######################### tc_prometheus ########################################
PROMETHEUS_SCRAPE_PORT = 8000 # Port the prometheus client should listen on
##################### Thumbor Community Extensions #############################
COMMUNITY_EXTENSIONS = []
Kill running container:
podman rm -f thumbor
Start the container but now include
podman run -d \
--name thumbor -p 8000:80 \
-v ~/thumbor/conf/thumbor.conf:/app/thumbor.conf \
-v ~/thumbor/data/:/data/storage \
ghcr.io/minimalcompact/thumbor:latest
Container shell can be invoked by running the following commands:
podman exec -ti thumbor bash