System update in the settings
Overview
This page does two things worth keeping apart: it checks whether a new version exists, and it runs the update routine. Either can be used independently of the other.
The update routine covers database migrations, the reconciliation of permissions and standard data, the cache rebuild and the rebuild of the interface. It is useful even when the code was updated by other means — through a deployment, for instance.
Core tasks
Check the version. Check now queries the update feed. If none is configured, the page says so explicitly — the update steps can still be run.
Assess an available update. For an update, the version, release date, minimum PHP version and release notes are shown. Four reasons can block an update, and the page names them:
| Notice | Meaning |
|---|---|
| PHP version insufficient | the server has to be raised first |
| Intermediate version required | update to an earlier version first, then continue |
| Plan does not entitle | the licence does not cover this update |
| A run is already in progress | wait |
Run the update. Run update starts the routine after a confirmation. The database backup is optional and recommended — it writes a dump before the update. During the run the application may respond in a limited way for a while; during the code swap it enters maintenance mode.
Follow the run. The status moves through Queued, Running, Succeeded or Failed, and the last lines of output can be inspected. After success you should reload the interface — it may have changed.
Read the notes from the steps. When a step warns — such as the check of the plugin setup with a note on Sendcloud —, its output appears under Notes from the steps, for every warning step, even if later steps warn as well and even after a successful run.
Fields in detail
| Element | From | What it means |
|---|---|---|
| Current version | the installation | What is running now. |
| Available version | the update source | What exists, with its changes. |
| Changes | changelog of the new release | What changes. Read before installing — this is where it says whether something existing now behaves differently. |
| Action | What it does |
|---|---|
| Check | Queries the update source. Changes nothing. |
| Install | Fetches the new release, secures the current state and switches. Database adjustments run along; the system is briefly unreachable during that. |
| Roll back | Restores the previous state. Time-limited and not possible in every case: what a database adjustment changed cannot always be undone. |
A backup belongs before every install. The update does create a way back, but a way back is not a backup: it restores the program state, not necessarily the data.
Your customisations survive an update: changed help pages, mail templates, roles and settings remain, because the sync only updates what is unchanged.
Settings & permissions
- Permission
platform.system.update. Without it the page is unreachable. - The update steps are repeatable. If a run fails, it can safely be started again once the cause
is fixed — a second run does no additional harm.
- Without an update feed there is no version check, but the routine still works.
- The update channel determines which versions are offered.
FAQ & troubleshooting
No update is found although one has been published. Check whether an update feed is configured and which channel is set.
The run failed. Read the output — it names the step. Restart after fixing the cause; the steps are repeatable.
The interface looks broken after the update. Reload it. Rebuilding the interface is part of the run, but your browser holds the old state.
Should we back up first? Yes. The backup is optional because some organisations run their own backup routines — not because it is dispensable.