Updates

Vesana updates itself via the admin UI. The updater sidecar runs the update transactionally: backup, pull, migrate, restart, health check, automatic rollback on failure.

Never run docker compose pull manually on a production instance

The GUI updater takes a snapshot of the database and the compose file before each update. Manual updates skip this safety and can leave the stack in an inconsistent state.

Online update (default)

Prerequisites: outbound access to license.vesana.org (update check) and ghcr.io (image pull).

1. Open Admin → Updates
2. Click „Check for updates"
3. Review available version + changelog
4. Click „Update now"

What happens behind the scenes:

sequenceDiagram
    participant UI as Admin UI
    participant U as Updater
    participant LP as Licence portal
    participant R as Registry (ghcr.io)
    participant DB as Postgres

    UI->>U: Start update to vX.Y.Z
    U->>LP: Fetch latest manifest
    U->>DB: pg_dump + .env snapshot
    U->>LP: Pull current docker-compose.prod.yml
    U->>R: docker compose pull
    U->>U: docker compose down api worker
    U->>DB: init container: migrations
    U->>U: docker compose up -d
    U->>U: Health check (90 s timeout)
    U-->>UI: ✓ success  (or ✗ → rollback)

The full update typically takes 1–3 minutes. The UI is unreachable for ~30 seconds (container restart phase).

Offline update

For air-gapped environments or when the server can't reach ghcr.io directly.

Get the package

On a machine with internet:

• Variant A: licence portal (license.vesana.org → Releases → Offline package)
• Variant B: existing online instance: Admin → Updates → „Download offline package"

File: vesana-update-vX.Y.Z.tar.gz. Contents: Docker image tarballs, compose file, manifest, migrations.

Apply

scp vesana-update-vX.Y.Z.tar.gz user@server:/opt/vesana/

Then in the admin UI:

1. Admin → Updates → Upload offline package
2. Select file → „Start update"

Same handling as online: snapshot, migrations, restart, health check, auto-rollback on failure.

Rollback

If an update causes visible problems:

1. Admin → Updates → Rollback
2. Pick a target version from recent snapshots (default: previous version)
3. Confirm

Rollback restores the DB snapshot and starts the old image tags. Data ingested after the update is lost — the rollback button is intentionally clearly marked.

Manual emergency path

Only if the GUI is unreachable and the updater isn't responding:

cd /opt/vesana

# 1. 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 compose file from portal (only if appropriate)
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 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 stack
docker compose -f docker-compose.prod.yml up -d

For an offline update, 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

Agent and collector updates

Agents and collectors update automatically on their next config refresh (~5 minute default). They pull the current version from the server, verify the signature, replace their own binary, and restart the service.

Pause / force: see Agents & collectors → Agent versioning.

Versioning

Vesana follows semver with this discipline:

Bump	Meaning
Patch (0.18.0 → 0.18.1)	Bug fixes, no schema changes, free rollback
Minor (0.18.x → 0.19.0)	New features, additive migrations, conditional rollback
Major (0.x.y → 1.0.0)	Planned breaking changes with migration plan

Schema cleanups (DROP COLUMN/TABLE) come at least two major releases after deprecation. Versioning details: Changelog → Versioning.

Next

• Backup & restore
• Troubleshooting