Skip to content

Updates

Vesana updates itself through the admin UI (Admin → System → Updates). A background updater service runs the update: space check, backup, pull, migration, restart. 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

Before every update the GUI updater checks free space, automatically creates a backup and checks your own override file before it stops anything. Manual updates bypass these safeguards.

Update types and version numbers

Vesana versions follow the scheme 1.<line>.<patch>, e.g. 1.902.0, 1.902.1:

  • A new second digit is a feature update: new functionality, bundled and tested beforehand.
  • A new third digit is a patch: a security update or a quick bugfix on the installed version. A patch changes no behaviour and carries no database change.

A new line (1.<line>.0) first goes only to instances with a tester license and is released to everyone afterwards — as the same version, not rebuilt. A normal instance therefore only sees released versions and their patches; tester lines that came between two releases are skipped in one step. A patch appears on the released line and, if different, on the newest tester line. On the updates page a patch is labeled "Security update / bug fix", a release marked as critical "Critical"; when a critical update is available, every page shows super admins a red notice at the top.

With a license key the updates page only offers versions released up to the end of the update period; a newer one is listed as "Requires renewal" and is never installed automatically either. Patches of a covered line always arrive.

Fresh installs (setup.sh, the :latest Docker tag) always get the currently released version.

Online update (manual)

Requirements: outbound access to the licence portal (update check) and the container registry (image pull), plus about 4 GB of free space. If less is free, the updates page says so before you start — with the free and required space and a hint to enlarge the disk of the VM or container.

  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. Space check — around 4 GB free is required, because the image pull loads the new images alongside the old ones. If there is not enough, the updater first removes old Vesana images and checks again; only if it is still short does the update abort, before anything was changed
  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). If no backup can be created, the update aborts — no backup, no update
  3. For online updates: the current compose file is fetched from the licence portal (the old version is kept as a backup). If your own docker-compose.override.yml sits next to it, the updater now checks it against the new compose file. If it doesn't fit, the update is aborted here, before anything is stopped, and the old compose file is restored — see Customising the stack
  4. 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
  5. New images are pulled
  6. Migrations run via the init container
  7. The version in the configuration is updated, the stack restarts

If an update fails, the updates page names the reason (e.g. not enough free space, licence portal unreachable, migration aborted); the update history shows it in a separate line. If a migration aborts, the message says how many migrations were already applied, that the instance keeps running on the previous version, and that the update can be retried.

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: checking → backup → download → migrations → restart → completed (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.

Automatic security updates and bugfixes only

If automatic updates are turned off entirely, the card shows its own switch, "Install security updates automatically". It installs only patches of the currently installed version (e.g. 1.902.0 → 1.902.1) — a feature update (new second digit) stays manual. A patch is installed without a waiting period; below the switch you choose the installation window (Anytime · Nightly · Custom window) it is applied in. If someone is working in Vesana, the notice dialog with a countdown comes first.

On a fresh install this switch is on; existing installations keep their prior behavior (off) until you turn it on yourself.

Turning it off only works after a warning in the card; while it is off, the card says "Security updates are turned off".

With a tester license you decide as well: automatic updates, waiting period, window and declining work as on any other instance.

Switching a tester instance to Stable

With a tester license the card shows the row "Update channel: Tester" and the button "Switch to Stable". Afterwards the instance only receives released versions and their patches, no more tester versions. The switch only goes one way: the Vesana team switches it back to the tester channel.

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. With "Install critical updates immediately", a release marked as critical does not wait for the minimum spacing either.
  • "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

These rights apply to the whole instance: they only count when the role is assigned for "all tenants" (or as Super Admin) — a right held in a single tenant is not enough.

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

Notification on a new version

Under Admin → System → Updates → "Notify on new version" you choose one or more notification channels (email, push, Teams, … — created under Alerting → Channels). Every new version that becomes available for this instance is announced there exactly once — with the key points of the release notes and a link to the update page. Your instance's update channel decides: an instance with a tester licence hears about tester versions, every other instance about released versions; a security or bugfix patch is announced too.

When you switch it on, Vesana remembers the current state — only what appears afterwards is announced. If feedback that someone follows on this channel is resolved by the new version, it is listed in the same message (see Feedback button).

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 like an online update: verify the package checksums, space check, pre-update backup, load the images from the package, take over the compose file from the package (including the check of your own override file), migrations, restart via the helper container. Applying it is recorded in the audit log (update_apply_offline, on failure update_apply_offline_failed).

Version history

Two separate views under Admin → System → Updates:

  • Version history — the available releases with release notes (only versions that have notes; the last five visible, "Show older versions" for the rest). The important part is on top, all further changes can be expanded
  • 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. If you have your own docker-compose.override.yml, add -f docker-compose.override.yml to every docker compose command below (or set COMPOSE_FILE in the .env, see Customising the stack) — otherwise your additions are missing after the restart.

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.

Profile updates from the Vesana library

Installed profiles from the Vesana library that were not changed locally are updated by Vesana every hour in the background. The switch "Update profiles automatically" on this page (super admin only) turns this off; default: on. Every automatic profile update is written to the diagnose log. Locally modified profiles are never overwritten silently; they show "Update available". After the update period of the license has ended, no profile updates are applied.

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, replace their own binary, and restart the service. Only a binary signed by the vendor is installed, and never a version older than the running one — even a compromised Vesana server cannot slip in a foreign binary. This check cannot be switched off.

Next