0042. A backup restores the instance by itself; the recovery kit, kept outside, is its only key
Status: accepted, 2026-10-30. Extends 0014 from one snapshot restored with the stock
restic to the whole instance.
Context
xvii server restore fetched xvii-node from the project's release store, which on the project's own instance is
the control plane that died; Caddy from its build service; PostgreSQL in whatever major the distribution ships,
which may be older than the dumps. It re-issued every certificate at once, stopped at the first source that
failed, and told nothing about DNS. The recovery kit was one per destination, its download recorded once, and its
only copy in the product sealed with a key that lives inside the backups it unlocks; the specified escrow under an
instance master key was never built, and couldn't help: anything kept on the instance is lost with it.
Decision
- The backup carries what restores it: xvii-node for both CPUs with its signed sums, every release in use,
Caddy's binary and certificates, the PostgreSQL major and roles. A restore needs only the recovery kit, the
CLI or no computer at all (a cloud-init document in the kit), and the distribution's package mirrors (PGDG's when
the major isn't the distribution's) — never the old instance, a release store or Caddy's build service.
- Nothing runs unverified. xvii-node taken from a backup runs only after its sums verify with a trusted release
key, in the CLI or in the cloud-init script.
- A restore keeps going, resumes and tells. A failed source is listed and its service left stopped while the
rest comes back; running it again continues; the summary gives each source's age, the steps' times and the DNS
records to move, and with the instance's DNS token it moves only those that pointed at the old server.
- One recovery kit for the instance, versioned, carrying every destination, the archive's configuration and a
check code. It is kept outside the instance, nowhere inside it; backups asks every superuser until one types the
current version's check code, and again every 90 days.
Consequences
- The backup grows by the releases in use and Caddy, both deduplicated night to night.
- A kit pasted into a provider's user data stays in that provider's metadata: the restore says to rotate the
destinations' keys afterwards.
- Whoever signs the instance's releases keeps the signing key outside the instance too; it is part of recovery.
- A drill (ADR 0038) restores the same way every month, so this path is exercised, not only written.
- Design:
superpowers/specs/2026-10-30-backups-dr-design.md in this repository.