shc / arch / backup-timeline ← lab docs

Every phase exists to shrink one red band

A backup has to read a volume nobody is writing to. The honest way to get that is to freeze the app, and the freeze is the whole cost. So shc cuts a backup into five phases and moves everything expensive outside it: the first rsync pass runs while the app is still serving traffic, so only a delta has to be synced under pause. Tar, checksum and archive all happen after the app is back up. Five acts, playing on their own.

$shc backup create -s myblog prepare

PREPARE runs with the stack still up: hooks, manifest, vault export, and the first rsync pass

it plays on its own; step it yourself with the button, or ← → once it has focus; it takes the loop back after a pause

the same thing, from a shell simulated

simulated: no daemon, no restic, no Docker. The stage is a JavaScript replay of parts shc really has, and the shell output is illustrative; the commands, flags and codes are not. What is exact: the five phases and their contents are internal/modules/backup/phases.go: PREPARE (pre_backup hooks, manifest prep and record capture, vault export to secrets.vlt, app and deployment tars, routed remote-volume captures, and the hot pass-1 rsync), QUIESCE (pre_pause hooks/jobs, then the pause), CAPTURE (the under-pause step only), RESUME (unpause, then post_pause hooks), FINALIZE (tar the staging, host-bind and named-volume captures, converters, totals and checksum, master archive, DB row flip, post_backup hooks, never under pause). Single-stack backups run the same phases back to back, so there is exactly one snapshot code path whether a stack is backed up alone or as a group member. The four capture modes are the captureMode constants in the same file, chosen in PREPARE by probing the filesystem: captureModeNone, captureModeCoW, captureModeRsync, captureModePausedTar. The pause-cost phrasing is quiesce.go's own: CoW is “pause ≈ snapshot creation (ms)”, double-pass is “pause ≈ delta sync”, the fallback is “pause ≈ tar duration”. The percentages drawn are illustrative: the source states the shape, not a ratio. What is real is the ordering, which mode pauses for which step, and that captureModePausedTar is the dev/test path taken when the daemon can't read the volume in-process and no root copier is wired. Invariants, from the file header: (a) a paused stack is always resumed; resume() is idempotent and called via defer, so an error or a panic cannot strand a stack frozen; (b) a stack whose PREPARE fails is excluded from its group while the rest proceed; (c) a failed pause aborts the capture with X500065BKPQAB only in the whole-tar mode; CoW snapshots and delta passes tolerate a degraded pause with a warn (X200063BKPQSC); (d) PauseTimeout bounds the whole quiesce window, per stack when solo and as one shared deadline across a group (--timeout, default 10s; the daemon-side timeouts.RoleQuiesce default is 30s). Three places where a plausible reading and the repo disagree, and the source wins. One: converters do not run under pause. docs/app-development/creating-apps.md says phase: capture “runs during the capture phase”, but phases.go runs every converter in FINALIZE, post-resume, against the static staging copy, and skips them entirely when there is no static copy; a post-resume run would then read the LIVE volume, and a converter's side effects (apps/postgres runs pg_resetwal -f) would corrupt it; the raw bytes captured under pause stand in instead. Two: the converter schema in those docs is stale. They show a list of {name, phase, output, networks}; the implemented schema (orchestrator.go, types.go) is map[string]BackupConverter keyed by the mount name, with no phase and no output field; output leaves through a "@output:/output" volume and is archived as data/@<name>.tar. Every real app uses the map form; see apps/postgres/backup.yaml and apps/mariadb/backup.yaml. Three: the shared pause window belongs to CreateBackupGroupFromRequest (grouping.go), the group-create driver that interleaves the phases group-wide. --all-connected and --with-dependants take a different route: CreateConnectedBackupGroup backs each member up through the restic path under one shared consistency_id and bundles them into a .bkg, and it hard-fails and rolls the completed members back if any member fails, because a partial consistency group is worse than none. Restore and recover are genuinely different commands. shc backup restore replays into a stack that already exists, takes exactly one selector (--id, --file, --before; --before 0m means the newest), stops the stack unless --keep-running, and takes a pre-restore-<backup id> safety backup first unless --no-rollback; if that safety backup fails the restore aborts with X500934RLBKPR before Stop or any replay, rather than mutate live data with no way back (restore.go). There is no shc rollback verb; rolling back is this restore. shc recover rebuilds stacks that are not there, walking validating → ordering → installing → restoring → wiring (recover.go), ordering DB providers before consumers from each manifest's captured integrations, and it can take --consistency-id with no archive at all. shc backup mount is the third door: a read-only, daemon-resident FUSE tree released with shc backup umount <id-or-path>. Every command, flag and code above was checked against docs/reference/cli/ and grepped in internal/. To install shc itself: git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shc && make install.