Installation

obleth ships as a Docker image and a Helm chart. The Docker Compose stack is the fastest way to get a complete working environment; the Helm chart is for production Kubernetes.

Prerequisites

Docker Compose

The Compose stack in deploy/docker/ starts the full obleth environment:

git clone https://github.com/thediymaker/obleth-gateway.git
cd obleth-gateway
docker compose -f deploy/docker/docker-compose.yml \
  --profile benchmark --profile edge \
  up --build -d

The benchmark profile starts the GPU-free benchmark fixture backend. The edge profile starts HAProxy. For a minimal core-only start (no bundled upstream, no HAProxy), omit both profiles.

Service ports

The Management API and metrics ports are published on the loopback interface only, so they are reachable from the Docker host and not from the network. The data plane, dashboard, and HAProxy are published on all interfaces.

Verify the stack is healthy:

curl -s http://localhost/health       # ok
curl -s http://localhost:9180/api/v1/health  # ok

Configuration

Copy .env.example to .env in deploy/docker/ and edit:

# Change the admin token before exposing the Management API
OBLETH_ADMIN_TOKEN=change-me-in-production

# Point at a real upstream instead of the benchmark fixture backend
OBLETH_UPSTREAM_BASE_URL=http://my-aibrix-or-vllm:8080/v1

# OTLP tracing (optional)
OBLETH_OTEL_ENDPOINT=http://jaeger:4318

# Dashboard sign-in (all required; the control plane refuses to start without them)
DASHBOARD_ADMIN_EMAIL=admin@example.com
DASHBOARD_PASSWORD=change-me            # >= 8 characters
DASHBOARD_SESSION_SECRET=change-me      # >= 32 characters

# Reaching the dashboard by LAN IP or an alternate hostname
# BETTER_AUTH_URL=http://192.168.1.50:3002
# TRUSTED_ORIGINS=http://192.168.1.50:3002,http://obleth.lan:3002

For the full list of variables see Environment Variables.

Observability profile

For Prometheus, Grafana, and Jaeger (OTLP):

docker compose -f deploy/docker/docker-compose.yml \
  --profile benchmark --profile edge --profile observability \
  up --build -d

Grafana requires admin credentials (anonymous access is disabled). Set them in .env before starting the profile:

GRAFANA_ADMIN_USER=admin
GRAFANA_ADMIN_PASSWORD=change-me   # required — compose errors out if unset

Additional services:

Kubernetes / Helm

helm install obleth deploy/k8s/obleth \
  --set obleth.adminToken="$(openssl rand -hex 32)" \
  --set postgres.password="$(openssl rand -hex 16)" \
  --set clickhouse.password="$(openssl rand -hex 16)" \
  --set controlPlane.dashboardPassword="$(openssl rand -hex 16)" \
  --set controlPlane.dashboardSessionSecret="$(openssl rand -hex 32)"

Those five values have no defaults — the chart fails to render without them; see Secrets below for keeping them out of a tracked values file.

This starts a self-contained demo: obleth (one replica), benchmark fixture backend, control-plane dashboard, Postgres, Redis, and ClickHouse. The HPA is off by default (hpa.enabled=false); obleth.globalMaxInFlight is enforced per replica, so raising obleth.replicas or enabling the HPA multiplies the concurrency reaching your upstream.

Minimal production install

For production, disable the bundled dependencies and point at your managed services:

# values-prod.yaml
postgres:
  enabled: false
  external:
    url: postgres://user:pass@my-pg-cluster:5432/obleth

redis:
  enabled: false
  external:
    url: redis://my-redis:6379

clickhouse:
  enabled: false
  external:
    url: http://my-clickhouse:8123

benchmarkBackend:
  enabled: false

obleth:
  allowedPrivateCidrs: ""   # only if OBLETH_BLOCK_PRIVATE_NETWORKS=1
  upstreamBaseUrl: https://my-aibrix-gateway/v1
  adminToken: change-me        # use a Secret instead
  replicas: 3                  # per-replica limit below; divide it by the replica count
  globalMaxInFlight: 256

ingress:
  enabled: true
  className: nginx
  host: obleth.example.com
  servicePort: 8080
  tls:
    - secretName: obleth-tls
      hosts: [obleth.example.com]

helm install obleth deploy/k8s/obleth -f values-prod.yaml

For a full reference of chart values, see Helm Values.

Post-install steps (Kubernetes)

helm install brings the pods up, but does not create tenant API keys or register models. Until you complete these steps, inference calls return 401 (no key) or 404 (no model).

1. Reach the Management API — port-forward or use an internal Service:
   kubectl port-forward svc/obleth 9180:9180
   

2. Create a tenant and mint a key — see First Tenant & Key. There is no shared "open" proxy key (unlike some other gateways); each client needs its own sk_... bearer token.
3. Register models — POST /api/v1/models (or import via the dashboard).
   • api_base must be the provider base ending in /v1
   • upstream_model is the bare name the upstream expects (e.g. vLLM model id)
4. Call the data plane — Authorization: Bearer <tenant-key> on port 8080 (proxy) or through your Ingress.

The bundled chart includes a benchmark fixture backend as the default upstream when benchmarkBackend.enabled=true and no models are registered. For real inference, register routes pointing at your Aibrix/vLLM Services.

SSRF and in-cluster upstreams

By default, obleth's SSRF policy allows private/LAN addresses when you register api_base values, so in-cluster hostnames like *.svc.cluster.local usually work without extra chart values.

If you enable strict mode (OBLETH_BLOCK_PRIVATE_NETWORKS=1), set obleth.allowedPrivateCidrs to your pod network (e.g. 10.0.0.0/8). See Security — Upstream URL validation.

Secrets

Don't commit production secrets in a tracked values file. Supply them at install time instead:

helm install obleth deploy/k8s/obleth \
  --set obleth.adminToken="$(openssl rand -hex 32)" \
  --set postgres.password="$(openssl rand -hex 16)" \
  --set clickhouse.password="$(openssl rand -hex 16)" \
  --set controlPlane.dashboardPassword="$(openssl rand -hex 16)" \
  --set controlPlane.dashboardSessionSecret="$(openssl rand -hex 32)"

Keep a local values-prod.yaml (gitignored) for everything else, or integrate with Sealed Secrets / External Secrets and patch the chart-managed Secret after install. The chart renders credentials into a Kubernetes Secret at deploy time — it does not read from a pre-created Secret by default.

Building from source

git clone https://github.com/thediymaker/obleth-gateway.git
cd obleth-gateway/obleth
cargo build --release

The binary is at target/release/obleth-proxy. Configure via environment variables:

export OBLETH_DATABASE_URL=postgres://obleth:obleth@localhost:5432/obleth
export OBLETH_REDIS_URL=redis://localhost:6379
export OBLETH_CLICKHOUSE_URL=http://localhost:8123
export OBLETH_UPSTREAM_BASE_URL=http://localhost:8081
export OBLETH_ADMIN_TOKEN=dev-admin-token

./target/release/obleth-proxy

The binary applies the embedded schema on first boot — no manual migration step needed.

Next steps

• Quick Start — mint a tenant key and make your first call
• First Tenant & Key — detailed tenant setup walkthrough
• Environment Variables — full configuration reference