64 docs indexed
All services, compose profiles, volumes, and networking in the obleth Docker Compose stack.
The Docker Compose stack lives in deploy/docker/. It is the recommended way to run obleth locally or in a staging environment.
cd obleth-gateway
# Dev mode (core services + benchmark fixture backend)
docker compose -f deploy/docker/docker-compose.yml --profile benchmark up -d
# With HAProxy edge
docker compose -f deploy/docker/docker-compose.yml --profile benchmark --profile edge up -d
# With observability (Prometheus + Grafana + Jaeger)
docker compose -f deploy/docker/docker-compose.yml --profile benchmark --profile observability up -d
# With Slurm provisioner plugin (keeps managed models alive on a Slurm cluster)
docker compose -f deploy/docker/docker-compose.yml --profile slurm up -d
| Profile | What it adds |
|---|---|
| (none) | obleth, postgres, redis, clickhouse, control-plane |
benchmark | benchmark-backend benchmark fixture service |
mock | Legacy alias for the benchmark fixture profile |
edge | HAProxy on port 80 |
observability | Prometheus, Grafana, Jaeger |
slurm | obleth-provisioner Slurm plugin (keeps managed models alive on a Slurm cluster) |
The first-party services (obleth, control-plane, benchmark-backend, obleth-provisioner) declare both an image: tag (published to GHCR by the release workflow) and a build: context (local source). docker compose pull && docker compose up -d runs the published images; docker compose up --build builds from the working tree. Pin a specific release with OBLETH_VERSION=v0.3.7 in your .env. The published image paths are under ghcr.io/thediymaker/obleth-gateway/.
| Service | Source | Purpose |
|---|---|---|
obleth | built from ../.. | Main gateway |
postgres | postgres:16 | Config database |
redis | redis:7 | Hot cache + token budgets |
clickhouse | clickhouse/clickhouse-server:24.8 | Usage ledger |
control-plane | built from ../../control-plane | Dashboard |
benchmark-backend | built from ../../benchmark-backend | OpenAI-compatible benchmark fixture backend (benchmark profile) |
haproxy | haproxy:2.9 | TLS terminator + LB (edge profile) |
prometheus | prom/prometheus | Metrics collection (observability profile) |
grafana | grafana/grafana | Dashboards (observability profile) |
jaeger | jaegertracing/all-in-one | Distributed tracing (observability profile) |
obleth-provisioner | ghcr.io/thediymaker/obleth-gateway/obleth-provisioner | Slurm provisioner plugin (slurm profile) — see Slurm Provisioning |
| Service | Container port | Host port |
|---|---|---|
obleth data plane | 8080 | 8088 |
obleth admin | 9180 | 9180 |
obleth metrics | 9091 | 9091 |
postgres | 5432 | 127.0.0.1:5432 |
redis | 6379 | 127.0.0.1:6379 |
clickhouse HTTP | 8123 | 127.0.0.1:8123 |
clickhouse native | 9000 | 127.0.0.1:9000 |
benchmark-backend | 8081 | 8081 |
control-plane | 3000 | 3002 |
haproxy | 80 | 80 |
prometheus | 9090 | 9090 |
grafana | 3000 | 3001 |
jaeger | 16686 | 16686 |
| Volume | Mounted at | Contents |
|---|---|---|
postgres-data | /var/lib/postgresql/data | Postgres data |
redis-data | /data | Redis AOF/RDB |
clickhouse-data | /var/lib/clickhouse | ClickHouse tables |
Copy the example file and edit it before starting the stack:
cp deploy/docker/.env.example deploy/docker/.env
Compose loads deploy/docker/.env automatically. The real .env is gitignored;
only the documented .env.example (with labeled dev examples) is committed.
Secrets are required — Compose uses ${VAR:?error} syntax and refuses to start
if they are unset:
# Required (no default — compose errors out if missing)
POSTGRES_PASSWORD=...
CLICKHOUSE_PASSWORD=...
OBLETH_ADMIN_TOKEN=... # openssl rand -hex 32
DASHBOARD_ADMIN_EMAIL=... # break-glass admin email (sign-in is email-based)
DASHBOARD_PASSWORD=... # or DASHBOARD_PASSWORD_HASH; >= 8 chars
DASHBOARD_SESSION_SECRET=... # >= 32 chars; openssl rand -hex 32
# Datastore identity (non-secret defaults; centralized here and composed into
# OBLETH_DATABASE_URL / ClickHouse URL)
POSTGRES_USER=obleth
POSTGRES_DB=obleth
CLICKHOUSE_USER=obleth
CLICKHOUSE_DB=obleth
# Recommended security hardening
OBLETH_ENCRYPTION_KEY=... # openssl rand -base64 32 (AES-256-GCM at rest)
OBLETH_API_KEY_PEPPER=... # openssl rand -hex 32
OBLETH_BLOCK_PRIVATE_NETWORKS= # set 1 for strict SSRF mode (private targets blocked by default-off)
OBLETH_ALLOWED_PRIVATE_CIDRS= # under strict mode, allow e.g. 10.0.0.0/8 for internal upstreams
# Common tuning
OBLETH_GLOBAL_MAX_IN_FLIGHT=64
OBLETH_FAIRSHARE_ALGORITHM=hierarchical
OBLETH_UPSTREAM_BASE_URL=http://benchmark-backend:8081
# Observability profile (required when running --profile observability)
GRAFANA_ADMIN_USER=admin # Grafana admin login
GRAFANA_ADMIN_PASSWORD=... # required — compose errors out if unset
# (anonymous access is disabled)
# Edge profile (HAProxy stats page auth)
HAPROXY_STATS_USER=admin
HAPROXY_STATS_PASSWORD=... # protects the :8404/stats page
The images run as a non-root user, and the Postgres/Redis/ClickHouse ports are
bound to 127.0.0.1 so the datastores are reachable only from the host — not the
network.
docker compose -f deploy/docker/docker-compose.yml down
# Remove volumes (deletes all data)
docker compose -f deploy/docker/docker-compose.yml down -v