Recipe Prepare a Team Deployment

Recipe: Prepare a Team Deployment

Use when: moving from a personal instance to an authenticated shared service.

Procedure

1. Choose Compose or Kubernetes using Deployment Decision Guide.
2. Define users, producer hosts, administrators, MCP clients, and monitoring systems.
3. Create separate random dashboard, hook, and MCP secrets; store them outside source control.
4. Provision one persistent SQLite volume and enforce exactly one writer.
5. Configure TLS, allowed hosts, firewall/network policy, and only the endpoints required.
6. Deploy an immutable image and run health checks.
7. Create and restore a test backup.
8. Add one producer host, install/authenticate hooks, and run a controlled session.
9. Configure Prometheus/Grafana and one owned service alert.
10. Add remaining hosts incrementally.
11. Record upgrade, rollback, secret rotation, and incident procedures.

Acceptance checklist

• Unauthorized UI/API/WebSocket access is rejected.
• Hook token cannot access the dashboard API.
• MCP transport requires its own token.
• Metrics are private and scrape successfully.
• Restart preserves history.
• Restore rehearsal succeeds.
• A real producer's session arrives and completes.
• Operators can identify a missing-ingestion problem.
• Data/transcript retention has an owner.

Run npm run deploy:validate for repository deployments. The authoritative production commands are in docs/DEPLOYMENT.md.