Updating Catalyst

Prerequisites

• The panel is running from the bundled Docker stack for the in-panel updater; a standalone install uses the manual path below.
• A pre-update database backup — this is the rollback for everything except node agents (backups).
• Administrator access to Admin → System (admin.write).

The order (always)

1. Read the release notes. Note breaking changes, migration steps, and minimum versions.
2. Back up the database (admin backups).
3. Update the panel (below). Database migrations run automatically at backend startup.
4. Verify the panel: log in, open a server console, check a backup listing.
5. Update nodes one batch at a time (updating a node).

Update the panel from the UI

When Catalyst runs from the bundled Docker stack, the panel updates itself.

1. Open Admin → System and find the Auto Updater section. It shows the Current version, the Latest version, and an Update status badge. If a release is available it reads Update available; otherwise Up to date.
2. Select Trigger Update. A Panel update dialog opens and streams the live log: Downloading update, then Restarting services. The panel goes down briefly and reconnects on its own; the page reloads into the new version when it finishes.
3. If the dialog shows Update failed, open the panel’s System Errors page (or collect a diagnostics bundle) for the reason before retrying.

The button is only enabled when the panel detects it is running in Docker and a newer release exists. On a standalone install the section shows Auto-update is only available when running in Docker. Please update Catalyst manually. — use the manual path below.

Automatic updates

The Auto Updater section also controls the panel’s own automation, and these settings are stored in the database — they apply immediately, with no redeploy:

• Panel update automation — poll for new releases.
• Install panel updates automatically — apply a release without confirming. Leave this off when you want to read the release notes first.
• Check for updates — how often the panel polls (1 hour to 24 hours).
• Check now — poll immediately, for when you do not want to wait.

AUTO_UPDATE_ENABLED, AUTO_UPDATE_AUTO_TRIGGER, and AUTO_UPDATE_INTERVAL_MS only seed these values on the first read; once you save a change in the panel, the panel wins.

Automatic node updates are opt-in per node in the same section — see updating a node.

Update the panel manually

From the directory that holds your stack (catalyst-docker/):

cd catalyst-docker
bash update.sh                 # refreshes compose/nginx/TLS stack files, keeps .env
docker compose pull            # fetch the new images
docker compose up -d           # recreate containers; migrations run at startup

update.sh --dry-run shows what it would change before touching anything. update.sh upgrades the stack files only — the docker compose pull step is what actually moves you to the new image.

If you run the installer with --update from the parent directory, it delegates to the same script:

bash install.sh --update

Watch the backend logs until migrations finish (docker compose logs -f backend).

Rules

• Pin production to release tags, not main. Track main only in a lab.
• If the panel fails to start after an update, read the container logs before doing anything — most failures are a migration waiting on a lock or an env variable renamed in the release notes.

Rollback

• Panel: restore the database backup, then restart the previous images.
• Nodes: reinstall the previous agent build on the affected node.
• After any rollback, repeat the four verification checks above.

Recovering from a failed migration

The backend runs prisma migrate deploy on every container start (catalyst-backend/docker-entrypoint.sh). If a migration fails, the entrypoint logs migrate deploy failed, refuses a destructive db push (unless ALLOW_DATA_LOSS=1 is set) and starts the backend anyway — which then errors at runtime on the missing schema. Recover in this order.

1. Take a dump first, even if the panel is down — the pre-update backup is the supported rollback (disaster recovery).
2. Read the failure.

   docker compose logs backend | grep -A 20 -i migration

3. Inspect the migration table for the row that never finished:

   docker compose exec catalyst-postgres psql -U catalyst -d catalyst_db

   SELECT migration_name, started_at, finished_at, rolled_back_at
   FROM "_prisma_migrations"
   ORDER BY started_at DESC
   LIMIT 5;

   A row with finished_at NULL and rolled_back_at NULL is the failed migration.
4. Fix the cause, then re-run. Most failures are a transient lock, a version/env mismatch, or a full disk. Once fixed, recreating the backend re-runs the deploy:

   docker compose up -d backend
   docker compose logs -f backend

5. If it still fails, restore the pre-update dump and redeploy the previous release. That is the rollback the panel supports.

Caution

Never edit or delete an already-applied migration, and do not hand-edit _prisma_migrations. If a migration must be re-applied after a correction, use Prisma’s own prisma migrate resolve --rolled-back <name> from inside the backend image — then redeploy. Setting ALLOW_DATA_LOSS=1 makes the entrypoint fall back to prisma db push --accept-data-loss, which can drop columns; use it only on a throwaway database.

Related

• Panel and node update order: this page and updating a node.
• Pre-update database dump and restore: disaster recovery.
• Backup schedule and storage: backups.
• Update failures at runtime: troubleshooting.