Skip to content

docs(deploy): clarify Git backup and recovery - #4761

Open
SmithLabsLLC wants to merge 1 commit into
block:mainfrom
SmithLabsLLC:docs/compose-git-recovery
Open

docs(deploy): clarify Git backup and recovery#4761
SmithLabsLLC wants to merge 1 commit into
block:mainfrom
SmithLabsLLC:docs/compose-git-recovery

Conversation

@SmithLabsLLC

@SmithLabsLLC SmithLabsLLC commented Aug 4, 2026

Copy link
Copy Markdown

Summary

  • document the object store as the durable source of truth for Git
  • identify the local Git volume as disposable scratch and process-local cache
  • require coordinated PostgreSQL, Redis, and object-store backups
  • require an isolated authenticated clone with exact ref, commit, and tree
    comparison after restore
  • align the production Compose and Helm operator guidance

Why

The production Compose backup hint currently treats the local Git volume as
authoritative. The Helm README and install notes make the same claim and
describe the object store as media-only. Buzz's current Git implementation
instead stores packs, manifests, and manifest pointers in the configured
object store; the local volume is scratch and process-local cache space.

Contradictory backup guidance can produce an apparently healthy restore which
cannot clone a repository.

Recovery guidance

The revised guidance tells operators to stop the stack for a coordinated
backup, or capture PostgreSQL before the object store. It then requires a
restore into an isolated stack followed by an authenticated clone and
comparison against pre-recorded refs, commits, and trees.

Testing

  • bash -n deploy/compose/run.sh
  • shellcheck deploy/compose/run.sh
  • ./deploy/compose/run.sh backup-hint
  • assertions that Compose and Helm guidance agree on the authoritative Git
    storage and recovery proof
  • render every Helm chart values fixture
  • git diff --check

Review

One Fable 5 xhigh review initially returned NEEDS CHANGES. All accepted and
approved findings were incorporated: the incorrect warm-restart cache claim
was removed, safe snapshot ordering was added, and Helm guidance was aligned.
No second independent review was run.

Scope

This is operator guidance only. It does not change storage code and does not
claim to fix issue #4469. An isolated real-world restore passed, so no
repeatable official code defect was reproduced.

Signed-off-by: Smith Labs LLC <232409717+SmithLabsLLC@users.noreply.github.com>
@SmithLabsLLC
SmithLabsLLC requested a review from a team as a code owner August 4, 2026 18:19
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