A panel installed by the VMStack installer updates itself: from the panel with Update now, automatically in a window you choose, or from the shell with vmstack-panel update. Every update dumps the database first, and is rolled back by itself if the panel does not come up healthy.
The version#
The panel's version is shown to administrators at the bottom of the sidebar and on System › Settings › Updates. The Updates page also shows the channel, the oldest agent the panel works with (Works with agents) and how the panel is updated.
Finding releases#
The panel reads the newest release of its channel every 6 hours, checks its signature against the VMStack release key built into the panel, and keeps what it found. Check now on the Updates page reads it at once.
The check sends nothing that identifies your panel: two plain HTTPS requests (the release manifest and its signature), with no version, no cookies and a fixed user agent. To turn checks off, for example on a panel without internet access, set VMSTACK_UPDATE_CHECK=false in /opt/vmstack/shared/.env. The Updates page then says "Update checks are off" and how to turn them on again.
When a release is available:
- administrators see Update available: and the version in the sidebar;
- a security release also puts a Security update banner on every administrator page until the panel is updated. Remind me tomorrow hides it for 24 hours for you; a newer security release brings it back at once.
A release that VMStack withdraws is never offered. If your panel runs a withdrawn version, the Updates page says so.
Channels#
| Channel | What it gets |
|---|---|
stable |
Releases for production panels. The default. |
beta |
Releases before they reach stable. For test panels. |
Change it under Automatic updates › Channel on the Updates page; the new channel is checked at once. From the shell, vmstack-panel update --channel beta changes it too.
Update now#
- Go to System › Settings › Updates.
- Read Newest release: its version, whether it is a security release, its date, the agents it needs and its release notes.
- Click Update now (it reads "Update to" and the version), and confirm.
The page then shows the update's steps as they run, and you keep the page while the panel is in maintenance. Other users see a maintenance page for a few seconds. An update takes one to three minutes.
When it is done, the page shows the result: updated, rolled back with the reason, not updated (nothing was changed) or postponed. Administrators also get an e-mail (alert group "Panel updates: installed, rolled back or failed").
If the page shows "The updater has not started in 2 minutes", the service that carries out the request is not running; see Troubleshooting the panel and licensing. Take the request back cancels it.
Update now is available only on panels installed by the installer. A panel run from a git checkout says "Updated with git".
What an update does#
- Download and check: the release manifest's signature, the archive's size and SHA-256, and the archive's paths.
- Prepare: unpack the release beside the one in use, and check it can run here (PHP version and extensions, database, cache, free disk, and that no node's agent is older than the release needs).
- Wait for a quiet moment: pause the queues and wait until no job runs. If jobs still run after 15 minutes, the update is postponed, the queues are resumed and nothing changes.
- Back up: dump the database into
/opt/vmstack/shared/backups/pre-<version>.sql.gz(the last 3 are kept). If the dump fails, nothing changes. - Switch: maintenance mode, the new release's migrations, switch to the new code, write its configuration (
vmstack-panel repairfrom the new release), restart the workers, scheduler and relay, reload PHP-FPM, resume the queues, end maintenance. - Health check for up to 2 minutes:
/upanswers, every unit runs, a worker takes a job on every queue, the scheduler beats, and the dashboard renders for an administrator. - Done: the oldest releases are removed (the last 3 are kept, never the one in use or the one before).
If any step from the switch on fails, the update is rolled back: the previous release is put back with its configuration, the workers are restarted and maintenance ends. The version is marked as failed here, and the Updates page shows the reason and the dump taken before.
Note: A rollback puts the previous code back but never restores the database. Migrations only add to the database, so the previous release runs on it. In the rare case that is not enough, the rollback message lists the commands to restore the dump by hand.
An update killed halfway, or cut by a reboot, is rolled back at the next start of the server (vmstack-panel-update-recover.service) or by the next update run.
Automatic updates#
Off by default. To turn them on:
- On System › Settings › Updates, under Automatic updates, tick Install updates automatically.
- Choose the Window: a Day (or every day), From and To, in the panel's time zone. It may run past midnight and must last at least 15 minutes.
- Choose Which releases:
- Only when a security release is out (the default): when a security release is pending, the channel's newest release is installed (it carries the fix and may carry other changes). Normal releases wait for Update now.
- Every release of the channel.
- Choose the Channel and click Save settings.
A timer looks every 10 minutes whether an update is due. While the window is open, it also reads the channel itself, so a release is installed within about 10 minutes of being published. A version that failed here is not tried again automatically; Update now tries it again. An update outside the window never runs, even for a security release.
From the shell#
On the panel server, as root:
vmstack-panel update --check
vmstack-panel update
| Option | What it does |
|---|---|
--check |
Only says what would be installed |
--version X |
Goes on only if X is what the channel offers now. It cannot install an older release. |
--channel stable|beta |
Changes the channel, then updates from it |
The log is /var/log/vmstack-panel-update.log. Only one update runs at a time.
Panels installed before the updater#
A panel installed by an early installer has a vmstack-panel update that says it is not available. Update it once with the newest installer's own updater; after that, vmstack-panel update works:
curl -fsSL https://vmstack.eu/install.sh | bash -s -- --update
History#
History on the Updates page lists every update and rollback made by the updater, with the versions and why a rollback happened. They are also in the audit log (panel.updated, panel.update_rolled_back, panel.update_failed).