Runbooks

Step-by-step procedures for known operational tasks. Read the right runbook before you start — they exist so you do not improvise under stress.

When something is broken

1. Check incident-response.md first — it routes you to the right runbook
2. Once routed, follow the runbook to the letter
3. If the runbook is wrong or incomplete, fix it after the incident

Available runbooks

Runbook	Use when
restore-postgres.md	A single DB needs to roll back
restore-volume.md	A Docker volume is corrupted or wiped
restore-from-snapshot.md	The whole VPS needs to roll back
docs-rebuild.md	Publish documentation changes
shared-state-locking.md	Editing a shared .env or running a multi-step git transaction under /opt

Writing a new runbook

Template every runbook against this shape:

1. When to use — one sentence describing the trigger
2. Cost / blast radius — what is disrupted
3. Prerequisites — access, info, downtime window
4. Steps — numbered, copy-pasteable shell where possible
5. Verify — how do you know it worked
6. Rollback — what to do if your fix made it worse
7. Escalation — when to stop and call João

A runbook that you cannot follow at 03:00 is not a runbook.

Post-mortems

Live in post-mortems/ (created on first use). One file per incident: what happened, root cause, prevention.