diff --git a/docs/backup/service-backup-template.md b/docs/backup/service-backup-template.md new file mode 100644 index 0000000..911ffc1 --- /dev/null +++ b/docs/backup/service-backup-template.md @@ -0,0 +1,44 @@ +# Per-service backup record — template + +Copy this file to `roles//BACKUP.md` when building a **stateful** service +role (ADR-022). It is the per-service **backup record**: what state the service holds, +how it is captured consistently, and how it is restored. The structured parts are +**rendered from the role's `backup__*` data** (the single source of truth that also +drives `/check-backup`) — keep the data authoritative and regenerate this file rather +than hand-editing the tables. The prose "Restore notes" tail is hand-written. + +A **stateless** service (holds no persistent data) does not get a `BACKUP.md`; it sets +`backup__state: false` with a reason in its role defaults instead. + +Delete this preamble in the copy and start from the heading below. + +--- + +# Backup — + +## State captured + +Rendered from `backup__*`: + +| What | Source | How captured | +|---|---|---| +| data dir(s) | `` | file-level, pulled read-only | +| database | `` → `` | logical dump (default; ADR-022 Decision 7) | + +- **Quiesce:** `` — `true` means the service is stopped → backed up → + restarted (escape hatch for data that cannot be dumped live; ADR-022 Decision 7 B). +- **RPO:** ~24 h (nightly; ADR-022 Decision 2). + +## Restore procedure + +1. Re-provision the host (Terraform) and redeploy this role (Ansible) — Model A. +2. `restic restore` the latest snapshot for `` into ``. +3. Replay each `` into its database. +4. Confirm with this role's `VERIFY.md` checks (ADR-008/017). + +## Restore notes + +Prose the data can't capture — ordering gotchas, "restore the DB before the data dir", +known-tricky migrations. + +-