Skip to content

docs: add storage backend drill walkthrough (BCTL-0) - #99

Merged
vineethkrishnan merged 1 commit into
mainfrom
docs/BCTL-0-storage-backend-drill
Jul 18, 2026
Merged

docs: add storage backend drill walkthrough (BCTL-0)#99
vineethkrishnan merged 1 commit into
mainfrom
docs/BCTL-0-storage-backend-drill

Conversation

@vineethkrishnan

Copy link
Copy Markdown
Owner

Summary

  • Adds docs/18-storage-backend-drill.md, an end-to-end walkthrough for proving a storage backend actually works: configure, initialize the repository, dry run, back up, restore, decrypt, and compare fingerprints against the source.
  • Written after running the drill for real against the local, rclone (local and s3 remotes), and s3 backends, plus a live PostgreSQL 17 database. All ten screenshots are that run's output, not mock-ups.
  • Documents two behaviours that were previously undocumented and both cause real recovery failures: a backend added after initial setup has no restic repository, and the unencrypted dump lingers on the backup host for the full local retention window.
  • Frames the fidelity check as the step that matters. Every step before it can pass while the restored data is silently truncated, so the drill ends by comparing md5 fingerprints rather than row counts.

Changes

Area Description
docs/18-storage-backend-drill.md New 8-step walkthrough: configure, init, dry run, backup, snapshots, restore, decrypt, fidelity check, lock check. Includes an operational-notes section on local plaintext retention and how a degraded remote hangs rather than fails
docs/public/images/storage-backend-drill/ 10 screenshots with their source .txt captures, plus a README documenting provenance and the regeneration command
docs/05-configuration.md Tip in the rclone section pointing at the required restic init for backends added after setup, and at the drill
docs/09-restore-guide.md Tip noting that encryption only needs the public key, so backups can succeed for months while the private key needed to restore them is already lost
docs/README.md, README.md, docs/.vitepress/config.mts Index, doc table, and sidebar entries under "How It Works"

Notes for review

Screenshots deviate from the CLI output in exactly one way. The CLI emits /, but freeze's embedded font has no glyph for either and renders both as tofu boxes, directly on the pass/fail signal. --font.family is not a workaround: freeze v0.2.2 renders a blank image for any non-default font. The captures substitute /. This is recorded in the images README so it is not mistaken for real output later.

Tooling diverges from the existing help center images, which docs/public/images/helpcenter/README.md says were made with silicon. This PR uses freeze per the current standard. Worth deciding separately whether to re-render the older set for consistency.

Project names read drill-* because that is what the drill actually ran under. They are not a proposed naming convention, and the images README says so.

Testing

  • npm run docs:build passes (VitePress fails on dead links by default)
  • All 10 image paths and all 6 internal doc links resolve to real files
  • npm run lint:check, npm run lint:strict, npm run build, npm run lint:dead-code pass
  • npm run test:cov passes
  • commitlint passes
  • Reviewer: confirm screenshots render correctly on the deployed docs site

Adds an end-to-end walkthrough for verifying a storage backend actually works:
configure, initialize the repository, dry run, back up, restore, decrypt, and
compare fingerprints against the source. Written after drilling the local,
rclone, and s3 backends end to end.

Documents two behaviours that were previously undocumented. A backend added
after initial setup has no restic repository and `backupctl run` will not
create one, so it needs an explicit `restic init`. The unencrypted dump also
remains on the backup host for the full `retention.local_days` window, even
though only the encrypted artifact is uploaded.

Screenshots are rendered with freeze rather than the silicon setup used by the
older help center images. freeze v0.2.2 renders a blank image for any
non-default font, and its embedded font has no glyph for the emoji the CLI
emits, so the captures substitute the dingbat check and cross. That
substitution is recorded alongside the images.
@vineethkrishnan
vineethkrishnan merged commit 3829a61 into main Jul 18, 2026
14 of 15 checks passed
@vineethkrishnan
vineethkrishnan deleted the docs/BCTL-0-storage-backend-drill branch July 18, 2026 12:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant