From 1b9264dc5a54c3bce138bd838a8d53a1887ba80b Mon Sep 17 00:00:00 2001 From: Smith Labs LLC <232409717+SmithLabsLLC@users.noreply.github.com> Date: Tue, 4 Aug 2026 14:01:24 -0400 Subject: [PATCH] docs(deploy): clarify Git backup and recovery Signed-off-by: Smith Labs LLC <232409717+SmithLabsLLC@users.noreply.github.com> --- deploy/charts/buzz/README.md | 11 +++++++++-- deploy/charts/buzz/templates/NOTES.txt | 9 +++++++-- deploy/compose/README.md | 21 +++++++++++++++++++++ deploy/compose/run.sh | 15 ++++++++++++--- 4 files changed, 49 insertions(+), 7 deletions(-) diff --git a/deploy/charts/buzz/README.md b/deploy/charts/buzz/README.md index b2778df28b..2b99bf98fe 100644 --- a/deploy/charts/buzz/README.md +++ b/deploy/charts/buzz/README.md @@ -207,10 +207,17 @@ Save these. Losing any of them is data loss. See NOTES.txt printed by `helm inst 1. `BUZZ_RELAY_PRIVATE_KEY` — relay identity. Rotating it = new identity (federation peers will not recognize the relay). 2. PostgreSQL database — the canonical event store. -3. S3 bucket — media blobs (chart default bucket: `buzz-media`). -4. Git PVC — repo on-disk state served by the relay's git endpoint. +3. Complete S3 bucket — the durable source of truth for media plus Git packs, manifests, and manifest pointers (chart default bucket: `buzz-media`). +4. Git PVC — optional scratch data and a process-local pack cache. Its cache contents are not reused after a relay restart, and it is not a repository backup. 5. Owner private key — held by the operator, not by this chart. Restore by re-installing with the same `ownerPubkey`. +Stop write traffic while taking the PostgreSQL and object-store snapshots when +possible. If the storage provider only supports ordered live snapshots, capture +PostgreSQL before the object store. After a restore, start an isolated relay and +perform an authenticated clone, then compare the expected refs, commits, and +trees. A healthy pod, database row counts, object counts, or a restored Git PVC +do not prove repository recovery. + ## Honest limitations (v1) - **Bundled MinIO is eval-only.** The quickstart profile runs an in-cluster diff --git a/deploy/charts/buzz/templates/NOTES.txt b/deploy/charts/buzz/templates/NOTES.txt index b409f4d942..084f468628 100644 --- a/deploy/charts/buzz/templates/NOTES.txt +++ b/deploy/charts/buzz/templates/NOTES.txt @@ -47,10 +47,15 @@ 1. BUZZ_RELAY_PRIVATE_KEY — relay identity. Rotating it = identity change; federation peers will treat the relay as a new identity. 2. PostgreSQL database{{ if .Values.postgresql.enabled }} ({{ .Release.Name }}-postgresql PVC){{ end }} - 3. S3 bucket "{{ .Values.s3.bucket }}" — media blobs - 4. Git PVC ({{ include "buzz.fullname" . }}-git) — repo on-disk state + 3. Complete S3 bucket "{{ .Values.s3.bucket }}" — source of truth for media + plus Git packs, manifests, and manifest pointers + 4. Git PVC ({{ include "buzz.fullname" . }}-git) — optional scratch and a + process-local pack cache; it is not a repository backup 5. Owner private key (held by the operator, NOT the chart) — restore by re-installing with the same ownerPubkey. + Stop write traffic while taking data snapshots when possible. If only ordered + live snapshots are available, capture PostgreSQL before the object store. + Test a restore with an authenticated clone and compare refs, commits, and trees. ────────────────────────────────────────────────────────────────────────────── Degradation warnings diff --git a/deploy/compose/README.md b/deploy/compose/README.md index bb0e63fe15..f5a5df514a 100644 --- a/deploy/compose/README.md +++ b/deploy/compose/README.md @@ -46,6 +46,27 @@ keypair. Run `./run.sh backup-hint` for the backup checklist. +## Backup and recovery + +Back up `.env`, PostgreSQL, Redis, and the complete configured MinIO/S3 bucket +from the same maintenance window. Stop the stack while taking the data +snapshots when possible. If the storage provider only supports ordered live +snapshots, capture PostgreSQL before the object store. The object store is the +durable source of truth for Git packs, manifests, and manifest pointers as well +as media. + +The `buzz-git-data` volume holds only scratch data and a process-local pack +cache. Its cache contents are not reused after a relay restart, and the volume +is not a repository backup. + +A recovery test must restore the coordinated data into an isolated stack and +perform an authenticated clone. Compare the recovered branch and tag refs, +commits, and trees with values recorded before the backup. Container health, +database row counts, object counts, or a restored `buzz-git-data` volume do not +prove that a repository can be read. See +[`docs/git-on-object-storage.md`](../../docs/git-on-object-storage.md) for the +storage model. + ## Validation Before sharing an install link publicly, verify a fresh install with: diff --git a/deploy/compose/run.sh b/deploy/compose/run.sh index d5465ea1f5..77246c4b19 100755 --- a/deploy/compose/run.sh +++ b/deploy/compose/run.sh @@ -42,11 +42,20 @@ Back up these before upgrades and on a regular schedule: - deploy/compose/.env, especially BUZZ_RELAY_PRIVATE_KEY, DB/Redis/S3 secrets, and BUZZ_GIT_HOOK_HMAC_SECRET - The owner private key if bootstrap generated one for RELAY_OWNER_PUBKEY - Postgres data (prefer pg_dump or a quiesced volume snapshot) -- MinIO/S3 bucket contents for media and git objects -- buzz-git-data volume (BUZZ_GIT_REPO_PATH=/data/git) +- Redis data (prefer an RDB export or a quiesced volume snapshot) +- The complete configured MinIO/S3 bucket; it is the source of truth for media + and Git packs, manifests, and manifest pointers +- buzz-git-data holds only Git scratch data and a process-local pack cache; + backing it up is optional, its cache is not reused after a relay restart, + and it cannot replace the object-store backup - Caddy data/config volumes if using compose.caddy.yml -Keep Postgres + object/git state snapshots from the same maintenance window. +Stop the stack while taking data snapshots when possible. If the storage provider +only supports ordered live snapshots, capture Postgres before the object store. +Keep Postgres, Redis, and object-store snapshots from the same maintenance window. +After a restore, start an isolated relay and perform an authenticated clone, then +compare the expected refs, commits, and trees. A healthy container or restored +buzz-git-data volume alone does not prove Git recovery. MSG }