Backup & restore

Status: Accepted · Audience: Operator · Area: E — Maintenance

---

Purpose

Make configuration recoverable, so it stops being precious.

This underwrites P6. An operator who cannot recover from a mistake will not experiment, will not update, and will not touch a working system. Fear of breaking things is what leaves stacks running years-old versions.

Backup here means configuration, not media. The library may be terabytes and is often irreplaceable, but it is not what breaks — what breaks is the small, intricate, hard-to-recreate state in the service databases.

Behaviour

Databases are quiesced before capture

Every *arr uses SQLite. Copying an SQLite database while it’s being written produces a file that may restore into a subtly corrupt state — which is worse than no backup, because the failure appears at restore time when it’s most needed.

Services are stopped, or their own backup mechanism used where one exists, before their state is captured. Correctness outranks convenience here.

What is captured

Backups containing credentials are labelled as such

A configuration backup holds the VPN key, provider passwords and every API key. It is exactly as sensitive as the credentials inside it, and operators routinely forget this — copying a backup to cloud storage without a thought.

The label is stated at creation and recorded in the archive.

Automatic before risky operations

Taken automatically before updates (E1), before configuration removal (A6), and before adopting an existing setup (A5). Not offered — taken.

Adoption’s capture reads the operator’s own paths, not lemonfiber’s, and that is what makes it possible to take it before. This requirement briefly said after instead, and the reasoning was sound at the time: a capture was described only in terms of lemonfiber’s own layout — its configuration directory, the service configuration under its data root, the materialised stack — and at adopt time none of that is the thing worth protecting. A whole-stack capture run then would archive lemonfiber’s own empty layout and call it a backup, which is worse than no backup, because it is a backup somebody would rely on.

What was wrong with moving it was that after does not fix it either. Adoption writes one line — the Compose project lemonfiber manages — and moves nothing. The operator’s configuration stays where it was, so a whole-stack capture a moment later describes the same empty layout. The premise that needed changing was never the timing; it was that lemonfiber could only ever capture its own tree.

So the scope is what changed. A capture taken before an adoption covers the existing setup’s own directories, at the host paths the survey already reports for exactly this purpose, and the trigger goes back where the requirement first had it. That is the protection worth having: an operator’s configuration as it stood before a tool they had just met touched anything.

Restore is selective

Whole-stack restore is the common case, but restoring a single service is often what’s actually wanted — one *arr’s configuration mangled while the rest is fine.

Restore verifies before replacing

The archive is validated, its version compatibility checked, and its contents listed before anything is overwritten. A restore that fails partway is far worse than one that refuses to start.

Retention is bounded and predictable

A stated number of backups is kept, oldest pruned. Backups are useless if they silently fill the disk they were protecting.

On the companion

Backups are what an operator thinks about at the worst possible moment, and the companion is where they are when it arrives (N6).

The three scopes captured here are the three an operator agrees to, and N6-R2 requires which one — the whole stack, one service, or an existing project — stated before the work starts and again on the result. The third is the adoption capture described above, and it is the one most worth naming: a copy of somebody else’s directories is not the same undertaking as a copy of ours.

Retention prunes. N6-R3 requires what a new copy removed to be reported with that copy, because it is housekeeping the operator did not ask for individually and would otherwise meet as an archive that is simply absent. Capture can also be paced deliberately, and N6-R4 requires a paced copy told apart from a stalled one — on a progress view watched from somewhere else, that difference is the entire reason to look. And a restore may land data somewhere other than where it came from, which N6-R5 requires the app to say: a restore that silently relocated a library is a restore its operator will believe failed.

A rehearsed run is labelled as a rehearsal wherever its result appears, and is never phrased in the past tense (N6-R1). Unlabelled, it is the report of a backup that does not exist. The capture taken before an adoption is one the operator meets mid-decision rather than having asked for, so N7-R4 requires it stated before that decision is agreed to rather than mentioned after it.

none is an answer. A listing that could not be read is a different one, and N6-R9 forbids showing the second as the first.

States

Edge cases

Acceptance criteria

Related

• E4 Rollback — the quick path for recent changes
• E1 Stack updates — the mandatory pre-update backup
• A6 Uninstall · A5 Migration
• A7 Credential management
• J6 Recovery