raft / docs
Guides

Upgrade Raft or change an image

You update the controller CLI, host deployment and development image separately. Updating one does not update the others. Review release notes, save your controller inventory, and back up important boxes before host changes. Schedule changes when interruptions are acceptable.

Update the controller

raft --version
raft self-update --check
raft self-update
raft doctor

--check installs nothing and returns 100 if an update exists. self-update uses the npm or uv tool channel that installed the running copy; without an explicit version it never downgrades. For uv release wheels, it checks the release SHA-256 before installation. npm verifies package integrity.

For a chosen version, use raft self-update --version 0.7.1. Source checkouts, editable installs, pip and other layouts are refused. Update a source checkout separately and run uv sync --locked; do not overwrite uncommitted work. If uv's tool directory moved, restore UV_TOOL_DIR to the original directory before retrying. Check command -v raft if your shell finds the wrong installation.

Raft may print a daily stderr notice about available releases but never installs them automatically. Set RAFT_NO_UPDATE_CHECK=1 to disable the notice. CLI updates leave hosts, existing boxes and image pins unchanged.

Redeploy matching host code

If doctor reports an incompatible expiry worker, obtain a separate checkout matching your CLI. This example pins 0.7.1; use the chosen version consistently:

git clone --branch v0.7.1 https://github.com/Microck/raft.git raft-v0.7.1
cd raft-v0.7.1
python3 deploy/deploy.py --location lab
raft doctor --location lab

Repeat for each host. Redeployment reapplies host services and firewall rules, but does not update guest files or import an image. It verifies existing resources rather than repairing arbitrary drift. Do not bypass resource conflicts or pool-size errors; preserve backups and inspect the host.

Disposable creation/fork, prune and setting retention require a compatible worker. Installing a CLI does not satisfy that requirement. For optional own disks, add --disk-pool SIZE to the deployer; an existing pool retains its size, and a conflicting explicit size fails.

Replace the image pin

From the matching checkout, build a native image under an unused alias:

python3 deploy/build-image.py --location lab --alias raft-dev-0-7-1

The build does not change your pin. Copy its final fingerprint into that location's image in ~/.config/raft/incus.json. Use the final development image fingerprint, not an intermediate Debian base fingerprint. Keep the previous pin if you may revert future creation. As an alternative to building, import a checksum-verified native image from the chosen release using its release instructions.

The pin affects only image-based new. Resume, fork, snapshot copies and recovery keep their saved filesystem. To update an existing guest, install updates explicitly or create a box from the selected image and transfer your files. Changing a pin does not roll back guest packages or host deployment.

Check the updated setup

Create a persistent test box using the first-box procedure. Check command readiness, docker info, files after stop/resume and application behavior. Delete only that test box after collecting needed results. For broader tests on isolated hosts, see verification.

On this page