deployment-review

name	deployment-review
description	Use this skill to review deployments, validate production readiness, or assist with deployment procedures. Reference: `DEPLOYMENT_GUIDE.md`, `docker-compose.yml`, `Caddyfile`, `Dockerfile`.

Skill: Deployment Review

Use this skill to review deployments, validate production readiness, or assist with deployment procedures. Reference: DEPLOYMENT_GUIDE.md, docker-compose.yml, Caddyfile, Dockerfile.

---

Pre-Deployment Checklist

Code Validation

uv sync --python 3.13 --dev
uv run pytest tests/ -v
node --check static/js/interpreter-booth.js
node --check static/js/whep-listener.js
uv run alembic upgrade head

Environment Variables (must be set in production)

Variable	Requirement
SECRET_KEY	32+ char random string — NOT change-me
API_KEY_ENCRYPTION_KEY	32+ char random string — required if transcription API keys are stored
ADMIN_PASSWORD	Set — empty string disables admin login
JWT_SECRET	Recommended — otherwise falls back to SECRET_KEY
DATABASE_URL	postgresql+asyncpg://user:pass@host/db for production
MEDIAMTX_WHIP_BASE	Browser-reachable HTTPS URL (e.g. https://media.example.com:8889)
JITSI_DOMAIN	Hostname of self-hosted Jitsi
JITSI_BASE_URL	Full HTTPS URL of Jitsi
DOCKER_HOST_ADDRESS	Host LAN/public IP for JVB ICE candidates
JVB_AUTH_PASSWORD	Change from changeme
JICOFO_AUTH_PASSWORD	Change from changeme

Database

• Run uv run alembic upgrade head on first deploy and after any migration PR.
• Verify portal-data Docker volume is mounted and persistent.
• For PostgreSQL: ensure asyncpg is available (included in SQLAlchemy[asyncio] dependency).

---

Startup Sequence

1. docker-compose up mediamtx jitsi-* -d
2. docker-compose up portal -d
   → portal container runs: alembic upgrade head && uvicorn ...
3. Verify: curl http://localhost:8000/healthz
   → expected: {"ok": true, "server": "fastapi", "mediamtx_ok": true}
4. Open admin panel: http://localhost:8000/admin/
5. Create event → room → booths → invite tokens
6. Distribute invite links to interpreters

---

Reverse Proxy (Caddy)

Caddyfile is provided for TLS termination and routing:

• Portal: localhost:8000 → HTTPS.
• MediaMTX WHIP/WHEP: localhost:8889 → exposed via separate subdomain or path.
• Jitsi: localhost:8443 → HTTPS.

Ensure MEDIAMTX_WHIP_BASE in .env matches the Caddy-exposed HTTPS URL for MediaMTX.

---

Health Monitoring

Endpoint: GET /healthz

{"ok": true, "server": "fastapi", "mediamtx_ok": true}

• ok: false — FastAPI itself is down.
• mediamtx_ok: false — MediaMTX Control API unreachable.

Docker health check: configured in docker-compose.yml for portal service (10s interval).

---

Rollback Procedure

1. Stop portal container: docker-compose stop portal
2. Revert to previous image/tag or restore .:/app source.
3. If DB schema rolled forward: uv run alembic downgrade -1 (one step back).
4. Restart: docker-compose up portal -d

---

Zero-Downtime Deploy Notes

VoxBento uses in-memory booth state (BoothRegistry). A portal restart:

• Drops all active WS connections.
• Loses all in-memory participant state (active interpreter, chat history).
• Browser clients will reconnect (WebSocket auto-reconnects in interpreter-booth.js).
• MediaMTX stream continues unaffected — WHIP/WHEP connections survive portal restart.
• Recommend deploying during low-traffic periods (between sessions).

---

Scaling Notes

• Current architecture is single-process (module-level BoothRegistry).
• Multiple uvicorn workers (--workers N) would not share booth state — do NOT use.
• Horizontal scaling requires Redis-backed booth state (see TD-03 in TECHNICAL_DEBT_REPORT.md).
• MediaMTX and Jitsi can be scaled independently.

---

Post-Deploy Verification

1. GET /healthz → {ok: true, mediamtx_ok: true}
2. Admin login at /admin/login.
3. Create test event + booth + invite token.
4. Open invite link in browser → redirected to booth page.
5. Verify Jitsi iframe loads.
6. Click "Mic Test" → confirm level meter activates.
7. Click "Go Live" → WHIP connects to MediaMTX.
8. Open /listener/{event_slug} in second tab → WHEP audio plays.