docs(wiki): record backup deploy gotchas (compose allowlist + host mount)
CI / check (push) Successful in 40s

Two lessons from the first park-buzi staging deploy, both in backup-recovery.md:
- A new server env var (BACKUP_KEY) must be added to docker-compose.yml's
  server.environment: allowlist, not just the Komodo secret/Stack env — otherwise
  the container never receives it (inspect shows it absent, not empty).
- The backup target must be a host path bind-mounted into the container; a desktop-
  automounted USB (/run/media/...) is invisible inside the container, so Test target
  reports 'does not exist'. Destinations are admin-provisioned (fstab + compose bind-
  mount), not operator-pluggable — partly a threat-model feature. Acknowledged as a
  flexibility limitation; USB-automount-to-container flow deferred.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
This commit is contained in:
2026-06-29 17:38:24 +02:00
parent 8f32d90d28
commit 9c6741a485
2 changed files with 61 additions and 0 deletions
+17
View File
@@ -1976,3 +1976,20 @@ TAG=stage-84f00db; komodo/README.md promotion section + per-booth secret list no
fleet-deployment-komodo open-item resolved + new 'Promotion tiers' table; container-deployment tag list +
:stage. Per-booth secrets (jwt/event_signing/backup) must pre-exist in Core for park-buzi; migrations run at
boot so a promotion auto-migrates the staging ledger (where a bad migration is caught before prod).
## [2026-06-29] fix+doc | First park-buzi backup deploy: BACKUP_KEY allowlist + container mount constraint
First real-world staging deploy surfaced two backup gotchas, both now in [[backup-recovery]]:
(1) BACKUP_KEY was wired as a Komodo secret + Stack-env line but NEVER added to docker-compose.yml's
server `environment:` ALLOWLIST — so the container came up without it (docker inspect: JWT/SIGN present,
BACKUP_KEY absent-not-empty; Backup screen "BACKUP_KEY missing"). A whole session was lost chasing Komodo
(secret name, re-sync, destroy/redeploy, env-only-change-doesn't-force-recreate) before checking the
compose allowlist. Fix: `BACKUP_KEY: ${BACKUP_KEY:-}` next to EVENT_SIGNING_KEY (commit on dev 8f32d90,
promoted dev→stage merge d0b609e → built stage-d0b609e). Lesson recorded: a new server env var ALSO needs a
line in the compose environment block.
(2) The backup target must be a HOST path BIND-MOUNTED into the container — a casually-plugged USB at
/run/media/<user>/<UUID> is invisible inside the container, so Test target rightly says "does not exist".
Provisioning = fstab-by-UUID a stable host path (e.g. /mnt/backup) + bind-mount it in prod compose + set
the in-container path as the UI target. Acknowledged limitation: backups are NOT operator-flexible (no
plug-a-USB-and-go); adding a destination is an admin host+compose change. Partly a feature vs the
operator-adversary threat model (operator can't redirect backups to a removable stick). USB-automount-to-
container flow deferred/not built.