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.
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.