Install with Docker Compose

The Compose stack always runs the gateway, the dashboard, Postgres, Redis and ClickHouse. Everything else is behind a profile you opt into.

Install

1. 1

   Get the files

   git clone https://github.com/thediymaker/obleth-gateway.git
   cd obleth-gateway/deploy/docker
   cp .env.example .env
   

   Run every docker compose command from this directory, so Compose reads .env and merges a docker-compose.override.yml if you add one.

2. 2

   Replace the example secrets

   Compose refuses to start while a required value is empty, but the example file fills them with development values. Replace each one:

   OBLETH_VERSION=v2.4.0
   OBLETH_ADMIN_TOKEN=...          # openssl rand -hex 32
   POSTGRES_PASSWORD=...
   REDIS_PASSWORD=...              # URL-safe: openssl rand -hex 32
   CLICKHOUSE_PASSWORD=...
   DASHBOARD_ADMIN_EMAIL=you@example.org
   DASHBOARD_PASSWORD=...          # at least 8 characters
   DASHBOARD_SESSION_SECRET=...    # at least 32 characters
   OBLETH_ENCRYPTION_KEY=...       # openssl rand -base64 32
   GRAFANA_ADMIN_PASSWORD=...      # only with the observability profile
   

   The gateway connects to Redis at redis://:${REDIS_PASSWORD}@redis:6379, so the password must not contain @ : / ? # % or spaces. Postgres takes its password only when its volume is first created; changing it later in .env does not change the database's password.

3. 3

   Choose profiles and a backend

   Set COMPOSE_PROFILES in .env (see Profiles). For real models, drop benchmark and set the default upstream; each registered model's own api_base overrides it:

   COMPOSE_PROFILES=edge
   OBLETH_UPSTREAM_BASE_URL=http://my-model-server:8000/v1
   

4. 4

   Start and check

   docker compose pull
   docker compose up -d
   curl -s http://localhost:8088/health            # ok
   curl -s http://localhost:9180/api/v1/health     # ok
   

   Use docker compose up -d --build to build the images from your checkout instead.

5. 5

   Create a tenant, a key and a model

   Continue with First tenant and key. The dashboard is on port 3002.

Profiles

The example .env sets COMPOSE_PROFILES=benchmark,edge,observability. Leave it empty for the core services only. You can also add a profile for one command: docker compose --profile slurm up -d.

Settings that matter in production

The Compose file fixes some gateway settings rather than reading them from .env: the global in-flight ceiling (4096), the default pool size (32), fairshare history (3600 s), the fairshare algorithm (hierarchical) and fail-open (true). To change one, set it under services.obleth.environment in a docker-compose.override.yml. Docker Compose lists what is fixed and what is forwarded; Environment variables has every setting.

Ports and exposure

HAProxy in this stack listens on plain HTTP. Put TLS in front of the data plane and the dashboard before anyone else uses them; see HAProxy and Security.

Upgrade

Set the new OBLETH_VERSION, then docker compose pull && docker compose up -d. Compose gives the gateway 345 seconds to drain in-flight requests before it stops. Read Upgrades first: some releases need a step before the new version starts.

cp datastores.env.example datastores.env    # set the passwords
docker compose --env-file datastores.env -f datastores.compose.yml up -d