OpenWorkers Infrastructure

Self-hosted Cloudflare Workers runtime.

Getting Started

• Docker Compose - Self-hosted deployment
• Local Development - Contributing (Docker for postgres/nats)
• Native Development - Contributing (no Docker)

Stack

Service	Description
postgres	PostgreSQL database
nats	Message queue for worker communication
postgate	HTTP proxy for PostgreSQL (query validation, multi-tenant)
openworkers-api	REST API
openworkers-runner	Worker runtime (V8 isolates)
openworkers-logs	Log aggregator
openworkers-scheduler	Cron job scheduler
openworkers-dash	Dashboard UI
openworkers-cli	CLI for migrations & worker management
openworkers-proxy	Nginx reverse proxy

Architecture

                         ┌─────────────────┐
                         │  nginx (proxy)  │
                         └────────┬────────┘
                                  │
         ┌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┬╌╌╌╌╌╌╌─┴──┬───────────────┐
         ╎               ╎           │               │
         ╎               ╎           │ sse/ws        │ http
┌╌╌╌╌╌╌╌╌┸╌╌╌╌╌╌╌┐   ┌╌╌╌┸╌╌╌┐  ┌────┸────┐    ┌─────┸───────┐
╎   dashboard    ╎   ╎  api  ╎  │ logs *  │    │   runner *  │
└╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘   └╌╌╌┬╌╌╌┘  └────┰────┘    └─────┰───────┘
                         ╎           │               │
                         ╎           │               │
                ┌╌╌╌╌╌╌╌╌┸╌╌╌╌╌╌╌╌┐  │      ┌────────┸────────┐
                ╎   postgate *    ╎  └──────┥      nats       │
                └╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┘         └────────┰────────┘
                                                     │
                                                     │
                ┌─────────────────┐           ┌──────┴───────┐
         * ─────┥   PostgreSQL    │           │ scheduler *  │
                └─────────────────┘           └──────────────┘

Note that dashboard and api can now be run directly as workers (postgate is in that case optional too as workerized api has runtime bindings to database).

Services logs and scheduler are not required for the core runtime but provide additional functionality (log streaming and cron jobs).

How Database Access Works

Worker JS code          Runner (Rust)              Postgate (lib)         PostgreSQL
      │                      │                           │                    │
      │  env.DB.query(sql)   │                           │                    │
      ├─────────────────────►│                           │                    │
      │                      │  postgate::execute(sql)   │                    │
      │                      ├──────────────────────────►│                    │
      │                      │                           │  SQL query         │
      │                      │                           ├───────────────────►│
      │                      │                           │◄───────────────────┤
      │                      │◄──────────────────────────┤                    │
      │◄─────────────────────┤                           │                    │

• Workers use bindings (env.DB.query()) provided by the runner
• Runner uses Postgate as a Rust library for query validation and execution
• Postgate HTTP is only used by the OpenWorkers API for admin operations

CLI

Use the CLI for database migrations and worker management:

# Install CLI
cargo install --git https://github.com/openworkers/openworkers-cli

# Or use Docker
docker run --rm ghcr.io/openworkers/openworkers-cli --help

# Self-hosting setup
ow alias set infra --db postgres://user:pass@localhost/openworkers
ow infra migrate run                    # Run migrations
ow infra users create admin             # Create first user
ow alias set infra --db postgres://... --user admin --force  # Set user context

# Manage workers
ow infra workers create my-worker
ow infra workers deploy my-worker script.ts

Scripts

# Database backup/restore
./database.sh backup
./database.sh restore <file>
./database.sh psql