120 lines
3.0 KiB
Markdown
Executable File
120 lines
3.0 KiB
Markdown
Executable File
# 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:
|
|
|
|
```dotenv
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
This starts:
|
|
|
|
- `gateway`
|
|
- `postgres`
|
|
|
|
Add the PgBouncer profile only when you need a transaction pool in front of
|
|
PostgreSQL:
|
|
|
|
```bash
|
|
docker compose --profile pgbouncer up -d
|
|
```
|
|
|
|
## 4. Enable observability when needed
|
|
|
|
Start the observability profile and point the gateway at the OTLP endpoint:
|
|
|
|
```bash
|
|
docker compose --profile observability up -d
|
|
```
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```dotenv
|
|
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:
|
|
|
|
```bash
|
|
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.
|