docs: add storage backend drill walkthrough (BCTL-0) - #99
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
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.local,rclone(local and s3 remotes), ands3backends, plus a live PostgreSQL 17 database. All ten screenshots are that run's output, not mock-ups.Changes
docs/18-storage-backend-drill.mddocs/public/images/storage-backend-drill/.txtcaptures, plus a README documenting provenance and the regeneration commanddocs/05-configuration.mdrestic initfor backends added after setup, and at the drilldocs/09-restore-guide.mddocs/README.md,README.md,docs/.vitepress/config.mtsNotes 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.familyis 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.mdsays 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:buildpasses (VitePress fails on dead links by default)npm run lint:check,npm run lint:strict,npm run build,npm run lint:dead-codepassnpm run test:covpasses