Upgrade Vellum

This guide shows you how to upgrade a self-hosted Vellum that runs with Docker Compose.

Vellum has no tagged release yet. An upgrade moves the instance to a newer commit of the repository. The data format can change between commits until the first release.

Before you start

You operate the instance: you have the directory with the Vellum source and docker-compose.yml.
You can sign in as the instance administrator.

Upgrade

Make a backup of the database and the master key. Follow Back up. The upgrade changes the database, and no step of Vellum changes it back.
Get the new source.
Terminal window
```
git pull
```
Build the image and start it.
Terminal window
```
docker compose up -d --build --wait
```
Vellum applies the database migrations when it starts. The command returns when the app is healthy.
Sign in. Open Settings, then Instance, then Diagnostics. Check that no module lists a pending migration.
Open a project and play a scenario.

Your session, your settings and your stored credentials survive the upgrade.

After an upgrade

A new version can change an extraction rule. The next scan of a repository then matches the accepted facts to the facts that it finds. When it cannot match a fact exactly, the review asks you to choose. See Extraction rules.

If Vellum does not start

Read the log.

docker compose logs --tail 50 vellum

Vellum does not start explains each message. To go back to the old version, follow If the upgrade fails.

Without Compose

Replace the container image or the published program with the new build, and start it with the same environment. The migrations run at start-up unless Database__MigrateOnStartup is false. See Upgrade in the runbooks.