Before you update

  1. From the releases page github.com/sleep3r/colloq/releases, download release.json, colloq-deploy.tar.gz and SHA256SUMS for the version you chose. Check the sums with sha256sum -c SHA256SUMS and the manifest with scripts/cluster.sh validate --release release.json.
  2. Make sure the images can be pulled with the registry credentials you use and that there is enough disk space for a backup.
  3. Check the stated data schema compatibility and save an external backup of the current state.
  4. Agree on downtime: the app, the broker and the kernels will be replaced.

Use the tools from the release you chose. The installer doesn't fill in a missing digest and doesn't accept a locally patched tools archive.

Run the update

sudo scripts/cluster.sh update --release next-release.json
sudo scripts/cluster.sh status
sudo scripts/cluster.sh smoke

Update first checks data schema compatibility, then makes a consistent portable backup — the app, the broker and room kernels stop already at this step. Only then does the preflight check that the images actually pull and start as UID 1000. If it fails, writers stay stopped and releases/current.json is not replaced yet: fix the cause and run update again, or go back to the previous release with sudo scripts/cluster.sh start. The backup lands in backups/ next to the release's unpacked tools — move it off the server. Notebooks and files stay; Python variables are lost.

Update keeps /var/lib/colloq/config.env, including the broker's RUNTIME_KERNEL_MEMORY and RUNTIME_KERNEL_MEMORY_MAX. To change them, pass the edited file: sudo scripts/cluster.sh update --release release.json --env-file instance.env — with the same release if only the configuration changes.

After the update, check an old room, a new room, publications, files and code execution. Make sure old classes still use their pinned environment revisions.

When you need a rollback

sudo scripts/cluster.sh rollback --release previous-release.json
sudo scripts/cluster.sh status
sudo scripts/cluster.sh smoke

Rollback also checks compatibility, makes a consistent backup and needs downtime. Going back to an old image doesn't undo an incompatible database migration: in that case you need a suitable backup and the restore procedure.

If the readiness check fails, the desired release stays recorded and the previous one is in releases/previous.json. The operator chooses to roll back explicitly; there is no automatic, unverified schema downgrade.

The k3s version changes separately

A Colloq release requires an exact k3s version. Changing it is an operation of its own: back up the datastore and server token, plan the k3s upgrade, then install a Colloq release compatible with the new exact version. A regular app update doesn't promise a safe cluster upgrade.

Old rooms and images

Keep the registry images that old rooms and backups refer to. Even if an environment is gone from a new release, the catalog keeps the earlier revisions it needs. Registry cleanup must take those references into account.

One VM and local volumes mean maintenance with downtime. This process gives you no HA and no zero-downtime updates.

Local install with pip

Stop the class (colloq stop), make a backup with colloq backup and update the package: pip install --upgrade colloq. The update doesn't touch data in ~/.colloq; on the next colloq start the kernel image is rebuilt if its Dockerfile or package lists changed. To roll back, install the previous version with pip install colloq==<version>; if in doubt, restore the backup with colloq restore --legacy --db <file.db> --files <archive>.