Deployment

Deploy @aw-chat/server (and optionally @aw-chat/admin + this docs site) on your infrastructure. The API image runs TypeScript via tsx under tini.

Handoff order

1. PostgreSQL — provision DB; set DATABASE_URL. Migrations apply on container start (db:migrate still available for one-offs).
2. Secrets / env — Intercom tokens, JWT_SECRET (same as your app’s token issuer), ADMIN_SESSION_SECRET, FILE_URL_SECRET, S3, optional FCM/Telegram. See Configuration.
3. API container — build/run server Docker; health: /health, ready: /ready (db + Intercom breaker).
4. Intercom webhook — HTTPS POST https://<api>/webhooks/intercom with Client Secret (Webhooks).
5. Admin — admin:create bootstrap user; deploy admin SPA; add its origin to CORS_ORIGINS.
6. Host apps — point SDK serverUrl at the API; add app origins to CORS_ORIGINS; mint JWTs with the shared secret.

Production checklist

• [ ] NODE_ENV=production
• [ ] DATABASE_URL, Intercom vars, JWT_SECRET (matches app signer)
• [ ] CORS_ORIGINS, REQUIRE_JWT_EXP=1, REQUIRE_S3=1
• [ ] Distinct ≥32-char JWT_SECRET, ADMIN_SESSION_SECRET, FILE_URL_SECRET
• [ ] ENABLE_DEVTOOLS / ENABLE_DEVTOOLS_RESET_ALL empty
• [ ] TRUST_PROXY_HOPS=1 behind nginx/Caddy
• [ ] S3 configured; TLS at reverse proxy; forward X-Forwarded-For / CF-IPCountry
• [ ] Intercom webhook HTTPS registered
• [ ] First admin created via CLI
• [ ] Optional: FCM / Telegram / auto-reply / DATA_RETENTION_DAYS

Production refuses to boot if the security asserts fail — Security.

Docker (API)

docker build -f apps/server/Dockerfile -t aw-chat-server .
docker run --env-file apps/server/.env -p 3100:3100 aw-chat-server

Admin panel

pnpm --filter @aw-chat/server admin:create <username> <password> [email]

Then:

• Same-origin — serve apps/admin/dist from the API origin; empty VITE_API_BASE.
• Separate static site — build with VITE_API_BASE=<api public URL>; add that origin to CORS_ORIGINS. Image: apps/admin/Dockerfile (context monorepo root, port 80).

More: Admin panel.

Suggested infrastructure

A single small VM (or container platform) + managed Postgres + S3-compatible object storage covers a pilot. Terminate TLS at Caddy/nginx; reserve a stable IP/DNS for the Intercom webhook.

CI in this repo runs lint → typecheck → test → build on main. How you promote images to your cluster (Coolify, K8s, ECS, …) is up to you — treat auto-deploy as optional.

Scaling beyond one instance

In-memory today: read cache, rate limits, admin lockout, circuit breaker, schedulers (channel publish / retention). For multiple replicas:

• Move cache + rate limits to Redis (same keys).
• Run scheduled publish / retention from one worker (or distributed lock), or posts may publish once per replica.

Hosting these docs

pnpm --filter @aw-chat/docs build   # → docs/.vitepress/dist
pnpm --filter @aw-chat/docs preview

Deploy the static output to any static host.

Day-2

Backup, rollback, monitoring: Operations.