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 <noreply@anthropic.com>
This commit is contained in:
@@ -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)
|
## One-time bootstrap (server → git clone)
|
||||||
|
|
||||||
Run **once** to convert the existing folder into a git checkout without losing the
|
Run **once** to convert the existing folder into a git checkout without losing the
|
||||||
|
|||||||
Reference in New Issue
Block a user