Updating VirtConsole

VirtConsole has two separately versioned components: the panel on the management server, and the agent on each hypervisor. Both come from the official update channel as signed packages. You can update from the admin panel with a live log, or from the command line with the vcli wrapper, which runs panel commands as the correct system user.

Every package is checked twice before it is applied: a checksum, then an Ed25519 release signature. A package with a missing or invalid signature is refused. Nothing is applied until both checks pass.

Update the management server from the panel

When a newer panel version exists, an amber Master update available banner appears above every admin page with the current and the new version. The banner can be dismissed for the browser session; it comes back on the next login until you update.

Click View on the banner. The update dialog opens and shows Local (installed) and Remote (available) versions.
Click Start update. The panel starts the update as a detached process and streams its log into the dialog line by line.
Wait for the final “completed” line. Services restart within a minute after it, from a cron job that runs outside the web process, so the panel may be unreachable for a few seconds at the end.
Reload the page. The version in the footer shows the new release.

If you close the dialog or refresh the page mid-update, open it again from the banner: it reloads the last 200 log lines and keeps following. The full log is kept at storage/logs/master-update.log on the management server.

Only one update can run at a time. A lock prevents a second start while one is in flight; it expires on its own after 10 minutes if the process dies, or you can click Clear stuck lock in the dialog.

Update the management server from the command line

SSH into the management server and run:

vcli app:update

The command does, in this order:

Asks the update channel for the latest version and stops if you already run it (--force re-applies the current version).
Downloads the package, verifies the checksum and the release signature.
Creates a backup: the database dump, .env and the application files, zipped under storage/app/update-backups/ as backup_<date>_<time>_<id>.zip (directory mode 0700, files 0600; the newest three are kept). Before anything changes, a preflight aborts the update and names any path the updater cannot read or write; The updater also repairs file ownership at the end of every run.
Applies the package (a full package replaces the application directory, a patch package overlays changed files; storage/ and .env are kept either way).
Runs database migrations and, when the release asks for it, the seeders.
Rebuilds caches, re-renders the service configuration and restarts the workers. A panel update also tests the web server configuration and reloads nginx gracefully at the end, so new web server settings apply with no manual step. If the test fails, nginx keeps serving the previous configuration and the reason is written to the application log. After a manual vcli app:update, reload nginx to apply new web server settings.

If any step after the backup fails, including a failed full update, the command restores the backup it just made and exits non-zero. Re-running the command is safe: it starts again from the version check.

Update the hypervisors from the panel

Go to Infrastructure > Hypervisors and open the host.
When the agent on that host is older than the current release, the page header shows the agent version with an Update Agent button. Click it.
The agent’s update log streams into a terminal window on the page. The host stays online; running instances are not touched.

Repeat per host. Update all hypervisors after every management-server update, since a new panel release can carry a matching agent release.

Update the hypervisors from the command line

There are two commands, and which one you use depends on where you are logged in.

On the management server, vcli hypervisor:update drives the same remote update the panel button does:

vcli hypervisor:update

It lists your hypervisors, asks which one to update, and streams that host’s update log to your terminal. It updates one host per run; use --force to re-apply the current version.

On the hypervisor itself, the agent updates with vcli app:update, the same command name the management server uses for its own update:

vcli app:update

It runs the signed download, backup and apply sequence locally, followed by the release’s post-update commands and a restart of the agent workers. Use it when the management server cannot reach the host, or when you are already on the node. vcli hypervisor:update does not exist on a hypervisor; vcli app:update on the management server updates the management server, not the agents.

Common problems

The banner does not appear although a newer version was announced. The availability check is cached for a short time. Wait a few minutes, or run vcli app:update on the server, which asks the channel directly.
The dialog says “A master update is already in progress” but nothing is running. Click Clear stuck lock in the dialog, or wait for the 10 minute lock to expire, then start again.
vcli app:update fails with “Refusing update: release signature missing” or “invalid”. The package on the channel did not pass the signature check. Do not work around it. Try again later and contact support if it persists.
vcli app:update fails part way through. The command restores its own backup and exits. Read the error, fix the cause (disk space and outbound HTTPS to the update channel are the usual ones) and re-run it.
A hypervisor stays on the old version. The management server cannot reach the agent on port 2443, or the agent’s update job is stuck. Check connectivity, look at Tasks in the sidebar for the failed update task, and retry from the host page. Or log in to the hypervisor and run vcli app:update there.