Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/sanskarsharma/thumbgen/llms.txt

Use this file to discover all available pages before exploring further.

Thumbgen can be deployed to Cloudflare using the Workers + Containers platform. In this setup, a lightweight TypeScript Worker acts as the public-facing entry point and proxies all incoming requests to a containerised instance of the Go service managed by a Durable Object. This gives you a globally distributed front door while keeping the stateful container lifecycle under Cloudflare’s control.

​
Architecture

Client Request
      │
      ▼
Cloudflare Worker (worker.ts)
      │  getContainer(env.THUMBGEN_CONTAINER).fetch(request)
      ▼
ThumbgenContainer (Durable Object)
      │  proxies to container on port 4499
      ▼
Go Thumbgen Service (Docker container)
  • worker.ts — A minimal Cloudflare Worker that extends Container from @cloudflare/containers. It declares the default container port (4499), a sleepAfter idle timeout, and lifecycle hooks (onStart, onStop, onError). The default fetch handler simply forwards every request to the container via getContainer(env.THUMBGEN_CONTAINER).fetch(request).
  • ThumbgenContainer — A Durable Object class that wraps the running Go container. It is referenced in wrangler.jsonc under both containers and durable_objects.bindings.
  • wrangler.jsonc — Declares the container image (built from the local Dockerfile), the Durable Object binding, and an optional custom domain route.

​
Prerequisites

​
Deployment Steps

1

Install dependencies

Install the required npm packages (including @cloudflare/containers and Wrangler):
npm install
2

Configure your custom domain

Open wrangler.jsonc and update the routes section with your own domain, or remove the entry entirely if you want to use Cloudflare’s default *.workers.dev subdomain:
"routes": [
    {
        "pattern": "thumbgen.pohawithpeanuts.com",  // add custom domain here, if needed
        "custom_domain": true
    }
]
Replace thumbgen.pohawithpeanuts.com with your own domain (which must already be active on Cloudflare), or delete the routes block to deploy without a custom domain.
If you leave the existing thumbgen.pohawithpeanuts.com domain in your wrangler.jsonc without replacing it, the deployment will fail with a domain conflict error because that domain is already claimed. Always edit or remove the routes section before running wrangler deploy.
3

Deploy to Cloudflare

Deploy the Worker and container to your Cloudflare account:
npx wrangler deploy
Wrangler will build the container image from the local Dockerfile, push it to Cloudflare’s registry, and publish the Worker. Once complete, your service will be live at the configured custom domain or your *.workers.dev URL.

​
Worker Source (worker.ts)

import { Container, getContainer } from '@cloudflare/containers';

export class ThumbgenContainer extends Container {
  // Configure default port for the container
  defaultPort = 4499;
  sleepAfter = "5m";

  override onStart() {
    console.log('Thumbgen container successfully started ...');
  }

  override onStop() {
    console.log('Thumbgen container successfully shut down ...');
  }

  override onError(error: unknown) {
    console.log('Thumbgen container error: ...', error);
  }
}

export default {
  async fetch(request, env) {
    return getContainer(env.THUMBGEN_CONTAINER).fetch(request);
  },
};
The sleepAfter = "5m" property instructs Cloudflare to automatically suspend the container after 5 minutes of inactivity. This keeps costs low for low-traffic deployments — the container is woken up automatically on the next incoming request with a short cold-start delay.

​
Wrangler Configuration (wrangler.jsonc)

The key sections of wrangler.jsonc that govern the Cloudflare deployment: 
{
    "name": "thumbgen-worker",
    "main": "worker.ts",
    "compatibility_date": "2025-05-23",
    "compatibility_flags": [
        "nodejs_compat"
    ],
    "observability": {
        "enabled": true
    },
    "containers": [
        {
            "name": "thumbgen",
            "image": "./Dockerfile",
            "max_instances": 1,
            "class_name": "ThumbgenContainer" // for ref in cloudflare worker / request handler code
        }
    ],
    "durable_objects": {
        "bindings": [
            {
                "class_name": "ThumbgenContainer",
                "name": "THUMBGEN_CONTAINER"
            }
        ]
    },
    "migrations": [
        {
            "tag": "v1",
            "new_sqlite_classes": [
                "ThumbgenContainer"
            ]
        }
    ],
    "routes": [
        {
            "pattern": "thumbgen.pohawithpeanuts.com",  // add custom domain here, if needed
            "custom_domain": true
        }
    ]
}
The max_instances field under containers is set to 1. This means only a single container instance will ever run at a time. For most thumbnail workloads this is sufficient, but if you expect high concurrency you can increase this value and Cloudflare will scale the container pool accordingly.

Build docs developers (and LLMs) love

Get started for freeTalk to us