tumbuloze

Micro service to serve thumbnails from Zordsdavini :)

Features

• Dynamic image resizing using bimg (powered by libvips).
• Local filesystem caching to avoid redundant processing.
• Supports multiple resizing modes.
• Dockerized for easy deployment.

API Usage

Endpoint: GET /i/{mode}/{encoded_url}

Supported Modes

The service supports four resizing patterns:

• w{width}: Resize to specific width, preserving aspect ratio (e.g., w200).
• h{height}: Resize to specific height, preserving aspect ratio (e.g., h15).
• {width}x{height}: Force resize to exact dimensions, ignoring aspect ratio (e.g., 300x200).
• m{width}x{height}: Resize to max width or height, preserving aspect ratio (e.g., m100x100).

URL Encoding

The {encoded_url} must be the source image URL, escaped for use in a URL path.

Example:

• Source: https://example.com/photo.jpg
• Encoded: https%3A%2F%2Fexample.com%2Fphoto.jpg
• Full Path: /i/w100/https%3A%2F%2Fexample.com%2Fphoto.jpg

Prerequisites

• Docker & Docker Compose (Recommended)
• Go 1.26+ (If building locally)
• libvips 8.10+ (If building locally)

Local Development Setup

To build and run the service locally, you need to install libvips and its development headers.

Arch Linux

sudo pacman -S libvips openslide base-devel

Note: openslide is required by some libvips modules on Arch; installing it resolves "unable to load vips-openslide.so" warnings.

Deployment

Docker Compose (with Traefik)

The included docker-compose.yaml provides a full setup including Traefik as a reverse proxy.

docker-compose up -d

The service will be accessible at http://tumbuloze.localhost (ensure your hosts file maps this to 127.0.0.1).

Docker Only

docker build -t tumbuloze .
docker run -p 8080:8080 -v tumbuloze_storage:/storage tumbuloze

Storage & Caching

Processed images are stored in a local volume to speed up subsequent requests.

Filesystem Structure: /{host}/{url_path_to_dir}/{mode}/{image_filename}

Example path inside the container: /storage/example.com/img/w100/photo.jpg (for source https://example.com/img/photo.jpg)

Environment Variables

• PORT: Port the service listens on (default: 8080).
• CACHE_DIR: Directory for storing thumbnails (default: /storage).
• CLEANUP_INTERVAL: How often to run the cache cleanup worker (e.g., 12h, 24h, 1h). Set to 0 to disable. (default: 24h).
• MAX_AGE_DAYS: Number of days to keep cached files (default: 90).