From f517c153c1b8cf40ae2f25d68f7d397b0d0e267f Mon Sep 17 00:00:00 2001 From: sravan Date: Tue, 30 Jun 2026 17:06:08 +0530 Subject: [PATCH] docs(deploy): add operational guardrails + env/verification checklist for IT Single-instance requirement, ALLOW_LOCAL_LOGIN-off, server-side directory token, no-store HTML, Node>=22.5/web-push, required env vars (SSO/VAPID/TURN), and the window.__BUILD per-release verification step. Co-Authored-By: Claude Opus 4.8 --- DEPLOY.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/DEPLOY.md b/DEPLOY.md index cb81a2a..841f758 100644 --- a/DEPLOY.md +++ b/DEPLOY.md @@ -21,6 +21,50 @@ Server facts: --- +## Operational guardrails (read before every deploy) + +These are correctness/security invariants, not preferences. Breaking one degrades +or breaks the app even if the container starts fine. + +- **Single instance only.** Chat, presence, and meeting (WebRTC) signaling use an + **in-process** registry. Do **not** scale to multiple replicas or place several + instances behind a round-robin load balancer — users on different processes + can't see each other's messages/calls. One container, one process. +- **`ALLOW_LOCAL_LOGIN` must NOT be set in production.** It's a dev-only escape + hatch that bypasses BizGaze SSO and the local-password lockout. Production logs + in via BizGaze only. +- **`BIZGAZE_DIRECTORY_TOKEN` is server-side only** — it's used by the server to + proxy directory lookups and must never be exposed to the browser/client. +- **HTML is served `Cache-Control: no-store` by design** so new builds land + immediately. Do not add an HTTP/CDN cache layer that caches `.html`. Static JS + (`icons.js`) is cache-busted with a `?v=` query, currently `?v=4`. +- **Node ≥ 22.5** (the image uses `node:24-alpine`) — required for the built-in + `node:sqlite` that `db.js` relies on. `deploy.sh` rebuilds the image, so + `npm install` (incl. `web-push`) happens automatically; no manual install. +- **No DB migration is required** for routine UI/chat releases. The `data.db` + volume persists across rebuilds; schema changes (when present) auto-apply on boot. + +### Env vars to confirm in `.env` +`.env` lives only on the server (never in git) and must contain, beyond the TURN +secrets already documented: + +| Group | Vars | Needed for | +|-------|------|-----------| +| Login / SSO | `BIZGAZE_LOGIN_URL`, `BIZGAZE_DIRECTORY_URL`, `BIZGAZE_DIRECTORY_TOKEN`, `SSO_SECRET` | BizGaze sign-in + directory search | +| Web Push | `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`, `VAPID_SUBJECT` | Background push notifications (incl. iOS PWA) | +| Calls | `TURN_URLS` / `TURN_SECRET` (or `TURN_USERNAME`+`TURN_CREDENTIAL`) | Audio/video across NATs & mobile networks | + +If the VAPID keys are missing, push silently no-ops (the app still runs). Push on +iOS additionally requires the user to **Add to Home Screen** (iOS 16.4+) — an +end-user step, not ops. + +### Per-release verification +After deploy, open the app and check the browser console logs the expected build, +e.g. `Biz Connect build 2026-06-30-batch14`. That confirms the new HTML is being +served (not a stale cache). + +--- + ## One-time bootstrap (server → git clone) Run **once** to convert the existing folder into a git checkout without losing the