Skip to content

Versioning

Scheme

Vesana runs on the 1.9 line: 1.9.<patch>. Every change self-hosters should receive is its own release — which is why the patch number climbs quickly (several releases per day are normal). A release can be a single fix or a bundled release of several changes; the release notes inside the instance (Admin → System → Updates) list each of them. A jump to 2.0 is a deliberate, announced decision, never an automatic side effect.

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

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.
  • Community profiles are not touched automatically — you apply profile updates deliberately 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 (signature-checked). 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 normal patch release — there is no separate channel. If you set the waiting time of automatic updates to "immediately" you get it within minutes; otherwise after the waiting time or with one click under Updates.

Next