Upgrades and rollback
Weik.io 2026.2upgrade.sh backs up the hub and moves it to a new release. upgrade.sh --rollback returns it to the release before and keeps every record stored since. Product page · Video
Watch: Backups, restore and upgrades, 3:28
The video makes a backup and restores one document and then the whole hub from it. It also goes through the upgrade steps.
This part of the video couldn't be loaded.
On this page
Every image in the stack is pinned by tag and digest, so your Weik.io installation changes only when you upgrade it. Each release publishes an images.env with one line per image. upgrade.sh in the stack folder moves the stack to that release. The integrations on your agents keep running while the hub upgrades.
A release only adds to what Weik.io saves and sends, and removes or renames none of it. An installation upgrades in place and keeps the records it has stored.
To pull the images from a registry of your own that keeps the upstream paths, set WEIKIO_REGISTRY on its line near the top of .env, above the image lines.
Upgrade a hub on one server#
Give upgrade.sh the release’s images.env by its path or its https:// address:
$ sudo sh ./upgrade.sh https://weik.io/downloads/releases/2026.2.4/images.env- The script backs up the installation into
backups/upgrade-<release>-<time in UTC>, named after the release the stack runs. - It pulls the new release’s backend image and runs its
weikio-backend upgrade. - It pulls the release’s images and brings the stack up on them.
- It waits up to three minutes each for the message server and the backend to respond, and ends with
doctor.
In step 2, weikio-backend upgrade writes the platform’s files in the stack folder again from your choices in weikio-install.json and puts the release’s image lines into .env. Every other line of .env and every file of yours stays as it is. Each file the command replaces is kept in .upgrade/<release>/.
The API is unavailable from when the backend container is recreated until it answers again. The script’s last line shows that time in seconds.
If a run stops part way, run it again from the start. A run to the release the stack already runs changes no file and exits 0.
Afterwards, docker compose logs init shows a line upgrade step <id> applied: <sentence> for each step the release applied. weikio audit query --action UpgradeStepApplied lists the same steps from the audit trail.
See what would change#
$ sudo sh ./upgrade.sh <images.env> --check--check shows what the upgrade would change and writes nothing.
If a platform file was edited by hand, the upgrade stops before the stack changes and prints the file’s name. Move the edit into docker-compose.override.yaml or .env and run the upgrade again, or give --replace-edited <file> to have the release’s copy take its place.
Pasting image lines into .env by hand isn’t an upgrade, because the platform’s files stay as the previous release wrote them.
Roll back#
To go back to the release the last upgrade moved the stack from, run:
$ sudo sh ./upgrade.sh --rollbackThe rollback puts back every file the upgrade kept in .upgrade/<release>/, including .env and weikio-install.json. Then it brings the stack up on that release’s images. It waits for the stack as the upgrade does and ends with doctor.
The rollback keeps the keys directory and every record stored since the upgrade, such as changes to the allowed networks. The previous release uses both as they are.
When you roll back from 2026.2.2 or later to an earlier release, the earlier release’s telemetry stores keep records only as long as its stack sets. A store that was set to keep them longer erases the older records when it starts.
The earlier release also can’t find the client secret of an identity provider saved on 2026.2.2 or later, so sign-in through that provider stops. Sign-in through such a provider works again once you run weikio provider set <provider> --client-secret-ref <project>.<secret> on the earlier release. Keep a local account or a platform-admin API key to run that command with.
Before it puts anything back, the rollback lists what each store would erase, and each such provider with the command for it. It changes nothing until you agree. To roll back anyway, run:
$ sudo sh ./upgrade.sh --rollback --yesIf the upgrade moved the message server to another minor version, the rollback changes nothing and shows the backup the upgrade made, because a message server can’t use storage that a later minor version wrote. Restore that backup as Backups and restore says.
Upgrade a hub on several servers#
A hub on several servers upgrades one server at a time, while the load balancer sends callers and agent links to the others. doctor on any server shows the order:
$ docker compose run --rm infra weikio-backend doctorIts servers row shows on 3 of 3 for three servers while every server responds. Its upgrade order row lists the servers in the order to upgrade them:
- The standard servers
- The data servers that don’t lead the storage
- The data server that leads the storage
Never upgrade two data servers at the same time. Upgrade each server in that order:
-
From the second server on, copy the keys directory of the first server you upgraded onto this one, so it has the key files the release added:
Terminal$ ssh <first server> 'tar -C / -cpf - opt/weikio/keys' | ssh <server> 'tar -C / -xpf -' -
In the server’s node directory,
/opt/weikio/deploy/compose/cluster/node-<n>, run the upgrade:Terminal$ sudo sh ./upgrade.sh <images.env>upgrade.shremoves the server from the load balancer’s pool before any of its services restarts, then brings the stack up. Beforedoctorruns, it waits for the message server and the backend to respond and for two of the balancer’s checks to pass. The server is then back in the pool. -
Go on to the next server only when
upgrade.shended withdoctorexiting 0 and theserversrow lists every server.
To roll back, go through the servers in the same order and run sudo sh ./upgrade.sh --rollback in each node directory.
Upgrade the agents#
After the hub, upgrade each agent with the same release’s images.env. In the folder its setup.sh installed the agent in, run:
$ sudo sh ./setup.sh --upgrade <images.env>setup.sh pulls the images and replaces the agent’s .env with the file. It then waits until the agent is online again. Every agent on a Linux host upgrades this way. A Windows agent upgrades when you run the later release’s installer, as Agents on Windows says.
An agent on an older release keeps working and shows as behind. weikio problems lists it with the release to upgrade to.
Upgrade a standby hub#
Paste the images.env lines of the primary’s release into the standby hub’s .env, so its next refresh writes the stack of that release.