Operations

Docker Deployment


Orcher provides a Docker Compose setup for running the backing services — PostgreSQL and PgBouncer. The orchestrator runs on the host (or in its own container, image ghcr.io/orcher-io/orcher) and serves both the gRPC API and the REST API, so it is the only Orcher process to run.

  • Backing services — PostgreSQL 15 and the PgBouncer connection pooler
  • Observability stack — Optional Prometheus and Grafana via --profile observability
  • Production Dockerfile — Multi-stage build with non-root user, health checks, and minimal runtime image
  • Environment-driven — All configuration via environment variables, no config files required

Quick Start

Start the backing services:

1
cd docker
2
docker compose up -d

This starts PostgreSQL (port 5432) and PgBouncer (port 6432).

Then run the orchestrator from source, pointing it at PgBouncer:

1
DATABASE_URL="postgresql://orcher:orcher@localhost:6432/orcher" \
2
cargo run -p orcher-orchestrator --release

The orchestrator listens on:

PortProtocolPurpose
50051gRPCSDKs, workers and the CLI (workflow/task polling, completions)
8080HTTPREST API (/api/v1), health checks (/health, /health/ready, /health/live) and metrics (/metrics)

Docker Compose Services

PostgreSQL

Primary data store for all workflow state, journal entries, task executions, and execution logs.

1
postgres:
2
image: postgres:15-alpine
3
environment:
4
POSTGRES_USER: orcher
5
POSTGRES_PASSWORD: orcher
6
POSTGRES_DB: orcher
7
ports:
8
- "5432:5432"
9
volumes:
10
- postgres_data:/var/lib/postgresql/data

The compose file tunes PostgreSQL for workflow workloads:

ParameterValuePurpose
max_connections200Support PgBouncer pool + direct connections
shared_buffers256MBShared memory for caching
effective_cache_size768MBQuery planner hint for OS cache
work_mem4MBPer-operation sort/hash memory
wal_buffers16MBWrite-ahead log buffer
max_worker_processes4Parallel query workers
random_page_cost1.1Tuned for SSD storage
effective_io_concurrency200Concurrent I/O for SSD

PgBouncer

Connection pooler that multiplexes client connections to a smaller pool of PostgreSQL connections. Required for production workloads — PostgreSQL connections are expensive (~10MB each), and concurrent workflows can exhaust the connection limit quickly.

1
pgbouncer:
2
image: edoburu/pgbouncer:latest
3
environment:
4
DATABASE_URL: postgres://orcher:orcher@postgres:5432/orcher
5
POOL_MODE: transaction
6
MAX_CLIENT_CONN: 1000
7
DEFAULT_POOL_SIZE: 50
8
MIN_POOL_SIZE: 10
9
RESERVE_POOL_SIZE: 10
10
AUTH_TYPE: scram-sha-256
11
ports:
12
- "6432:5432"

Pool modes:

  • transaction (recommended) — Connection returned to pool after each transaction. Best for high concurrency. Supports 1000s of clients with 50–100 actual database connections.
  • session — Connection held for entire client session. Equivalent to direct PostgreSQL but with connection queuing.
  • statement — Most aggressive pooling but breaks multi-statement transactions.

Always connect via PgBouncer (port 6432) instead of direct PostgreSQL (port 5432) when running multiple workers or high-concurrency workloads.

Observability Stack

Prometheus and Grafana are available as an optional profile:

1
cd docker
2
docker compose --profile observability up -d

This adds:

ServicePortPurpose
Prometheus9090Metrics collection, scrapes orchestrator on port 8080
Grafana3001Dashboards and visualization (admin/admin)

Prometheus is pre-configured to scrape the orchestrator at host.docker.internal:8080/metrics with a 15-second interval. The Grafana instance includes provisioned datasources pointing to Prometheus and pre-built dashboards for task router monitoring.


Connection Strings

ServiceConnection StringWhen to Use
PgBouncerpostgresql://orcher:orcher@localhost:6432/orcherProduction and high-concurrency (recommended)
PostgreSQL (direct)postgresql://orcher:orcher@localhost:5432/orcherDebugging or migrations

Next Steps

  • Configuration — Environment variables, CLI flags, and TOML configuration
  • Production — Production Dockerfile and full production stack
  • Troubleshooting — Health checks, volumes, and common issues
  • Kubernetes — Deploy to Kubernetes with Helm charts
  • Metrics — Prometheus metrics reference