Upgrading

Upgrading VaultTerm means moving to a newer image and letting migrations run on boot. The procedure differs only in how the new image reaches the host: pulled and rebuilt on a connected install, or carried in a bundle for an air-gapped one. Either way, take a database backup first.

Back up first

Migrations are forward-only — there is no down-migration. The database backup is therefore both your safety net and your rollback path: if an upgrade goes wrong, you restore the pre-upgrade dump. Do not skip it. See Backups and recovery for the pg_dump command and the full list of what to back up (the database, .env, and the db-data volume).

Connected upgrade

On a host with the repository and network access, pull the new code and rebuild:

cd deploy/onprem
git pull
docker compose up -d --build        # rebuilds the app image; migrations run on boot

The app container applies any pending migrations on boot, then recreates with the new image. There is no separate migration step. Watch the logs to confirm migrations applied and the server started:

docker compose logs -f app
curl -fsS http://localhost:4000/health

Air-gapped upgrade

For a disconnected host, rebuild the bundle on the connected side with a new version tag, transfer it, and extract over the install directory — your .env is preserved.

# On the connected host
cd deploy/onprem
./bundle-offline.sh v1.1.0          # new version tag

# Transfer the tarball, then on the air-gapped host
tar -xzf vaultterm-onprem-v1.1.0.tar.gz -C /opt/vaultterm
cd /opt/vaultterm
./install-offline.sh                # loads the new image and recreates the app container

Extracting over the existing install directory keeps your .env, so you do not reconfigure secrets or URLs. install-offline.sh loads the new image and recreates the app container, which runs migrations on boot exactly as a connected upgrade does. See Air-gapped install for how the bundle is built and transferred.

After upgrading

• Confirm migrations applied and the server started (the log lines above).
• Confirm /health returns OK.
• If anything is wrong, restore the pre-upgrade database backup.

Next

• Backups and recovery — back up before every upgrade; it is the rollback path.
• Air-gapped install — the bundle build and transfer.