household-bot/docs/specs/HOUSEBOT-062-first-deploy-runbook.md

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.