Upgrading Layer 1 Tools

Fool-proof guide — check, plan, backup, upgrade, verify. Never auto-apply.

Golden rules (read first)

Never auto-apply upgrades. Checking on a schedule is fine; applying always needs a human and --confirm.
Always run plan before apply. Read the full plan — especially Authentik major-version jumps.
Never copy-paste commands from plan. The plan is a preview. Only apply --confirm runs the full compose stack, backup, and rollback. Plain docker compose in the install folder can miss override/mail files and wipe data.
Backup happens automatically on apply — but only if you use the upgrade manager. Manual upgrades need manual backups first.
One tool at a time. Do not upgrade Plane and Authentik in the same session unless you enjoy debugging two broken stacks.
Upgrade Authentik before or after SSO apps carefully — if auth is down, Plane SSO logins fail. Prefer a maintenance window.
Read the release notes linked in the plan output before confirming.

Program: /opt/ryrahcrew/upgrade-manager/upgrade-manager
Config: /opt/ryrahcrew/upgrade-manager/config.yml (paths, DB containers, health URLs — do not hand-edit current_version)
History: /opt/ryrahcrew/upgrade-manager/upgrade-log.md
Backups: /opt/ryrahcrew/upgrade-manager/backups/<tool>-<timestamp>/
Full README: /opt/ryrahcrew/upgrade-manager/README.md on the VPS

1. Check — cd /opt/ryrahcrew/upgrade-manager && ./upgrade-manager check — shows current vs latest for Plane and Authentik.
2. Plan — ./upgrade-manager plan <tool> — e.g. plan plane. Prints target version, changelog URL, backup plan, and the exact commands apply will run. Stops here. Changes nothing.
3. Apply — only when ready: ./upgrade-manager apply <tool> --confirm. Re-prints the plan, backs up, upgrades, health-checks. On failure → automatic rollback (restores install tarball, starts stack, replays DB dump).
If no upgrade is available, apply --confirm prints the plan and exits — nothing is changed.
Optional Plane flag: --merge-env appends missing keys from variables-upgrade.env into plane.env (never overwrites existing values).
View history: ./upgrade-manager log
MCP read tools (for agents): infra_read_upgrade_check, infra_read_upgrade_plan, infra_read_upgrade_log — check/plan only, never apply. See MCP guide.

Database: pg_dump --clean --if-exists from the tool's Postgres container (see table below).
Install directory: full tarball of the tool's install_path — all compose files, .env, overrides, mail overlays.
Stored under backups/<tool>-<timestamp>/database.sql and install.tar.gz.
Apply aborts if either backup file is missing or empty — upgrade does not start.
On health-check failure: tarball restored over install path, database replayed, stack restarted.

Plane — Path: /opt/plane/plane-app. Config: plane.env (APP_RELEASE). Compose: docker-compose.yaml, docker-compose.override.yml, docker-compose.mail.yml. Method: Plane installer (downloads release compose + variables.env). Not a plain docker compose pull. Health: https://plane.ryrahcrew.cloud/api/instances/ (200). DB: plane-app-plane-db-1 / user plane / db plane.
Authentik — Path: /opt/authentik. Config: docker-compose.yml (downloaded fresh) + .env. Compose: docker-compose.yml, docker-compose.override.yml, docker-compose.mail.yml. Method: download compose → pull → up. Health: https://auth.ryrahcrew.cloud/-/health/live/ (200). DB: authentik-postgresql-1 / authentik / authentik. Upgrade major versions sequentially.

☐ Ran ./upgrade-manager check today — note current vs latest.
☐ Ran ./upgrade-manager plan <tool> and read the full output.
☐ Opened the release notes URL from the plan; no breaking changes you aren't ready for.
☐ Maintenance window booked if the tool is SSO-critical (Authentik, or apps that depend on it).
☐ Disk space OK: df -h /opt — backups need room under upgrade-manager/backups/.
☐ You know how to verify the app manually (open URL, sign in, create a test record/issue).
☐ For Plane: reviewed env diff; use --merge-env only if you understand new keys.

Upgrade manager runs an automatic health check; success updates config.yml and upgrade-log.md.
Plane: open https://plane.ryrahcrew.cloud, sign in, open a project board.
Authentik: open https://auth.ryrahcrew.cloud, admin login, check Dashboard → version.
If anything looks wrong after a successful health check: check ./upgrade-manager log and backup path; restore manually from backups/ if needed.

Plane: cd /opt/plane && ./setup.sh → option 5 (Upgrade) → review variables-upgrade.env vs plane.env → option 2 (Start). Use full compose: -f docker-compose.yaml -f docker-compose.override.yml -f docker-compose.mail.yml.
Authentik: cd /opt/authentik && wget -O docker-compose.yml https://docs.goauthentik.io/compose.yml && docker compose pull && docker compose up -d
Manual upgrades: backup DB yourself first — docker exec <db-container> pg_dump -U <user> -d <db> > backup.sql

Optional cron (Mondays 08:00 UTC) — check only, never apply:
0 8 * * 1 cd /opt/ryrahcrew/upgrade-manager && ./upgrade-manager check >> /var/log/ryrah-upgrade-check.log 2>&1
Review the log when you have time; run plan only when you intend to upgrade.
Disable a tool in config.yml with enabled: false to skip it entirely.

Apply says backup failed / container restarting: fix the stack first (e.g. docker ps -a, container logs). Backup waits up to 120s for Postgres to be ready.
Rollback failed / no such container: fixed in current upgrade manager — rollback now restores config, starts the stack, then replays the DB dump.
Plan exit code 1 with “No upgrade available”: normal — means you are already on latest. apply --confirm will also refuse to change anything.