chore(iios): production Dockerfile + migrate entrypoint + env/secrets contract

Adds a multi-stage Dockerfile for iios-service (build → pnpm deploy prune → slim non-root runtime), a docker-entrypoint that runs `prisma migrate deploy` then starts the server as PID 1, a .dockerignore, a fully-commented .env.example config contract, and docs/DEPLOYMENT.md (topology, scaling, release strategy, prod-readiness gaps). Moves prisma to dependencies so the CLI ships in the prod bundle. Image builds, migrates, and serves /health 200. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-03 19:19:13 +05:30
parent 5bd1f646ca
commit a520b26398
7 changed files with 241 additions and 4 deletions
@@ -0,0 +1,100 @@
+# Deploying IIOS
+
+IIOS deploys as **one runtime service** (`@insignia/iios-service`) plus **one datastore**
+(Postgres). Everything else in the repo is a **library** (SDKs) or a **dev demo**, not a
+deployed service.
+
+| Artifact | Type | How it ships |
+|---|---|---|
+| `@insignia/iios-service` | **Runtime service** | Docker image (this guide) |
+| `iios-contracts`, `iios-adapter-sdk`, `iios-kernel-client`, `iios-testkit` | Library | published to npm; imported by host apps |
+| `iios-message-web`, `iios-inbox-web`, `iios-support-web`, `iios-ai-web`, `iios-meeting-web`, `iios-community-web` | Web SDK (library) | published to npm; **bundled into host-app frontends** (optionally one CDN widget) |
+| `apps/*` (message-demo, ai-studio, route-admin…) | Dev demo | not deployed |
+
+The service is a **modular monolith**: a single NestJS process serves the HTTP API, the
+WebSocket (socket.io) gateway, the outbox relay, and the projectors together.
+
+## Build the image
+
+Build context is the **monorepo root** (the image needs the workspace + lockfile):
+
+```bash
+docker build -f packages/iios-service/Dockerfile -t iios-service:latest .
+```
+
+The multi-stage build compiles the service + its workspace deps, generates the Prisma
+client, and prunes to a self-contained prod bundle (`pnpm deploy --legacy`). The runtime
+image runs as the non-root `node` user and starts via `docker-entrypoint.sh`, which runs
+`prisma migrate deploy` then `node dist/main.js`.
+
+## Run it
+
+```bash
+docker run --rm -p 3200:3200 \
+  -e DATABASE_URL='postgresql://USER:PASS@HOST:5432/iios?schema=public' \
+  -e APP_SECRETS='{"portal-demo":"<secret>"}' \
+  -e IIOS_DEV_TOKENS=0 \
+  iios-service:latest
+```
+
+Health check: `GET /health` → `200`. Metrics/ops: `GET /metrics` (relay lag, projection
+cursors, retention snapshot counts).
+
+## Configuration & secrets contract
+
+Every knob is an environment variable — see [`packages/iios-service/.env.example`](../packages/iios-service/.env.example)
+for the full, commented list. Highlights:
+
+- **Secrets** (inject from a vault, never bake into the image): `DATABASE_URL`,
+  `APP_SECRETS` (per-app JWT signing keys), `ADAPTER_SECRETS` (webhook HMAC keys).
+- **⚠️ `IIOS_DEV_TOKENS` MUST be `0`/unset in production.** It exposes `/v1/dev/*`
+  (unauthenticated token minting, webhook injection, chaos, retention sweep). This is the
+  single most important prod-hardening flag.
+- **`IIOS_CELL_ID`** tags which physical cell this instance serves — the hook for splitting
+  noisy/regulated tenants into isolated cells later, with no code change.
+- **Worker timers** (`IIOS_RELAY_INTERVAL_MS`, `IIOS_RETENTION_SWEEP_INTERVAL_MS`) — see
+  scaling notes below.
+
+## Topology
+
+```
+ host apps ──HTTPS/WSS──► [ LB / ingress ] ──► iios-service ×N ──► Postgres (pgvector)
+ (embed SDKs)              (WS + sticky)         (API+relay+                 │
+                                                  projectors)         (+ Redis, + OPA/CMP/MDM
+                                                                        as external ports — later)
+```
+
+- **Postgres** — managed (RDS / Cloud SQL / Neon). One logical DB, tenant-isolated by scope.
+- **Redis** — **not required for a single instance.** Add it when you run **multiple replicas
+  with live chat** (socket.io needs its Redis adapter to fan-out across instances) or when
+  BullMQ queues are introduced.
+- **Platform ports** (OPA policy, CMP consent, MDM, CRRE, SAS) — today in-process permissive
+  stubs (`LocalDevPorts`). For production, point these at real external services; the service
+  already calls them **fail-closed**.
+
+## Scaling & release strategy
+
+**Horizontal scaling is safe** because the event core was hardened for it:
+
+- The outbox relay claims rows with `FOR UPDATE SKIP LOCKED` → each event is relayed by
+  exactly one replica; its co-located projectors process it once (idempotent `claim()` +
+  the projection-cursor + idempotency-command ledgers give exactly-once effects).
+- The **DLQ + replay** path means a bad deploy loses nothing — fix and replay.
+
+**Rolling / blue-green deploys:**
+
+1. **Migrations:** run `prisma migrate deploy` as a **one-off pre-deploy job**, then set
+   `IIOS_SKIP_MIGRATE=1` on the replicas so N pods don't race the migration. (For a single
+   instance, the default boot-time migration is fine.)
+2. Use **expand-contract (backward-compatible) schema changes** so old and new pods can run
+   against the same schema during the roll — this is the prerequisite for zero-downtime.
+3. Roll replicas with a `/health` readiness gate; drain WebSocket connections on `SIGTERM`.
+4. **WebSocket ingress** needs sticky sessions (and the Redis socket.io adapter once N>1).
+
+## Not yet built (prod-readiness gaps)
+
+- **CI/CD pipeline** to build/push this image and run migrations.
+- **Redis + socket.io Redis adapter** wiring (needed at N>1 with realtime).
+- **Real platform-port services** (OPA/CMP/MDM) — today permissive stubs.
+- **Secrets manager** integration (currently plain env).
+- A **schema-compatibility gate** in CI to enforce expand-contract migrations.