add Phase 2A container and recovery readiness gates

2026-07-12 18:59:45 -04:00 · 2026-07-12 18:59:45 -04:00 · a9fec0d83d
commit a9fec0d83d
parent da03be61a9
15 changed files with 629 additions and 30 deletions
--- a/docs/le-app-database-migration/phase2a-host-maintenance/backup-readiness-plan.md
+++ b/docs/le-app-database-migration/phase2a-host-maintenance/backup-readiness-plan.md
@ -0,0 +1,94 @@
+# Proportional Phase 2A backup-readiness plan
+
+## Verified existing evidence
+
+- `/srv/directus-archive/20260710-175408/SHA256SUMS` verified with return code 0.
+- The repaired `/.snapshots` Btrfs subvolume supports Snapper; snapshots 1–3
+  succeeded.
+- Maintenance creates and directly verifies a uniquely numbered pre-upgrade root
+  snapshot before Pacman.
+
+These facts do not yet justify `LE_PHASE2A_BACKUPS_READY=YES`.
+
+## Snapshot coverage
+
+The explicit root snapshot is crash-consistent coverage of the root `@`
+subvolume, including ordinary paths below it such as `/etc`, `/usr`, `/boot`
+when `/boot` is not a separate mount, and `/var/lib/docker` unless independently
+mounted. It is not an application-consistent database backup.
+
+The following are outside root `@` and therefore outside that snapshot:
+
+- Btrfs subvolumes `@home`, `@root`, `@srv`, `@cache`, `@log`, and `@tmp`;
+- the EFI system partition mounted at `/boot/efi`;
+- ext4 mounts `/mnt/storage`, `/mnt/appdata`, `/mnt/media`, and
+  `/mnt/coldstasis`;
+- tmpfs/runtime mounts.
+
+The protected Directus archive is below `/srv`, so its independent checksum
+verification—not the root snapshot—protects that evidence. Bind-mounted database
+or application state on the separate subvolumes or ext4 mounts is likewise not
+covered by the root snapshot. Unrelated media need not be duplicated merely
+because a consuming container is running.
+
+## Minimum fresh package-maintenance backup set
+
+Before setting the backup attestation, create and test:
+
+1. application-consistent dumps of every active MariaDB/MySQL and PostgreSQL
+   production database, including the transitional `le-directus-source` and
+   `le-payload-pg` databases if they must survive the maintenance window;
+2. a root-only host-configuration archive containing package inventory, `/etc`,
+   GRUB configuration, EFI boot metadata, relevant systemd units/drop-ins,
+   nftables/network configuration, and Docker Compose/deployment definitions;
+3. the explicit root Snapper snapshot already enforced by maintenance;
+4. checksum manifests plus a documented restore test or validated restore
+   procedure for the new dumps and configuration archive.
+
+Do not copy unrelated media libraries or bulk application media solely because
+their containers are running. Database dumps provide application consistency;
+the Btrfs snapshot provides fast crash-consistent package/config rollback.
+
+## Review-only commands
+
+The operator must replace the uppercase placeholders with reviewed root-only
+paths. Credentials must come from existing root-only client configuration or an
+interactive mechanism; never place passwords in command arguments or logs.
+
+```bash
+stamp=$(date -u +%Y%m%dT%H%M%SZ)
+backup_root=/ROOT/ONLY/BACKUP/DESTINATION/le-phase2a-$stamp
+install -d -o root -g root -m 0700 "$backup_root"
+
+pacman -Q > "$backup_root/packages-before.txt"
+cp --preserve=mode,ownership,timestamps /boot/grub/grub.cfg "$backup_root/grub.cfg"
+efibootmgr -v > "$backup_root/efibootmgr.txt"
+
+tar --xattrs --acls --numeric-owner -cpf "$backup_root/host-config.tar" \
+  /etc /usr/lib/systemd/system /boot/grub
+
+mariadb-dump --defaults-extra-file=/ROOT/ONLY/MARIADB-CLIENT-CONFIG \
+  --all-databases --single-transaction --routines --events --triggers \
+  > "$backup_root/mariadb-all.sql"
+
+pg_dumpall --file="$backup_root/postgresql-all.sql"
+
+# Transitional containers: use existing non-secret local authentication only.
+docker exec le-directus-source mariadb-dump \
+  --defaults-extra-file=/ROOT/ONLY/IN-CONTAINER-CLIENT-CONFIG \
+  --all-databases --single-transaction --routines --events --triggers \
+  > "$backup_root/le-directus-source.sql"
+
+docker exec le-payload-pg pg_dumpall \
+  > "$backup_root/le-payload-pg.sql"
+
+find "$backup_root" -maxdepth 1 -type f -print0 |
+  LC_ALL=C sort -z |
+  xargs -0 sha256sum > "$backup_root/SHA256SUMS"
+
+(cd "$backup_root" && sha256sum -c SHA256SUMS)
+```
+
+These commands are a review package, not execution approval. Confirm database
+names, authentication methods, output capacity, dump return codes, nonempty
+outputs, and a restoration test before attesting readiness.