Audit & annotate catalog bundles with upgrade-safety metadata (tracks try-hola/hola#284)

[pofallon]

Summary

Audit every catalog bundle for upgrade hazards and annotate it with the upgrade-safety metadata being designed in try-hola/hola#284 (breaking, minFromVersion, waypoints[], bundled-datastore majorVersion, sidecarTransform, preUpgradeBackup, …). This is the apps-repo side of that work: #284 adds the fields and enforcement to the server; this issue tracks populating them per app.

Blocked on the Phase 0 fields from #284 landing, but the audit (which app exhibits which hazard) can start now and feed the schema.

Hazard taxonomy (from try-hola/hola#284)

H1 forward-only/no-downgrade · H2 no-version-skip/min-from-version · H3 bundled-datastore major bump · H4 coupled/swapped sidecar · H5 required manual command · H6 breaking config/env · H7 mandatory pre-upgrade backup · H8 backup-unsafe versions.

Per-app audit checklist

For each bundle: does it bundle a datastore (Postgres/MySQL/Redis/SQLite)? does upstream forbid version skips or define waypoints? does a major need a manual migration or sidecar swap? then fill the metadata once the fields exist.

• immich — known hazards (verified): bundles its own Postgres (VectorChord image, digest-pinned); H1 forward-only; H2 upstream floors/waypoints (e.g. floor 1.107.2, waypoint 1.132.3 before 1.137.0, blacklist transit 1.136.0); H4 pgvecto-rs→VectorChord DB image swap at 1.133.0 (also drops command/healthcheck); H3 on the bundled Postgres major; H7 back up first. Highest-priority annotation target.
• postiz — bundles two Postgres (postiz-postgres:17-alpine, temporal-postgres:16-alpine) + Redis + Temporal → H3 on both PG majors; verify upstream migration behavior across postiz majors (H1). Note the Temporal search-attribute coupling we already handle.
• paperless-ngx — audit: bundled Postgres (H3) + Gotenberg coupling (H4, 7→8 at 2.11), Whoosh→tantivy reindex at 3.0.0 (H5), exports broken on 2.0.0/2.0.1 (H8).
• gitea — auto-migrates on start (H1, no-downgrade across minors); audit whether our bundle uses SQLite or a bundled DB (H3).
• vaultwarden — embedded diesel migrations (H1); ADMIN_TOKEN Argon2 + $$ escaping / port 3012 removal are H6 (audit our env templating).
• mealie — audit datastore (SQLite vs bundled Postgres) and upstream migration constraints.
• actual-budget — audit (SQLite-ish; budget-file format migrations?).
• n8n — audit datastore + any breaking env across majors.
• backrest — audit (it is the backup app; low data-migration risk but confirm).
• homepage — config-only, stateless-ish; likely H6-only (config schema changes). Confirm.
• uptime-kuma — SQLite in /app/data; H1 on its own schema. Confirm no-skip rules.
• guacamole — bundled DB (guacd + DB)? audit H3 and the schema-init/upgrade scripts.
• webtop — mostly stateless desktop; audit persisted config.
• hangar — SQLite at /data; H1 forward-only on its own schema (currently 0.1.0, pre-1.0 — expect breaking minors). Low risk today.

Deliverable

Once #284 ships the fields, a follow-up PR per app (or a batch) adding the metadata, prioritised immich → postiz → paperless-ngx (the datastore-bundling, hardest-migration apps). The audit notes above should land in each package README's upgrade section regardless.

Related

• Safe stateful app upgrades: migration signaling, version-skip guards, pre-upgrade snapshots & data-aware rollback hola#284 — the server-side design (fields, enforcement, snapshots, hooks).

---

🤖 Drafted with Claude Code