Upgrading

You don’t need to take a backup first: the installer copies the database before it changes anything, and goes back to the old version by itself if the new one doesn’t start. (Your hourly backups carry on as well.)

The controller

Get the newer vorticpanel-<version>.tar.gz (from Releases, or npm run package), copy it to the server, and run its installer, the same way as installing:

scp vorticpanel-0.2.0.tar.gz root@SERVER_IP:/root/

cd /root && tar -xzf vorticpanel-0.2.0.tar.gz && bash vorticpanel-0.2.0/install.sh

It keeps the address, accounts, servers and settings, and doesn’t ask for an Owner again.

Stopping the old version refuses new changes and waits up to two minutes (PANEL_STOP_WAIT) for running jobs to finish. Jobs still running after that show as interrupted and are never re-run on their own; telemetry corrects server statuses. Servers keep running on their nodes the whole time, and agents reconnect by themselves.

What the installer does on an upgrade

Copies the new version in next to the old one, then stops the panel.
Copies the database to /var/backups/panel/pre-upgrade-<old version>-<time>.db. If that fails (a full disk, say), it starts the old version again and stops without changing anything.
Moves the old version aside, to /opt/panel/dist.old, dist-server.old and dist-agent.old, and puts the new one in its place.
Starts the new version and waits up to a minute for it to answer on http://127.0.0.1:8080/api/v1/status, and to still answer 10 seconds later.
If it doesn’t, it goes back by itself: the old version, the database copy from step 2 and the old settings are put back and started, and it says so. Nothing the new version did is kept. journalctl -u panel --since '-15 min' shows why the new version failed.

Going back by hand

The version you upgraded from stays in /opt/panel/*.old until the next upgrade, and the installer prints these commands with the right file name filled in. To go back to it later (changes made since the upgrade are lost):

systemctl stop panel
cd /opt/panel && for d in dist dist-server dist-agent; do rm -rf $d && mv $d.old $d; done
rm -f /var/lib/panel/panel.db-wal /var/lib/panel/panel.db-shm
runuser -u panel -- install -m 600 /var/backups/panel/pre-upgrade-0.1.0-20261005-140000.db /var/lib/panel/panel.db
systemctl start panel

ls -lt /var/backups/panel/pre-upgrade-* lists the copies; use the newest one, from the version you’re going back to.

The node agents

You don’t need to log in to the nodes. Every upgrade of the controller brings a new agent, and the nodes pick it up on their own, in stages, once the tasks they’re running have finished. Only the agent restarts; the servers on the node keep running. By default:

The node with the fewest servers goes first.
Once it has run the new agent for 5 minutes, the rest follow, up to 3 at a time. A node waiting its turn says so on its Settings tab, with roughly when it updates.
A new agent that can’t reach the controller puts the old one back by itself.
If the first node isn’t back on the new agent within 10 minutes, or its update fails, automatic updates stop for that version and staff get a notification. The other nodes keep their agent; their Settings tab says to update them by hand.

To change how updates go out, open any node, go to Settings → Agent, and under How updates go out (shown while Update agents automatically is on) choose: whether one node tries it first, and for how long (0 to 120 minutes) before the rest follow; how many update at once (1 to 100, or all at once); and how many minutes to wait between one group and the next (0 to 120; 0 starts the next as soon as one finishes). For example, all at once: untick the first node and pick all nodes at once. One a minute: 1 at a time with a wait of 1 minute. It applies to every node, and through the API it’s nodes.agentRollout in the platform settings.

To do it yourself instead, open the node, go to Settings → Agent and press Update agent. Turn off Update agents automatically there if you’d rather choose when each node updates (it applies to every node).

If an update fails, the node’s Settings tab says why, and staff get a notification. Agents installed before automatic updates existed can’t update themselves; for those, run this once on the node, and they keep themselves up to date after that:

curl -fsSL https://panel.example.com/agent/panel-agent.mjs -o /opt/panel-agent/panel-agent.mjs && systemctl restart panel-agent

Restarting the agent doesn’t stop the servers on the node.