Platform Updates

TrixOS releases follow semantic versioning. Every release is listed with its changes in the changelog. The running version is shown at the bottom of the sidebar and under Settings.

Database migrations run automatically when the API starts (MIGRATE_ON_START=true), and jobs that are running during the update continue at the step where they stopped. You don’t need a maintenance window, but avoid updating while an OS install is copying files.

Update the panel

One click (since 0.8.0)

When a newer release is out, admins see Update to X.Y.Z under the version at the bottom of the sidebar. It opens the release’s changes; Update now does the rest:

1. TrixOS checks that the release is signed with the TrixOS release key (built into TrixOS; a release from anywhere else, a changed package or an older version is refused).
2. The updater on the host checks the signature again with its own copy of the key, backs up the database, installs the release, rebuilds the containers and waits until the new version answers.
3. If the new version does not come up, it puts the previous version back, starts it again and tells you, with the location of the database backup.

The panel is unavailable for a few minutes meanwhile; the window shows the steps and the log, then Reload.

The updater is a small script on the host (/usr/local/sbin/trixos-update, started by systemd when the panel asks for an update): the containers themselves get no access to Docker or the host. The installer sets it up. On an installation from source, or one older than 0.8.0, set it up once:

cd /opt/trixos
sudo bash deploy/updater/install-updater.sh --dir /opt/trixos
docker compose up -d

Check it with systemctl status trixos-update.path; each update’s log is in /opt/trixos/update/state/update.log and journalctl -u trixos-update.

Installed with the script

Run the install script again on the panel host:

curl -fsSL https://trixos.sh/install | bash

This also works without the updater. It downloads the newest release package, checks its SHA-256, replaces the release files in /opt/trixos (or your --dir), keeps .env, isos and all data, rebuilds the containers and waits until the API answers. To install a specific release, add -s -- --version X.Y.Z.

Take a database backup first (see below or Backups & Restore). Compare your .env with the new .env.example for settings that were added.

From source

1. Back up the database.

   cd /opt/trixos
   docker compose exec -T postgres pg_dump -U trixos -d trixos -Fc > /var/backups/trixos/before-update.dump

2. Pull the new release and rebuild:

   git pull --ff-only
   docker compose up -d --build
   docker compose --profile tools build kvm-viewer

Check the result

docker compose ps
docker compose logs --since 10m api | grep -i -E "error|migrat"
docker compose exec api trixos license status

Open the panel and check the version at the bottom of the sidebar.

If something goes wrong

Install the previous release again (--version with the script, git checkout <previous tag> from source), restore the backup and restart:

docker compose exec -T postgres pg_restore -U trixos -d trixos --clean --if-exists < /var/backups/trixos/before-update.dump
docker compose up -d --build

Update the site agents

Each release of the panel contains the matching agent version. When an agent is older, System → Agents shows Update agent next to it. The agent downloads the new version from the panel, checks its SHA-256 checksum and restarts itself within a minute.

The Dashboard lists every agent with its version and marks the ones with an update available (see System health). Agents older than 1.3.0 show no CPU, memory and disk usage until they are updated.

Reinstall on the same page gives you the full installer command again. Use it when a release notes that the agent needs new packages or firewall rules; it keeps the agent’s registration and WireGuard tunnel.

Base images

The panel’s containers are built on official node, postgres, redis and nginx images. Rebuild regularly to pick up their security updates:

docker compose pull postgres redis
docker compose build --pull
docker compose up -d