Operations handbook: consolidate the production-running docs into one narrative
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
## Motivation
Running Awa in production currently means reading `deployment.md`, `deploying-on-managed-postgres.md`, `troubleshooting.md`, the upgrade guides, and scattered sections of `configuration.md` — each excellent, none the front door. 0.7 adds more (pooler matrix, doctor, health endpoints, Helm, auth). The handbook is the consolidation.
## Scope
One coherent "run Awa in production" narrative on the docs site:
- Topology chooser: the four deployment surfaces (workers / maintenance-only / callback ingress / admin UI) + the serverless tick() shape, and when to use each.
- Postgres care: MVCC discipline, autovacuum guidance, pooler matrix, sizing (folding in the managed-Postgres guide).
- Day-2 operations: monitoring (dashboards + alert pack), `awa doctor`, DLQ workflow, batch operations, queue pause, backpressure response.
- Upgrades: the staged-transition mental model, rollback boundaries, per-release guides.
- **Production-readiness checklist**: one page an operator can literally tick before go-live.
Existing docs become sections or get absorbed; no content deleted without a redirect/pointer.
## Acceptance
- Handbook published on the docs site; production checklist exists as a single page.
- Every 0.7 operational feature (doctor, health, alerts, auth, Helm, tick) is reachable from the handbook.
- `troubleshooting.md` entries cross-link doctor checks and alert-pack rules.
## References
Roadmap: `docs/0.7-roadmap.md` (WS-6, NEW-15). Depends on: docs site, doctor, alert pack, pooler matrix, Helm (#344), auth (#343).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/0.7-roadmap.md and read deployment.md, deploying-on-managed-postgres.md, troubleshooting.md, the upgrade guides, and configuration.md to map existing content. Review the docs-site structure and referenced doctor, alert-pack, Helm, auth, health, pooler, and tick material. Done means the handbook and standalone checklist are published, all listed operational features are reachable, and troubleshooting entries cross-link the doctor checks and alert rules.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- helm, postgresql, rust
- Domain
- databases, devops, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100