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

```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.

## 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.
