diun document

2026-04-29 12:12:34 -04:00
parent 24525b5cf3
commit cf50764fa2
4 changed files with 80 additions and 1 deletions
@@ -306,3 +306,53 @@ curl -I http://minecraft.thekims.family
 # Verify SMART, ZFS, and disk space are healthy
 /opt/argento/scripts/disk-health-check.sh
 ```
+
+---
+
+## Maintenance: Postgres major version upgrade
+
+A postgres major bump (e.g. 17 -> 18) cannot reuse the old data dir -- the
+on-disk format changes. Re-init and reload from `pg_dumpall`. `backup.sh`
+already produces a daily dump for both Nextcloud and Immich.
+
+Procedure (Nextcloud; Immich notes at the end):
+
+```bash
+cd /opt/argento/docker/nextcloud
+
+# 1. Force a fresh dump so it reflects current state, not yesterday's.
+/opt/argento/scripts/backup.sh
+
+# 2. Stop the stack. Nothing will write to the DB after this.
+docker compose down
+
+# 3. Move the dump out of the data dir before nuking it.
+cp db/pg_dumpall.sql /tmp/nc-pg_dumpall.sql
+mv db db.old
+
+# 4. Bump the postgres image tag in compose.yaml (e.g. 17-alpine -> 18-alpine).
+
+# 5. Start only postgres so it initializes a fresh data dir, then wait for it.
+docker compose up -d postgres
+docker compose logs -f postgres   # wait for "ready to accept connections", Ctrl-C
+
+# 6. Restore. Connect to the default 'postgres' DB so the dump can recreate
+#    the 'nextcloud' DB itself.
+docker exec -i nextcloud-db psql -U nextcloud -d postgres < /tmp/nc-pg_dumpall.sql
+
+# 7. Bring up the rest of the stack and verify the app end-to-end.
+docker compose up -d
+
+# 8. Once verified, remove the old data dir and the temp dump.
+rm -rf db.old /tmp/nc-pg_dumpall.sql
+```
+
+**Immich differences:**
+
+- Data dir is `${DB_DATA_LOCATION}` from `.env` (not under `docker/immich/`),
+  so step 3 is just `mv "$DB_DATA_LOCATION" "$DB_DATA_LOCATION.old"` -- the
+  dump at `docker/immich/db/pg_dumpall.sql` is in a separate dir and stays put.
+- DB container is `immich_postgres`, user is `${DB_USERNAME}` from `.env`.
+- Immich pins to a specific postgres image (`ghcr.io/immich-app/postgres`)
+  with a digest -- check Immich release notes before bumping; they coordinate
+  the upgrade, you usually just follow their version.