Deployment

Single-host Docker (the default)

For most teams, the official Docker image on a single host is the right starting point.

docker compose up -d

The bundled docker-compose.yml exposes the dashboard on :3000 and the proxy on :8080, persists a SQLite file under ./data/, and reads .env for secrets.

Behind a reverse proxy

For TLS termination, run nginx or Caddy in front:

# /etc/nginx/sites-available/ai-cost-gate
server {
  listen 443 ssl http2;
  server_name ai-cost-gate.example.com;

  ssl_certificate /etc/letsencrypt/live/ai-cost-gate.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/ai-cost-gate.example.com/privkey.pem;

  # Dashboard
  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
  }

  # OpenAI-compatible proxy
  location /v1/ {
    proxy_pass http://127.0.0.1:8080/v1/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Backups

The whole database is one SQLite file. Back it up however you back up the host's disk. We recommend:

• A nightly sqlite3 .backup to object storage.
• A weekly off-host snapshot.

To restore: stop the container, replace ./data/ai-cost-gate.db, and start the container again.

Upgrades

Pull a new image, restart:

docker compose pull
docker compose up -d

The schema is migrated on startup. There is no separate migration step. We guarantee that within a major version, you can always roll back to an older image without manual steps.

Monitoring

ai-cost-gate exposes a /health endpoint on the admin port (default :3000). Point your existing health-check at it. For deeper metrics, scrape /internal/metrics (Prometheus format) once you've set METRICS_ENABLED=true.

Multi-host

For higher availability, run two or more ai-cost-gate instances pointing at the same SQLite file (on a shared volume) is not supported — SQLite + multiple writers doesn't work. We are evaluating a Postgres backend; see the public roadmap.