Upgrading

Migrations are compiled into the binary and run at startup. They only move forward: once a newer version has opened the database, an older one may refuse to start or misread the schema, and nothing migrates back down.

So the order matters, and it is the same on every install:

1. Back up data/.
2. Upgrade.
3. Check it came up.

Skipping step 1 is the only way to lose a stack history, and it is the step people skip.

1. Back up

sqlite3 data/kaio.db ".backup '/backups/kaio.db'"
tar czf /backups/kaio-$(date +%F).tar.gz data/

Copying kaio.db alone while the server runs is not a backup: recent writes sit in the -wal file until a checkpoint. Backup and restore explains what that directory holds and why the three files travel together.

2. Upgrade

The image

docker compose pull
docker compose up -d

Pin a version rather than latest if you want to choose when this happens.

The release tarball

Unpack the new archive and run its installer again:

sudo ./install.sh

It keeps /etc/kaio.env, replaces the binaries and the web assets, and restarts the service only if it was already running. See Installation for the layout it writes.

3. Check it came up

kaio-cli health
kaio-cli stack ls

health reports the version now answering, so it is the quickest confirmation that the new binary is the one serving. stack ls confirms the migration found your stacks.

In a cluster, upgrade the control plane last and check the registry afterwards: a node running an older version still answers, and its reported version is visible in kaio-cli node ls.

Your stacks are not part of the upgrade

The containers Kaio deployed are ordinary Compose projects owned by the Docker daemon, not by Kaio. Stopping, replacing and restarting Kaio leaves them running, and an upgrade never recreates them on its own. What a stack loses during the restart is the live view: metrics, the event stream, and any open log or shell session.

Going back

There is no downgrade path for an applied migration, so returning to a previous version means restoring the state it knew:

1. Stop the service, or docker compose down.
2. Put back the previous image tag or the previous binaries.
3. Restore the data/ backup taken before the upgrade.
4. Start it again.

A backup taken after the upgrade carries the newer schema and will not help. That is the whole reason step 1 comes first.

Related

• Backup and restore
• Data retention, for what a restored backup is expected to have lost
• Deploy with Compose
• Installation