---
id: upgrading
title: Upgrading
sidebar_label: Upgrading
---

Upgrading the control plane is a pull and a recreate. Agents are versioned and
upgraded separately. See [Agent updates](./agent-updates.md).

:::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

```bash
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:

```bash
docker compose logs -f server
```

## Before you upgrade

- **Back up MongoDB.** See [Backups](./backups.md). 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.