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

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

## Upgrading the hosted deployment

Both Compose files, together:

```bash
cd /opt/vantage
docker compose -f docker-compose.yml -f docker-compose.site.yml pull
docker compose -f docker-compose.yml -f docker-compose.site.yml up -d --remove-orphans
```

CI builds and pushes images but does **not** deploy them; rolling out is this
manual step. See [CI/CD](./ci-cd.md).

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