hardbyte / hardbyte/awa

Operations handbook: consolidate the production-running docs into one narrative

Open
#379 0 comments 0 reactions 0 assignees View on GitHub
docs
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.