Deployment

A single Chimpbase process runs everything — HTTP, workers, cron, and subscriptions. As your workload grows, you can split these responsibilities across multiple containers while sharing the same PostgreSQL database.

Single process (default)

The simplest deployment is a single container that does everything:

# docker-compose.yml
services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  app:
    build: .
    environment:
      DATABASE_URL: postgres://myapp:secret@postgres:5432/myapp
    ports:
      - "3000:3000"
    depends_on:
      - postgres

volumes:
  pgdata:

This single app container handles HTTP requests, processes background jobs, runs cron schedules, and delivers subscription events. For many workloads, this is enough.

Scaling workers

When background jobs need more throughput, add dedicated worker containers. Since queue coordination happens through PostgreSQL, multiple containers can safely poll the same queues:

services:
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  api:
    build: .
    environment:
      DATABASE_URL: postgres://myapp:secret@postgres:5432/myapp
      CHIMPBASE_SERVER_PORT: 3000
    ports:
      - "3000:3000"
    depends_on:
      - postgres

  worker:
    build: .
    environment:
      DATABASE_URL: postgres://myapp:secret@postgres:5432/myapp
      CHIMPBASE_WORKER_CONCURRENCY: 10
      CHIMPBASE_WORKER_POLL_INTERVAL_MS: 500
    deploy:
      replicas: 3
    depends_on:
      - postgres

volumes:
  pgdata:

All containers run the same chimpbase.app.ts. The worker replicas pick up jobs from the shared PostgreSQL queue — no broker needed.

Environment variables

Why this works

Chimpbase uses PostgreSQL for all coordination:

• Queues use row-level locking — multiple workers safely dequeue without duplicates
• Cron schedules are durable — only one container fires each scheduled slot
• Subscriptions with idempotent: true deduplicate across processes
• Workflows persist state in PostgreSQL — any container can resume a workflow

No separate broker, no leader election service, no external scheduler. PostgreSQL handles it.

Scaling further

When a single PostgreSQL instance becomes the bottleneck:

• Add read replicas for query-heavy actions
• Move high-throughput queues to a dedicated broker
• Shard workflows by tenant or domain

But start here. One database, N containers, and the same chimpbase.app.ts everywhere.