The panel's Update now button and cgctl update start the same update. It installs only releases signed with a key the installed CloudGround carries, takes a snapshot of the panel's state first, and puts the previous release back by itself if the new one is not healthy within 60 seconds.

Check for a new version

When a newer release exists, the dashboard shows CloudGround <version> is available, with the version you are running and a What's new link. The panel checks when you open it and keeps the answer for six hours.

To stop checking, open Settings, card Panel updates, switch off Check for updates when the panel is opened and press Save. The check never installs anything by itself.

In the same card, Update channel chooses what you are offered: Stable only final versions, Beta (pre-release versions too) also the pre-release ones.

From the shell, as root on the server:

bash

cgctl update --check

It prints update available: <installed> -> <release> (signature verified), or up to date, and changes nothing.

Update from the panel

1. On the dashboard press Update now. Or, in Settings, card Panel updates, press Update now and confirm.
2. The panel says Update started: the panel will restart.

With the API the request is POST /api/panel/update, with {"version": "<version>"} or {} for the newest.

Update with cgctl

On the server, as root:

bash

cgctl update

This installs the newest release of the channel the panel follows. The variations:

Command	What it installs
cgctl update	the newest release of the panel's channel
cgctl update --to <vX.Y.Z>	that release, never an older one
cgctl update --channel beta	the newest release of that channel (stable or beta), this once
cgctl update --timeout <duration>	the same, waiting that long for the verdict (default 10m)

cgctl update waits for the restart and prints updated: <previous> -> <release> and the snapshot it took, exit 0. If the release was rolled back it prints rolled back: <previous> runs again, with its state from <snapshot>, exit 1.

What an update does

1. It checks the release before changing anything: the signed manifest verifies with a key compiled into the installed CloudGround, the channel takes it (a beta never on stable), and it is newer than the running release and than any release ever installed on this server.
2. It downloads every file and checks it against the manifest, then swaps the binaries, keeping the old ones.
3. A guard process, running the previous release, stops the panel, takes a snapshot of the panel's state and the agent's records, and starts the new release.
4. If the agent and the panel answer on the new binaries within 60 seconds, the update is done. Otherwise the guard puts back the previous binaries, units and the snapshot, and starts the previous release again.

The new panel migrates its database forward at its first start, through every step between the two releases: you can go from one release to any newer one in a single update. The migration never runs backwards, so the way back is the snapshot, which a failed update restores by itself.

What it keeps

An update replaces the binaries and, when the release changes them, the systemd units. It never touches the sites' files, their databases, certificates or backups. The sites keep serving throughout: nginx and the sites' PHP are not restarted. Only the panel answers with an error for the few seconds of its restart.

It refuses, and changes nothing:

• a release that is not signed with a key the installed CloudGround carries;
• a release that is not newer than the running one or than the newest ever installed here (refusing to downgrade);
• an update while a backup, a restore or a task that cannot resume is running: wait until it has finished.

Check how it went

bash

cat /var/lib/cloudground-agent/update-result.json
journalctl -u cloudground-update-guard

The file says which version you moved to, or that the update was rolled back and why. The journal shows every step of the guard. The newest three snapshots stay in /var/lib/cloudground-agent/update-snapshots/.

NoteThe installer is not an update

Running a newer release's install.sh on an installed server is refused: it names cgctl update --to <release>, because the installer has no snapshot and no rollback. The installer of the release already installed repairs the server (see what the installer does).

Next step

To take CloudGround off a server, see uninstall CloudGround.