From 9c6741a4852071ff71da81ed941c3372a1dc3ef8 Mon Sep 17 00:00:00 2001 From: Julian Cuni Date: Mon, 29 Jun 2026 17:38:24 +0200 Subject: [PATCH] docs(wiki): record backup deploy gotchas (compose allowlist + host mount) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- wiki/concepts/backup-recovery.md | 44 ++++++++++++++++++++++++++++++++ wiki/log.md | 17 ++++++++++++ 2 files changed, 61 insertions(+) diff --git a/wiki/concepts/backup-recovery.md b/wiki/concepts/backup-recovery.md index 645dc29..d8c3d32 100644 --- a/wiki/concepts/backup-recovery.md +++ b/wiki/concepts/backup-recovery.md @@ -99,6 +99,38 @@ All three supported in the first cut; the manual button and the periodic timer s - **SFTP** — push to an SFTP endpoint, useful for an offsite copy. **FTP is excluded** (plaintext credentials + data); SFTP is the safe equivalent. +### The target must be a bind-mounted host path — NOT a casually-plugged USB (2026-06-29) + +The server runs **inside the `parking-server` container**, so it can only `stat()`/write paths that +are **bind-mounted into that container**. A USB stick the operator plugs in lands at a desktop +auto-mount path on the *host* (`/run/media//`), which **does not exist inside the +container** — so the in-UI **Test target** correctly reports *"location does not exist."* This bit on +the first booth deploy (2026-06-29): `BACKUP_KEY` was finally injected, then the target test failed +because the USB path wasn't visible to the process. + +**So a backup destination is provisioned by the ADMIN at the host level, not chosen ad hoc by the +operator.** The procedure: + +1. Attach the disk (external HDD/SSD/USB) and mount it at a **stable host path** (e.g. `/mnt/backup`) + via **`/etc/fstab` by UUID** — *not* the desktop automounter, whose UUID-named path changes per + drive and vanishes on unplug. +2. **Bind-mount that host path into the container** in the prod compose (e.g. + `/mnt/backup:/mnt/backup` on the `server` service — same pattern as the `/dev/usb` printer + passthrough in [[container-deployment]]). +3. In the UI (Setup → Backup), set the **target directory to the in-container path** (`/mnt/backup`) + and **Test target** — now writable. + +> **This is partly a feature, not just a limitation** ([[threat-model]]): because the destination is +> a host-provisioned bind-mount, the **booth operator cannot redirect backups to a removable stick +> they walk off with** — real destinations are an admin/host decision, on the trusted side of the +> [[trust-boundary]]. A network share (SMB/NFS) is the same shape: mount on the host, bind-mount in. +> +> **Limitation acknowledged:** the backup target is therefore **not operator-flexible** — you cannot +> just plug in a USB and back up from the UI. Adding a new destination = a host `fstab` + compose +> bind-mount change + redeploy. For the appliance model (single-purpose, admin-provisioned) this is +> the right trade; a future "back up to a freshly-plugged removable drive" flow would need host-level +> automount detection wired to the container, which is **deferred / not built**. + ## Retention at the destination **Keep last N + thinned dailies** (e.g. last 7 daily / last 4 weekly) — bounded disk use, and it @@ -155,6 +187,18 @@ timer + the manual route**. What landed: - **Komodo wiring.** `BACKUP_KEY` is a **per-booth Komodo secret** (`[[park_buzi_backup_key]]` in `komodo/resources.toml`; documented in `komodo/.env.komodo.example`), escrowed offsite alongside `EVENT_SIGNING_KEY`. It is the *only* backup env var — target + retention are in the DB. + +> **Gotcha — compose `environment:` is an ALLOWLIST (cost a full booth-deploy session, 2026-06-29).** +> Wiring `BACKUP_KEY` as a Komodo secret + Stack-env line is **necessary but not sufficient**: +> `docker-compose.yml`'s `server.environment:` block only forwards the variables it *names*. The key +> was wired everywhere (secret store, Stack env, `.env.example`, schema) but **never added to that +> compose block**, so the container came up *without* it — `docker inspect ...Config.Env` showed +> `JWT_SECRET`/`EVENT_SIGNING_KEY` present and `BACKUP_KEY` **absent (not empty)**, while the Backup +> screen correctly reported "BACKUP_KEY missing". Diagnosis was muddied by chasing Komodo (secret +> name, re-sync, destroy/redeploy, env-only-change-doesn't-recreate) before checking the compose +> allowlist. **Lesson: a new server env var needs a line in `docker-compose.yml` `server.environment:` +> too — that's the only place env reaches the container.** Fixed: `BACKUP_KEY: ${BACKUP_KEY:-}` next to +> `EVENT_SIGNING_KEY`. Quick check on a booth: `docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' | grep -i backup`. - **`server.ts`** — an **unref'd daily timer** (`backupService.runScheduled`), a **no-op until configured**, and **deliberately NOT run at startup** (a just-power-cut booth shouldn't write to a possibly-unmounted disk; the daily cadence + the manual button cover it). diff --git a/wiki/log.md b/wiki/log.md index 8b8af4f..c97a8a1 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -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// 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.