Upgrading & Migration

How to upgrade Voxeltron, roll back if something goes wrong, and migrate from other self-hosted PaaS platforms.

Upgrade Methods

Homebrew (macOS / Linux)

$ brew upgrade voxeltron

Upgrades both the voxeltrond daemon and the voxeltron TUI binary.

Debian / Ubuntu

$ sudo apt update && sudo apt upgrade voxeltron

The APT package includes systemd service definitions. The daemon is automatically restarted after upgrade.

Fedora / RHEL

$ sudo dnf upgrade voxeltron

Docker

$ docker pull voxeltron/voxeltrond:latest
$ docker-compose up -d

Docker Compose recreates only the daemon container. Your application containers are not interrupted.

Manual Binary Replacement

# Stop the daemon
$ sudo systemctl stop voxeltrond

# Replace binaries
$ sudo cp voxeltrond /usr/local/bin/voxeltrond
$ sudo cp voxeltron /usr/local/bin/voxeltron

# Restart
$ sudo systemctl start voxeltrond

Install Script (Re-run)

$ curl -sSL https://get.voxeltron.dev | bash

Re-running the install script detects the existing installation and upgrades in place. Configuration and state are preserved.

Pre-Upgrade Checklist

Back Up the State Database

$ cp <data_dir>/state.db <data_dir>/state.db.bak-$(date +%Y%m%d)

Default <data_dir> is /var/lib/voxeltron (Linux) or ~/Library/Application Support/voxeltron (macOS).

Back Up Configuration

$ sudo cp /etc/voxeltron/voxeltron.toml /etc/voxeltron/voxeltron.toml.bak

Check Release Notes

Read the release notes for your target version. Look for breaking changes, deprecated features, and state migration notes.

Verify Binary Checksums

$ sha256sum voxeltrond
# Compare against the checksum listed in the release assets

What Happens During an Upgrade

Rollback Procedure

1. Keep Previous Binaries

Before upgrading, save your current binaries:

$ sudo cp /usr/local/bin/voxeltrond /usr/local/bin/voxeltrond.prev
$ sudo cp /usr/local/bin/voxeltron /usr/local/bin/voxeltron.prev

2. Restore Previous Version

# Stop the daemon
$ sudo systemctl stop voxeltrond

# Replace with previous binaries
$ sudo cp /usr/local/bin/voxeltrond.prev /usr/local/bin/voxeltrond
$ sudo cp /usr/local/bin/voxeltron.prev /usr/local/bin/voxeltron

# Restore state database if migrations were applied
$ cp <data_dir>/state.db.bak-YYYYMMDD <data_dir>/state.db

# Restart
$ sudo systemctl start voxeltrond

Migrating from Other Platforms

From Coolify

1. Export application configurations and environment variables from Coolify's dashboard
2. Re-create projects in Voxeltron:

   $ voxeltron project create --name my-app --source github.com/org/repo
   $ voxeltron env set --project my-app KEY=value

3. Point DNS records to your Voxeltron server's IP address
4. Voxeltron handles TLS automatically — certificates are provisioned via Let's Encrypt on first request

From Dokploy

1. Export application configs and environment variables from Dokploy
2. Re-create projects in Voxeltron using the TUI or gRPC API
3. Migrate Docker Compose files — Voxeltron deploys from Docker images directly
4. Update DNS records to point to your Voxeltron server
5. TLS certificates are provisioned automatically

Version Compatibility Matrix