SysDeck/klanker-gate/docs/guides/deploying-to-production.md

Deploying to Production

This guide describes the production deployment shape the repository actually ships: Docker, Docker Compose, PostgreSQL, and optional observability services.

1. Prepare the production environment

You need:

• a reachable PostgreSQL instance or the shipped postgres service
• one or more provider credentials
• an admin token for /api/*
• optional config-encryption key if you want persisted secrets encrypted at rest

Recommended baseline env settings:

PORT=8080
OPENAI_API_KEY=sk-your-key
FROSTY_DEFAULT_PROVIDER=openai
FROSTY_PG_URL=postgres://user:pass@db.internal:5432/frosty
FROSTY_PG_DIRECT_URL=postgres://user:pass@db.internal:5432/frosty
FROSTY_ADMIN_TOKEN=replace-me
FROSTY_ALLOWED_HOSTS=gw.example.com
FROSTY_LOG_STORE=pg
FROSTY_SHARED_RATE_LIMIT=on
FROSTY_ENCRYPTION_KEY=<base64-encoded-32-byte-key>

2. Build or pull the gateway image

docker build -t frosty-gateway .

The image already includes the built UI bundle because the Dockerfile runs the UI build in its first stage.

3. Start the default production stack

docker compose up -d

This starts:

• gateway
• postgres

Add the PgBouncer profile only when you need a transaction pool in front of PostgreSQL:

docker compose --profile pgbouncer up -d

4. Enable observability when needed

Start the observability profile and point the gateway at the OTLP endpoint:

docker compose --profile observability up -d

OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318

5. Scale carefully

The checked-in Compose file defines one gateway service, but the gateway itself supports multi-process fan-out via FROSTY_WORKERS.

Use that when:

• the host OS is Linux or macOS,
• you want multiple worker processes sharing port 8080,
• your connection budget can support workers x pool-size PostgreSQL usage.

If you scale out to multiple containers or replicas, set:

FROSTY_SHARED_RATE_LIMIT=on

That keeps fixed-window governance authoritative across replicas rather than per process.

6. Health and rollout checks

Useful production checks:

curl http://localhost:8080/healthz
curl -H "Authorization: Bearer <token>" http://localhost:8080/api/runtime
curl http://localhost:8080/metrics

Health checks are already defined in Compose for gateway, PostgreSQL, PgBouncer, Grafana, and MinIO.

7. Backup priorities

Back up these first:

1. postgres-data or the external PostgreSQL database
2. the MinIO trace-storage path if you keep observability history
3. Prometheus and Grafana volumes only if you need retained observability state

frosty-data is scratch space, not the primary durable state.

8. What this guide does not assume

• no Kubernetes or Helm packaging is shipped in the repository
• no CI/CD workflow is checked in to automate the gate
• no managed secret-store integration is wired directly into the Compose assets

If you build those layers around Frosty, document them separately from the repository's shipped deployment surface.