Skip to content

Updates

Vesana updates itself through the admin UI (Admin → System → Updates). A background updater service runs the update: backup, pull, migration, restart, health check. Either you trigger the update yourself, or you let Vesana handle it via automatic updates.

Never run docker compose pull manually on a production instance

The GUI updater automatically creates a backup before every update and checks disk space and health before actually switching over. Manual updates bypass these safeguards.

No channel concept

There are no beta/stable/nightly channels. There's always exactly one "latest version" from the licence portal — Vesana shows you "Current version" and "Available version" side by side. If an update is critical (security fix, urgent bug fix), a red "Critical" badge marks it accordingly.

Online update (manual)

Requirements: outbound access to the licence portal (update check) and the container registry (image pull).

  1. Open Admin → System → Updates (an automatic check already runs on opening; "Check for updates" forces a fresh one)
  2. Review the available version + changelog
  3. Click "Update now"

What happens in the background

  1. Disk-space check — around 4 GB free is required, because the image pull loads the new images alongside the old ones before cleanup happens
  2. Pre-update backup — always a configuration backup (not a full dump; lands in the same backup catalog as scheduled/manual backups, see Backup & Disaster Recovery)
  3. Old Vesana images are cleaned up — only images with exactly the Vesana name and a version tag; unrelated images on the same server whose name happens to contain "vesana" are left alone
  4. For online updates: the current compose file is fetched from the licence portal (the old version is kept as a backup)
  5. New images are pulled
  6. Migrations run via the init container
  7. The version in the configuration is updated, the stack restarts

The service restart runs in its own helper container that survives the recreation of the containers — even if the updater itself is recreated in the process, the instance is not left behind with "502 Bad Gateway".

Progress display

The UI shows the update run as a progress bar with clear stages: idle → checking → downloading → backing_up → migrating → restarting → health_check → done (or failed).

The bar actually measures: the download in bytes (e.g. "Image 3/7 · 812 MB / 2.1 GB"), migrations as a counter, the backup by file size. If a measurement fails, the update continues unchanged and shows coarse stages instead of aborting.

During the restart phase, the UI is briefly unreachable. An overlay bridges this gap: it specifically polls until the new version actually responds (not just any response) — so no premature success appears while the old version is still running in the background. Until then you see a "Vesana is starting …" splash. Afterwards the UI waits until the API is fully back — you stay logged in with your permissions, no logout/login needed.

Sessions survive updates

A Vesana update — manual or automatic — logs nobody out: the announced restart carries the running sessions over. Only real restarts stay strict: a server reboot, a manual restart of the stack or a crash still require a fresh login.

Automatic updates

Vesana can update itself. The switch sits directly on the Updates page in the "Automatic updates" card; the settings below it are saved as soon as you change them.

Setting Options Meaning
Waiting period after release Immediately · 24 hours · 3 days (default) · 1 week · 2 weeks · Custom (1 hour to 90 days) New versions mature first. What gets installed is always the newest version that is at least that old — if a fix appears during the waiting period, the fixed version is installed directly; a broken release passes the instance by.
Install critical updates immediately on (default) / off Releases marked as critical (e.g. security fixes) skip the waiting period.
Installation window Any time · At night (01–06 h) · Custom window (from–to) A due update waits for the next window. The time zone is shown; Vesana is briefly unavailable during installation.

What else the automation takes into account:

  • Release trains: If one day brings several releases, there is a single update to the last version of the train. A release that was replaced by a successor within a few hours is never installed.
  • Minimum spacing: At least the configured waiting period lies between two automatic updates — no daily update rattle.
  • "Immediately" means immediately: With the waiting period set to "Immediately", Vesana notices a new release within about two minutes; with a waiting period it checks less often, since hours to days pass anyway.
  • Failure: If an automatic attempt fails, Vesana retries the same target version no earlier than 6 hours later. If it failed before touching anything (licence portal briefly unreachable, not enough space), a 15-minute pause is enough. A short DNS/network hiccup no longer fails a running update: the check against the portal is retried and falls back to the last known release data if needed.
  • Traceable: Automatic updates carry the "Auto" marker in the update history and appear in the diagnostics log.

The card always says what happens next — "All up to date", "v… matures for another 2 days", "installation in the next window (…)" or "v… was declined". A running automatic update is visible everywhere, on other pages and in the admin area too.

Announcement with countdown

If an update is due and someone is currently working in Vesana, a notice dialog "Automatic update" appears first with a five-minute countdown; it names the fixed installation time and when it was announced. The countdown follows the server's clock, not the browser's, and appears in a background tab too. If nobody is working, the update starts without an announcement.

The dialog offers — depending on permissions — three options:

Action Effect Permission
Defer (+15 min · +1 h · +4 h) Pushes the time back, at most 24 hours in total from the original time updates.defer — Operator, Admin, Super Admin
Decline this update Exactly this target version is never installed automatically (manual only); a newer release is treated normally again updates.decline — Admin, Super Admin
Install now Starts the update immediately without waiting out the countdown updates.install_now — Admin, Super Admin

If the announced update fails, the notice says so in plain text and offers "Try again".

No automatic rollback

There is no automatic rollback mechanism. If an update fails, the stack stays in whatever state the failure occurred in — the recovery strategy is the pre-update backup, which the updater automatically created before the run:

  1. Open Admin → System → Backup & DR
  2. Look for the most recent "Pre-Update" backup
  3. Trigger a restore (type the hostname + identity confirmation, see Backup & Disaster Recovery)

That brings the database back to the state right before the update — the configuration, not the metrics history, because the pre-update backup is a configuration backup. The compose-file backup the updater creates before online updates additionally helps if you also need to roll back the compose configuration.

Offline update

For air-gapped environments, or when the server has no direct access to the container registry.

Get the package

On a machine with internet: licence portal → Releases → Offline package. File: vesana-update-vX.Y.Z.tar.gz. Contents: Docker image tarballs, compose file, manifest, migrations.

Load the package

In the admin UI: Admin → System → Updates → "Upload offline update" → select the file. The upload is streamed straight to the updater without an intermediate copy on the server; packages up to 8 GB are possible (since v1.9.437 — before that the upload failed above 50 MB with "413 Request Entity Too Large"). If your own reverse proxy sits in front of Vesana, its upload limit applies additionally.

The updater treats the offline package exactly like an online update — disk check, pre-update backup, migrations, restart via the helper container. Additionally, a health check with a timeout (about 90 seconds) runs afterwards, since the offline path has no direct access to external reachability checks.

Version history

Two separate views under Admin → System → Updates:

  • Version history — all available releases with changelog (the last five visible, "Show older versions" for the rest)
  • Update history — the updates actually performed on this instance: target version, starting version, Online/Offline, Successful/Failed, timestamp, "Auto" marker for automatic updates. Failed attempts also name the target version.

The updater only touches its own instance

The updater identifies its compose project via its own container. If two Vesana instances run on one host, each only updates itself. If the installation is not under /opt/vesana (installer variable VESANA_DIR), the installer writes the directory into .env as COMPOSE_PROJECT_DIR — exactly that installation is then updated.

Reverse proxy in front of Vesana

The maintenance component that applies updates is not reachable from outside (since v1.9.437 — before that it could be addressed under /updater/… without login). All UI functions run through the authenticated API; from outside exactly one read-only query stays open, the progress status during a running update (/updater/update/status), so the bar keeps going while the instance restarts. If your own reverse proxy forwards everything to the Vesana web server, there is nothing to do. If you built your own per-path rules, only this status path needs to be let through.

Manual emergency path

Only when the GUI is unreachable and the updater service also doesn't respond:

cd /opt/vesana

# 1. Backup (in addition to the built-in pre-update backup)
docker compose -f docker-compose.prod.yml exec postgres \
  pg_dump -U vesana vesana | gzip > backup_$(date +%Y%m%d-%H%M%S).sql.gz

# 2. Update the compose file from the portal (only if intended)
sudo curl -sSL https://license.vesana.org/api/v1/install/compose -o docker-compose.prod.yml.new
diff docker-compose.prod.yml docker-compose.prod.yml.new
mv docker-compose.prod.yml.new docker-compose.prod.yml

# 3. Pull new images
docker compose -f docker-compose.prod.yml pull

# 4. Init container for migrations
docker compose -f docker-compose.prod.yml run --rm init

# 5. Restart the stack
docker compose -f docker-compose.prod.yml up -d

For an offline update, add this before step 3:

tar xzf vesana-update-vX.Y.Z.tar.gz -C /tmp/vesana-update
for img in /tmp/vesana-update/images/*.tar; do docker load < "$img"; done

After such a manual restart a fresh login is required — only announced restarts from the updater carry sessions over.

Agent and collector updates

Agents and collectors update themselves automatically on their next config refresh (a few minutes by default). They pull the current version from the server, verify the signature, replace their own binary, and restart the service.

Next