le-app/docs/le-app-database-migration/phase2a-host-maintenance/backup-readiness-plan.md

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.

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.