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. Migrations run, recording markers so each runs once.
2. Indexes are ensured. Auth and settings index builders are fatal on failure; secret and workflow ones only warn.
3. Default steps are reseeded from the image, overwriting the default library which is why those steps are read-only.

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.

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 they retry, and the poll loop is idempotent.
• 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 page that touches encryption a secret group to confirm KEY_ENCRYPTION_KEY came through.