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 Mattermost sequential steps and Twenty 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 Mattermost in the same session unless you enjoy debugging two broken stacks.
Upgrade Authentik before or after SSO apps carefully — if auth is down, Outline and Mattermost logins fail. Prefer a maintenance window.
Read the release notes linked in the plan output before confirming.

Where the upgrade manager lives

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

The only workflow you need (3 commands)

1. Check — cd /opt/ryrahcrew/upgrade-manager && ./upgrade-manager check — shows current vs latest for all five tools.
2. Plan — ./upgrade-manager plan <tool> — e.g. plan mattermost. 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.

What gets backed up (every apply)

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.

Per-tool reference — paths, config, health checks

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.
Outline — Path: /opt/outline. Config: docker.env, .env. Compose: docker-compose.yml, docker-compose.mail.yml. Method: pull image → yarn db:migrate → up. Health: https://docs.ryrahcrew.cloud/ (200). DB: outline-postgres / outline / outline.
Mattermost — Path: /opt/mattermost. Config: .env → MATTERMOST_IMAGE_TAG. Compose: docker-compose.yml, docker-compose.without-nginx.yml, docker-compose.override.yml, docker-compose.mail.yml. Method: update tag → down → pull → up (sequential for major jumps). Postgres data mounts to /var/lib/postgresql/data via override — do not use plain docker compose without all four files. Health: https://chat.ryrahcrew.cloud/api/v4/system/ping (JSON status: OK). DB: mattermost-postgres-1 / mmuser / mattermost.
Twenty — Path: /opt/twenty. Config: .env → TAG. Compose: docker-compose.yml, docker-compose.override.yml, docker-compose.mail.yml. Method: down → update TAG → pull → up (migrations auto-run). GitHub releases (e.g. twenty/v2.18.0) map to Docker tags (e.g. v2.18.5) — the upgrade manager resolves this automatically. Health: https://crm.ryrahcrew.cloud/healthz (JSON status: ok). DB: twenty-db-1 / postgres / default.
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.

Pre-flight checklist (before apply --confirm)

☐ 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 Mattermost: plan lists every intermediate version — do not skip steps.
☐ For Plane: reviewed env diff; use --merge-env only if you understand new keys.

After upgrade — verify success

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.
Outline: open https://docs.ryrahcrew.cloud, SSO login, open a document.
Mattermost: open https://chat.ryrahcrew.cloud, SSO login, post in a test channel.
Twenty: open https://crm.ryrahcrew.cloud, login, open Companies list.
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.

Manual fallback (if upgrade manager fails)

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.
Outline: cd /opt/outline && docker compose -f docker-compose.yml -f docker-compose.mail.yml pull && docker compose run --rm outline yarn db:migrate --env=production-ssl-disabled && docker compose up -d
Mattermost: edit MATTERMOST_IMAGE_TAG in /opt/mattermost/.env, then docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml -f docker-compose.override.yml -f docker-compose.mail.yml down && pull && up -d
Twenty: edit TAG in /opt/twenty/.env, then docker compose down && docker compose -f docker-compose.yml -f docker-compose.override.yml -f docker-compose.mail.yml pull && up -d
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

Weekly version check (safe to schedule)

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.

Troubleshooting

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.
Twenty pull failed with not found: GitHub version ≠ Docker tag. Use apply --confirm — it resolves tags like twenty/v2.18.0 → v2.18.5. Do not hand-set bare 2.18.0 in .env.
Mattermost users disappeared after upgrade: caused by running plain docker compose without all four compose files. Use upgrade manager or the full -f file list from the plan output.
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.

Last verified status (2026-07-08)

Run ./upgrade-manager check on the VPS for live numbers.
All five tools verified healthy after overnight simulation:
Plane 1.3.1 — plan ✅ apply correctly skipped (up to date).
Outline 1.8.1 — plan ✅ apply correctly skipped (up to date).
Mattermost 11.8.2 — plan ✅ apply correctly skipped (up to date). Postgres volume mount fixed in override.
Twenty 2.18.5 (Docker tag for GitHub 2.18.0) — plan ✅ apply ✅ upgraded successfully from 0.2.1.
Authentik 2026.5.3 — plan ✅ apply correctly skipped (up to date).

Open Upgrading Layer 1 Tools → Admin panel Back to hub