Deploying Thumbor

Introduction

Thumbor is an open-source smart imaging service that enables on-demand image manipulation including resizing, cropping, and applying filters. What makes Thumbor unique is its intelligent detection capabilities: it can identify faces, focal points, and important features in images to make smart cropping decisions. This ensures important content is preserved when images are resized for different screen sizes and layouts.

Key features of Thumbor include:

• Smart Cropping: Uses facial and feature detection to crop images intelligently
• On-Demand Resizing: Generate any image size without pre-processing
• Image Filters: Apply blur, brightness, contrast, watermarks, and more
• Format Conversion: Convert between image formats (WebP, AVIF, JPEG, PNG)
• URL-Based API: Simple URL structure for all image operations
• Caching: Built-in result caching for optimal performance
• Security: HMAC-signed URLs prevent unauthorized image operations
• Loader Extensibility: Load images from various sources (HTTP, S3, local files)
• CDN Compatible: Works seamlessly with content delivery networks
• Open Source: Active community with extensive plugin ecosystem

This guide walks you through deploying Thumbor on Klutch.sh, configuring security settings, and integrating with your application.

Why Deploy Thumbor on Klutch.sh

Deploying Thumbor on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles container orchestration, allowing you to focus on image optimization rather than infrastructure.

Scalable Resources: Adjust CPU and memory based on image processing demands and traffic patterns.

HTTPS by Default: Automatic SSL certificates ensure secure image delivery.

Persistent Storage: Cache processed images for faster subsequent requests.

GitHub Integration: Version control your configuration with automatic redeployments.

Prerequisites

Before deploying Thumbor on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and image processing concepts
• Source images accessible via HTTP or stored locally

Understanding Thumbor URLs

Thumbor uses a URL-based API for image operations:

https://thumbor.example.com/unsafe/300x200/smart/example.com/image.jpg

Components:

• unsafe or HMAC signature for security
• 300x200: Target dimensions
• smart: Enable smart cropping
• Image source URL

Preparing Your Repository

Create a GitHub repository with the following structure:

thumbor-deploy/
├── Dockerfile
├── .dockerignore
└── thumbor.conf

Creating the Dockerfile

FROM minimalcompact/thumbor:latest

# Copy custom configuration
COPY thumbor.conf /app/thumbor.conf

# Environment variables
ENV THUMBOR_PORT=8888
ENV DETECTOR=thumbor.detectors.face_detector
ENV SECURITY_KEY=${SECURITY_KEY}
ENV ALLOW_UNSAFE_URL=${ALLOW_UNSAFE_URL:-false}

# Storage configuration
ENV STORAGE=thumbor.storages.file_storage
ENV FILE_STORAGE_ROOT_PATH=/data/storage

# Result storage configuration
ENV RESULT_STORAGE=thumbor.result_storages.file_storage
ENV RESULT_STORAGE_FILE_STORAGE_ROOT_PATH=/data/result_storage

# Loader configuration
ENV LOADER=thumbor.loaders.http_loader

# Image quality
ENV QUALITY=85
ENV WEBP_QUALITY=80

EXPOSE 8888

CMD ["thumbor", "-c", "/app/thumbor.conf"]

Configuration File

Create thumbor.conf:

# Security
SECURITY_KEY = 'your-security-key-here'
ALLOW_UNSAFE_URL = False

# Server configuration
HTTP_LOADER_FORWARD_USER_AGENT = True
HTTP_LOADER_FORWARD_ALL_HEADERS = False

# Detectors for smart cropping
DETECTORS = [
    'thumbor.detectors.face_detector',
    'thumbor.detectors.feature_detector',
]

# Image quality settings
QUALITY = 85
WEBP_QUALITY = 80
AUTO_WEBP = True

# Allowed sources (restrict to trusted domains)
ALLOWED_SOURCES = [
    '.+',  # Allow all sources (restrict in production)
]

# Storage configuration
STORAGE = 'thumbor.storages.file_storage'
STORAGE_EXPIRATION_SECONDS = 60 * 60 * 24 * 7  # 7 days

# Result storage
RESULT_STORAGE = 'thumbor.result_storages.file_storage'
RESULT_STORAGE_EXPIRATION_SECONDS = 60 * 60 * 24  # 1 day

# File paths
FILE_STORAGE_ROOT_PATH = '/data/storage'
RESULT_STORAGE_FILE_STORAGE_ROOT_PATH = '/data/result_storage'

# Maximum image dimensions
MAX_WIDTH = 4000
MAX_HEIGHT = 4000

# Respect source image if smaller than requested
RESPECT_ORIENTATION = True

# Enable CORS
CORS_ALLOW_ORIGIN = '*'

Environment Variables Reference

Variable	Required	Default	Description
SECURITY_KEY	Yes	-	Secret key for URL signing
ALLOW_UNSAFE_URL	No	false	Allow unsigned URLs
THUMBOR_PORT	No	8888	HTTP server port
QUALITY	No	85	Default JPEG quality
AUTO_WEBP	No	true	Auto-convert to WebP when supported

Deploying on Klutch.sh

Generate Security Key

Create a secure key for URL signing:

openssl rand -base64 32

Save this key for configuration.

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “thumbor” or “image-service”.

Create the Thumbor App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 8888.

Set Environment Variables

Configure the required variables:

Variable	Value
SECURITY_KEY	Your generated security key
ALLOW_UNSAFE_URL	false (or true for testing)

Attach Persistent Volumes

Add persistent storage for image cache:

Mount Path	Size	Purpose
/data/storage	10 GB	Source image cache
/data/result_storage	20 GB	Processed image cache

Deploy Your Application

Click Deploy to build and launch Thumbor.

Test the Service

Access an image through Thumbor: https://your-app-name.klutch.sh/unsafe/300x200/smart/example.com/image.jpg

Using Thumbor

URL Structure

Basic Thumbor URL format:

https://thumbor/SIGNATURE/SIZE/SMART/SOURCE

Resizing Images

Resize to specific dimensions:

/unsafe/300x200/example.com/image.jpg

Maintain aspect ratio (specify one dimension):

/unsafe/300x0/example.com/image.jpg  # Fixed width
/unsafe/0x200/example.com/image.jpg  # Fixed height

Smart Cropping

Enable intelligent cropping:

/unsafe/300x200/smart/example.com/image.jpg

Thumbor will detect faces and important features, centering the crop on them.

Applying Filters

Add filters to the URL:

/unsafe/300x200/filters:brightness(10):blur(2)/example.com/image.jpg

Available filters:

• brightness(n): Adjust brightness
• contrast(n): Adjust contrast
• blur(n): Apply Gaussian blur
• watermark(url,x,y,alpha): Add watermark
• quality(n): Set output quality
• format(f): Convert to format (webp, png, jpeg)
• grayscale(): Convert to grayscale
• round_corner(n): Add rounded corners

Signed URLs

For production, use HMAC-signed URLs:

import hmac
import hashlib
import base64

def sign_url(image_url, security_key):
    signature = hmac.new(
        security_key.encode(),
        image_url.encode(),
        hashlib.sha1
    ).digest()
    return base64.urlsafe_b64encode(signature).decode()

Integration Examples

Web Application Integration

Generate Thumbor URLs in your application:

function getThumborUrl(imageUrl, width, height) {
    const base = 'https://thumbor.example.com';
    const path = `${width}x${height}/smart/${imageUrl}`;
    // Add signature for production
    return `${base}/unsafe/${path}`;
}

Responsive Images

Generate multiple sizes for responsive images:

<img
    srcset="
        https://thumbor.example.com/unsafe/320x0/image.jpg 320w,
        https://thumbor.example.com/unsafe/640x0/image.jpg 640w,
        https://thumbor.example.com/unsafe/1280x0/image.jpg 1280w
    "
    sizes="(max-width: 320px) 320px, (max-width: 640px) 640px, 1280px"
    src="https://thumbor.example.com/unsafe/640x0/image.jpg"
/>

CDN Integration

Place a CDN in front of Thumbor:

1. Configure CDN origin to your Thumbor instance
2. Set appropriate cache headers
3. Use CDN URL in your application

Production Best Practices

Security Recommendations

• Disable Unsafe URLs: Set ALLOW_UNSAFE_URL=false in production
• Restrict Sources: Configure ALLOWED_SOURCES to trusted domains only
• Strong Security Key: Use a cryptographically secure key
• Rate Limiting: Implement rate limiting at the CDN or proxy level

Performance Optimization

• Enable Result Storage: Cache processed images
• Use WebP: Enable AUTO_WEBP for smaller file sizes
• CDN Caching: Use a CDN for global distribution
• Appropriate Quality: Balance quality vs. file size

Caching Strategy

Optimize cache settings:

1. Set appropriate expiration times
2. Use consistent URL patterns for cache efficiency
3. Implement cache purging for updated images
4. Monitor cache hit rates

Troubleshooting

Images Not Loading

• Verify source image URL is accessible
• Check ALLOWED_SOURCES configuration
• Review loader settings
• Check container logs for errors

Slow Processing

• Increase container resources
• Enable result storage caching
• Use a CDN for frequently accessed images
• Optimize source image sizes

Signature Errors

• Verify security key matches between generator and Thumbor
• Check URL encoding
• Ensure consistent URL format

Face Detection Not Working

• Install OpenCV dependencies
• Enable face detector in configuration
• Verify detector is available in container

Additional Resources

• Thumbor Documentation
• Thumbor GitHub Repository
• Thumbor Filters Reference
• Thumbor Client Libraries
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Thumbor on Klutch.sh provides a powerful image processing service for your applications. With smart cropping, on-demand resizing, and extensive filter options, Thumbor eliminates the need for pre-processed image variants. The combination of Thumbor’s intelligent image manipulation and Klutch.sh’s reliable infrastructure ensures fast, optimized images for any screen size or format requirement.