Runbooks¶
Operational runbooks for the homelab. Each file covers one procedure the fleet
can hit at any time. Read docs/nodes.md and
docs/networking.md first — the runbooks act against that
reality.
Index¶
| Runbook | Covers |
|---|---|
| node-setup.md | SSH key, GitHub access, and repo clone on a new node |
| restic-restore.md | Restore data from the Backrest/restic repos (pihdd + gdrive) |
| node-rebuild.md | Rebuild a node from scratch (vps-apps / pi-home / vps-net) |
| certificate-renewal.md | What TLS exists and why the edge certs renew on their own |
| netbird-down.md | Recovery when Netbird / the mesh drops, incl. tunnel fallbacks |
| vaultwarden-backup.md | Vaultwarden backup & restore (pi-home, SQLite) |
| home-assistant-backup.md | Home Assistant backup & restore (vps-apps) |
| mesh-dns-flapping.md | "DNS slow / DietPi dying" — NetBird restart storms, stale resolvers |
| hermes-webui.md | Operate/upgrade the Hermes web front-end on vps-apps (mesh-only, local build) |
Consistent procedure checklist¶
Whenever following a runbook, apply the shared steps:
- Confirm the thing you're about to change is the one the runbook describes (read the reference docs; the fleet has drifted before).
- Get approval for anything on vps-net, volume removal, a data restore, or
a firewall/SSH change (see
CLAUDE.md, "Ask before doing"). - Back-up before restore — never overwrite live state without a rollback copy.
- Verify after — don't trust the command output alone; confirm the app works (log in, load data, run one export).