Upgrading
vxl daemon upgrade installs a release over SSH, restarts the systemd service, checks readiness and rolls back if the new daemon does not come up.
Before you upgrade
- Read the release notes for the exact version.
- Back up
/etc/voxeltron/voxeltron.tomland the operator token. - Back up
/etc/voxeltron/voxeltrond.envwith the database state. - Stop the daemon before copying its state database if you want a consistent file copy.
- Keep the CLI and daemon on the same minor version.
$ env_file=/etc/voxeltron/voxeltrond.env
$ sudo cp /etc/voxeltron/voxeltron.toml /etc/voxeltron/voxeltron.toml.bak
$ sudo cp "$env_file" "$env_file.bak"
$ sudo systemctl stop voxeltrond
$ sudo cp /var/lib/voxeltron/voxeltron.db /var/lib/voxeltron/voxeltron.db.bak
$ sudo systemctl start voxeltrondThe secrets passphrase is in /etc/voxeltron/voxeltrond.env. Keep the existing file in place across upgrades so stored secrets remain readable.
Upgrade with the installer
Rerun the site installer on the host with the exact release selected byVOXELTRON_VERSION. Download and read it first:
$ curl -fsSLo install.sh https://voxeltron.dev/install.sh
$ less install.sh
$ sudo env VOXELTRON_VERSION=0.1.3 sh ./install.shFor an optional local mirror, set VOXELTRON_RELEASE_BASE_URL to the base URL holding the signed release files. Signature verification still uses the installer's embedded key. See Installation.
Upgrade over SSH
$ vxl daemon upgrade \
--server prod \
--release-version v0.1.3 \
--verify-config \
--verify-runtime-compatUse --host user@host[:port] instead of --server for a one-off upgrade without a saved profile. --ssh-key selects the key.
--verify-config validates the active configuration with the replacement daemon before restarting. --verify-runtime-compat checks that installed guest runtime helpers match the new daemon.
For automation, add --json:
$ vxl daemon upgrade --server prod --release-version v0.1.3 --jsonWhat happens during an upgrade
- The CLI uploads the release archive over SSH and verifies it with the pinned key.
- The daemon unit is stopped and the new
voxeltrondis installed. - The service starts and must pass the readiness check.
- If readiness fails, the previous binary is restored and the service is restarted.
App and database containers are not restarted by the upgrade. Only the management daemon restarts, so a deploy in progress at that moment is interrupted. Use a quiet window for production upgrades.
Check the result
$ vxl server inspect prod
$ vxl doctor remote --server prod
$ voxeltrond --versionRoll back
When readiness fails, vxl daemon upgrade rolls back the binary automatically and reports the failure. If the new daemon starts but the configuration or state is wrong, install the previous release explicitly:
$ vxl daemon upgrade --server prod --release-version v0.1.3 --verify-configIf the new version changed the state schema, restore the state database backup before starting the older daemon. An older binary may not understand a newer schema.
Upgrade the CLI
The CLI is a single binary. Replace it with the archive from the same release and verify the checksum first. See installation.
$ vxl --versionCompatibility
| Daemon | CLI | Notes |
|---|---|---|
0.1.x | 0.1.x | Community v0.1. |
A patch difference inside 0.1.x is supported. Upgrade the daemon first, then the CLI.