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.
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
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.