scripts/backup/README.md

# Backup and restore

Scripts for the native VMs (production and test). They run outside the app, so a broken app still backs up. `deploy/vm/install.sh` installs them; the steps and the restore procedure are in [docs/DEPLOY.md](../../docs/DEPLOY.md), "Backups on a VM" and "Restore on a VM".

| File | Installed as | What it is |
|---|---|---|
| `ps-backup.sh` | `/usr/local/sbin/ps-backup` | Nightly `pg_dump -Fc` plus `pg_dumpall --globals-only --no-role-passwords`, as the postgres OS user on the local socket. Checked with `pg_restore --list`, 7 kept, `last-success` and `last-failure` markers. |
| `ps-restore.sh` | `/usr/local/sbin/ps-restore` | Restores a dump into a fresh database, applies the globals, copies stored files into an assets folder without overwriting, checks every file's sha256 against the database, prints row counts. |
| `packetstation-backup.service` | `/etc/systemd/system/` | Oneshot as root, sandboxed, writes only `/var/backups/packetstation`. |
| `packetstation-backup.timer` | `/etc/systemd/system/` | 02:00 America/Denver every day, `Persistent=true`. |
| `backup.conf.example` | `/etc/packetstation/backup.conf` | `name database folder`, one line per stack. |

Tests: `tests/server/test_backup_scripts.py` runs both scripts with fake PostgreSQL tools (`PG_BINDIR`) and a fake user switch (`PG_AS`).

## What a backup is

In `/var/backups/packetstation` (root:packetstation 0750):

- `ps-<UTC stamp>.dump`: the app database, custom format. Mode 0600.
- `ps-<UTC stamp>.globals.sql`: the roles, without passwords. Mode 0600.
- `last-success`, `last-failure`: one line, `<ISO UTC time> <dump name>` (a failure adds the reason). Mode 0644. The worker's backup-check job reads them through the folder's group.

Each dump is written under a temporary name (`.ps-….partial`), checked, then renamed. A failed run leaves no partial file and writes `last-failure`. Exit 1 if any stack failed, 2 for a usage or config error.

Not in the dump: the stored files (`/var/lib/packetstation/assets`), `/etc/packetstation` (env file, secrets, CA) and the archive share. The PBS backup of the VM covers the first two; the archive is on the QNAP.

## The docker-1 test stack

These scripts no longer talk to Docker. The docker-1 test stack keeps the copies installed in `/usr/local/sbin/ps-backup.sh` and `ps-restore.sh` (the phase 9 versions, in git history up to commit 3fdf063) until it is stopped. Do not install the new scripts on docker-1: its `backup.conf` has the old four-column format, which the new script refuses.
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00			`# Backup and restore`

Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			Scripts for the native VMs (production and test). They run outside the app, so a broken app still backs up. `deploy/vm/install.sh` installs them; the steps and the restore procedure are in [docs/DEPLOY.md](../../docs/DEPLOY.md), "Backups on a VM" and "Restore on a VM".
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			`\| File \| Installed as \| What it is \|`
			`\|---\|---\|---\|`
			\| `ps-backup.sh` \| `/usr/local/sbin/ps-backup` \| Nightly `pg_dump -Fc` plus `pg_dumpall --globals-only --no-role-passwords`, as the postgres OS user on the local socket. Checked with `pg_restore --list`, 7 kept, `last-success` and `last-failure` markers. \|
			\| `ps-restore.sh` \| `/usr/local/sbin/ps-restore` \| Restores a dump into a fresh database, applies the globals, copies stored files into an assets folder without overwriting, checks every file's sha256 against the database, prints row counts. \|
			\| `packetstation-backup.service` \| `/etc/systemd/system/` \| Oneshot as root, sandboxed, writes only `/var/backups/packetstation`. \|
			\| `packetstation-backup.timer` \| `/etc/systemd/system/` \| 02:00 America/Denver every day, `Persistent=true`. \|
			\| `backup.conf.example` \| `/etc/packetstation/backup.conf` \| `name database folder`, one line per stack. \|
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			Tests: `tests/server/test_backup_scripts.py` runs both scripts with fake PostgreSQL tools (`PG_BINDIR`) and a fake user switch (`PG_AS`).
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
			`## What a backup is`

Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			In `/var/backups/packetstation` (root:packetstation 0750):
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
			- `ps-<UTC stamp>.dump`: the app database, custom format. Mode 0600.
			- `ps-<UTC stamp>.globals.sql`: the roles, without passwords. Mode 0600.
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			- `last-success`, `last-failure`: one line, `<ISO UTC time> <dump name>` (a failure adds the reason). Mode 0644. The worker's backup-check job reads them through the folder's group.
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			Each dump is written under a temporary name (`.ps-….partial`), checked, then renamed. A failed run leaves no partial file and writes `last-failure`. Exit 1 if any stack failed, 2 for a usage or config error.
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			Not in the dump: the stored files (`/var/lib/packetstation/assets`), `/etc/packetstation` (env file, secrets, CA) and the archive share. The PBS backup of the VM covers the first two; the archive is on the QNAP.
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			`## The docker-1 test stack`
Phase 9: Admin completion, reconcile, notifications, integrity, backups 2026-10-21 18:27:09 -06:00
Native VM install kit: systemd units, launcher, install and upgrade scripts; backups, restore and doctor without docker exec; DEPLOY.md VM, NPM and NFS sections 2026-10-30 18:08:48 -06:00			These scripts no longer talk to Docker. The docker-1 test stack keeps the copies installed in `/usr/local/sbin/ps-backup.sh` and `ps-restore.sh` (the phase 9 versions, in git history up to commit 3fdf063) until it is stopped. Do not install the new scripts on docker-1: its `backup.conf` has the old four-column format, which the new script refuses.