vantage-docs/docs/operations/upgrading.md

id, title, sidebar_label

id	title	sidebar_label
upgrading	Upgrading	Upgrading

Upgrading the control plane is a pull and a recreate. Agents are versioned and upgraded separately. See Agent updates.

:::info Cloud instances upgrade themselves This page is for self-hosted installs. If your instance is hosted by us, there is nothing here for you to do. :::

Upgrade

cd /opt/vantage
docker compose pull
docker compose up -d --remove-orphans

--remove-orphans clears containers for services that no longer exist in the Compose file, which is what leaves a stale container running after a service is renamed or removed.

What happens on boot

1. The database is brought up to date. Each change runs once.
2. The built-in workflow steps are reinstalled, which is why those steps cannot be edited.

If Vantage cannot complete either safely, it stops rather than run half-prepared.

Watch it:

docker compose logs -f server

Before you upgrade

• Back up MongoDB. See Backups. Migrations are one-way.
• Read the release notes for anything about migrations or environment variables.
• Check your .env still supplies everything required. A newly required variable stops the boot rather than defaulting to something unsafe.

Single sign-on after an upgrade

Each identity provider now has its own callback URL. If you configured single sign-on on an older version it was carried over, but its callback URL changed, and sign-in through it fails until you copy the new one from its card in Settings and register it with your identity provider. The card shows a reminder until you dismiss it.

Password sign-in is unaffected, so you can always sign in locally to fix this.

Downgrading

There is no automatic downgrade. Migrations do not roll back, so returning to an older image means restoring the database backup taken before the upgrade. This is the reason the backup is not optional.

Zero-downtime

The stack is not designed for it. docker compose up -d recreates the server container, which is a short interruption:

• Agents reconnect on their own.
• Workflow runs in progress lose their command stream. Steps already dispatched finish on the agent, but their results have nowhere to go. Do not upgrade during a run.
• Sessions survive, because they live in Redis rather than in the server.

After upgrading

• Confirm every service is running.
• Confirm servers return to active within a couple of poll intervals.
• Open a secret group, to confirm KEY_ENCRYPTION_KEY came through.