System update in operation
Overview
An update swaps the code and then runs a fixed sequence of steps. It is the same for every route — whether the update is triggered from the console, from the interface or by a deploy run. An update is therefore never a special case but always the same procedure.
The database is backed up before the steps run. If the backup tool is missing on the server there is a warning instead of an abort — an update that fails on a missing helper program helps nobody.
The steps
- Clear the application cache
- Run migrations
- Synchronise permissions and roles
- Update standard data (existing customisations are preserved)
- Record plugin ownership
- Rebuild the interface if needed
- Warm the cache
- Regenerate the tool catalogue for AI access
- Stop background processes so they restart on the new code
All steps are idempotent. Recovery after a failure is therefore: run it again.
Checking beforehand
A check run says whether an update exists at all without changing anything. It suits a schedule: one return value per state — up to date, update available, error.
What an update does not touch
- Your customisations of standard data. What was changed in this instance stays.
- Your help texts. Overridden help pages survive every update; returning to the shipped version is
a deliberate step.
- Your documents. Finalised documents are immutable, across versions too.
Going back to the previous version
After a self-update (console or interface) the system keeps the previous code version. There are three equivalent ways to restore it: in the settings under System update → Back to the previous state (with a confirmation), via the API (POST /api/v1/system/update/rollback, permission platform.system.update, progress via /api/v1/system/update/jobs/{jobId}) or on the console with app:update --rollback. All three take the same path, and every rollback is recorded in the audit log with who triggered it, the source and the target version. Only the code is swapped — the database schema stays. Renamed permissions are reverted automatically: before the code swap the permission names are brought back to the old state, afterwards the restored version aligns them with what it knows, rebuilds the search index and has the background workers restart on the restored version. If reverting fails, the rollback aborts before any code is swapped — the installation stays as it was, and the previous version remains available for a second attempt.
Common problems
The update aborts during migrations. Check the message and the database user; run again after fixing.
Old background processes keep running after the update. They are stopped at the end of the update and restart by themselves. If something hangs, restarting the service helps.
The interface shows old content. A reload without cache is usually enough.