Skip to content

Versioning

Scheme

Since v1.900.0, versions follow the scheme 1.<line>.<patch>, e.g. 1.903.0, 1.903.1:

  • New line (second digit, 1.<line>.0) = feature update: new functionality, bundled.
  • Patch (third digit) = security update or quick bugfix on an existing line. A patch changes no behaviour and brings no database migration and no changed compose file.

Before that, Vesana ran on the 1.9.<n> series (up to v1.9.453), where every change was its own release. A jump to 2.0 is a deliberate, announced decision, never an automatic side effect.

Versions carry a v in tags (v1.903.0); the UI and API responses show the bare value.

Tester line and release for everyone

A new line first goes only to instances with a tester license. Tester instances install it like any update — automatically if automatic updates are on. Once it has proven itself, the same version is released to everyone — nothing is rebuilt. Fresh installs (:latest) always get the currently released version.

A normal instance only sees released versions and their patches. If several tester lines lie between two releases, it skips over them in one update; the release notes of the release describe the whole jump.

What an update brings

  • Container images for all services; the updater swaps them in one go and takes a backup automatically beforehand.
  • Database migrations run by the init container at start — always additive: new tables, new columns with defaults, new indexes, new bundled data. Nothing is renamed or dropped; columns that became obsolete stay.
  • Agents and collectors update themselves afterwards (minutes), as does the Active Collector.
  • Vesana library profiles do not come with the Vesana update but from the library: profiles not changed locally update automatically, a super admin applies updates to locally modified ones via the preview.

Skipping several versions at once is supported; migrations run in order.

Rollback

There is no downgrade: older images do not know the newer tables, and the database is never migrated backwards. The way back is the backup: the updater takes one automatically before every update; a restore recreates the database fresh from the backup (Backup & restore). Everything since the backup is lost in the process — so: verify the backup, then update.

If you prefer to let releases mature, use the waiting time after release of the automatic updates — the newest version that survived the waiting time is installed; a release replaced right away passes the instance by.

Breaking changes — policy

A change counts as breaking if existing API clients with identical code get errors, existing agents/collectors stop working, or existing configurations become invalid without migration. Such changes are marked explicitly in the release notes with ⚠️ and the required action (e.g. "viewers can no longer acknowledge — adjust the role"). Not breaking: new optional fields, new endpoints, more detail in error responses, new UI paths, new permissions (the built-in roles receive them automatically at startup).

Removed features (email 2FA, native app, log rules) are announced in the release; their database columns stay additively.

API versioning

/api/v1/ is stable. New fields are added, existing ones do not change their meaning. The live schema of the running instance is the authoritative reference (API reference).

Agent and collector versions

Agent and collector have their own version numbers and update from the server; they only install binaries signed by the vendor and never an older version. A server update may bring a new agent version; features that need a new agent (e.g. hardware telemetry, Docker tab) appear once the agent has caught up. Old agents keep working until they are updated.

Hotfixes

A hotfix is a patch: it appears on the released line (and, if different, on the newest tester line) and so reaches all instances on that line right away. With the switch "Install security updates automatically" (on for fresh installs) it is installed without a waiting period, even if automatic updates are otherwise off; otherwise with one click under Updates. See Updates → Automatic security updates and bugfixes only.

Next