Self-Hosting

Run OpenWorkers on your own infrastructure.

Requirements

  • Docker + Docker Compose
  • TLS certificates (for HTTPS)
  • GitHub OAuth app (for dashboard login)

Quick Start

# Clone the infra repo
git clone https://github.com/openworkers/openworkers-infra.git
cd openworkers-infra

# Configure environment
cp .env.example .env
# Edit .env with your values

# Start database and run migrations
docker compose up -d postgres
git clone https://github.com/openworkers/openworkers-cli.git
for f in openworkers-cli/migrations/*.sql; do
  docker compose exec -T postgres psql -U $POSTGRES_USER -d $POSTGRES_DB < "$f"
done

# Generate API token
docker compose up -d postgate
docker compose exec postgate postgate gen-token 
  aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa api 
  --permissions SELECT,INSERT,UPDATE,DELETE
# Copy the token to .env as POSTGATE_TOKEN=pg_xxx...

# Start all services
docker compose up -d

Stack

ServiceDescription
postgresPostgreSQL database
natsMessage queue for worker communication
postgateHTTP proxy for PostgreSQL
openworkers-apiREST API
openworkers-runnerWorker runtime (V8 isolates)
openworkers-logsLog aggregator
openworkers-schedulerCron job scheduler
openworkers-dashDashboard UI
openworkers-proxyNginx reverse proxy

Architecture

                         ┌─────────────────┐
                         │  nginx (proxy)  │
                         └────────┬────────┘
                                  │
         ┌───────────────┬────────┴──┬───────────────┐
         │               │           │               │
         │               │           │               │
┌────────┸────────┐ ┌────┸────┐ ┌────┸────┐ ┌────────┸────────┐
│   dashboard     │ │  api    │ │ logs *  │ │  runner (x3) *  │
└─────────────────┘ └────┬────┘ └────┰────┘ └────────┰────────┘
                         │           │               │
                         │           │               │
                ┌────────┸────────┐  │      ┌────────┸────────┐
                │   postgate *    │  └──────┥      nats       │
                └─────────────────┘         └────────┰────────┘
                                                     │
                                                     │
                ┌─────────────────┐           ┌──────┴───────┐
         * ─────┥   PostgreSQL    │           │ scheduler *  │
                └─────────────────┘           └──────────────┘

Single database: All components share one PostgreSQL database. Postgate uses views that map to OpenWorkers tables.

Configuration

Required Environment Variables

VariableDescription
POSTGRES_USERDatabase user
POSTGRES_PASSWORDDatabase password
POSTGRES_DBDatabase name
GITHUB_CLIENT_IDOAuth app client ID
GITHUB_CLIENT_SECRETOAuth app secret
JWT_ACCESS_SECRETJWT signing key (min 32 chars)
JWT_REFRESH_SECRETJWT refresh key (min 32 chars)
POSTGATE_TOKENAPI token (generated in step 4)
HTTP_TLS_CERTIFICATEPath to TLS certificate
HTTP_TLS_KEYPath to TLS private key

Updating

# Pull latest images
docker compose pull

# Restart services
docker compose up -d

# Apply new migrations (if any)
for f in openworkers-cli/migrations/*.sql; do
  docker compose exec -T postgres psql -U $POSTGRES_USER -d $POSTGRES_DB < "$f" 2>/dev/null || true
done

Resources