mirror of
https://github.com/whekin/household-bot.git
synced 2026-03-31 23:34:04 +00:00
63 lines
2.4 KiB
Markdown
63 lines
2.4 KiB
Markdown
# HOUSEBOT-062: First Deployment Runbook and Cutover Checklist
|
|
|
|
## Summary
|
|
|
|
Document the exact first-deploy sequence so one engineer can provision, deploy, cut over Telegram webhook traffic, validate the runtime, and roll back safely without tribal knowledge.
|
|
|
|
## Goals
|
|
|
|
- Provide one runbook that covers infrastructure, CD, webhook cutover, smoke checks, and scheduler enablement.
|
|
- Close configuration gaps that would otherwise require ad hoc manual fixes.
|
|
- Add lightweight operator scripts for webhook management and post-deploy validation.
|
|
|
|
## Non-goals
|
|
|
|
- Full production monitoring stack.
|
|
- Automated blue/green or canary deployment.
|
|
- Elimination of all manual steps from first deploy.
|
|
|
|
## Scope
|
|
|
|
- In: first-deploy runbook, config inventory, smoke scripts, Terraform runtime config needed for deploy safety.
|
|
- Out: continuous release automation redesign, incident response handbook.
|
|
|
|
## Interfaces and Contracts
|
|
|
|
- Operator scripts:
|
|
- `bun run ops:telegram:webhook info|set|delete`
|
|
- `bun run ops:deploy:smoke`
|
|
- Runbook:
|
|
- `docs/runbooks/first-deploy.md`
|
|
- Terraform runtime config:
|
|
- optional `bot_mini_app_allowed_origins`
|
|
|
|
## Security and Privacy
|
|
|
|
- Webhook setup uses Telegram secret token support.
|
|
- Post-deploy validation does not require scheduler auth bypass.
|
|
- Mini app origin allow-list is configurable through Terraform instead of ad hoc runtime mutation.
|
|
|
|
## Observability
|
|
|
|
- Smoke checks verify bot health, mounted app routes, and Telegram webhook state.
|
|
- Runbook includes explicit verification before scheduler jobs are unpaused.
|
|
|
|
## Edge Cases and Failure Modes
|
|
|
|
- First Terraform apply may not know the final mini app URL; runbook includes a second apply to set allowed origins.
|
|
- Missing `DATABASE_URL` in GitHub secrets blocks CD entirely so schema-dependent deploys cannot ship without migrations.
|
|
- Scheduler jobs remain paused and dry-run by default to prevent accidental sends.
|
|
|
|
## Test Plan
|
|
|
|
- Unit: script typecheck through workspace `typecheck`.
|
|
- Integration: `bun run format:check`, `bun run lint`, `bun run typecheck`, `bun run test`, `bun run build`, `bun run infra:validate`.
|
|
- Manual: execute the runbook in dev before prod cutover.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] A single runbook describes the full first deploy flow.
|
|
- [ ] Required secrets, vars, and Terraform values are enumerated.
|
|
- [ ] Webhook cutover and smoke checks are script-assisted.
|
|
- [ ] Rollback steps are explicit and environment-safe.
|