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.toml and the operator token.
  • Back up /etc/voxeltron/voxeltrond.env with 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 voxeltrond

The 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.sh

For 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-compat

Use --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 --json

What happens during an upgrade

  1. The CLI uploads the release archive over SSH and verifies it with the pinned key.
  2. The daemon unit is stopped and the new voxeltrond is installed.
  3. The service starts and must pass the readiness check.
  4. 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 --version

Roll 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-config

If 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 --version

Compatibility

DaemonCLINotes
0.1.x0.1.xCommunity v0.1.

A patch difference inside 0.1.x is supported. Upgrade the daemon first, then the CLI.