Skip to content
TruthVouch Docs

Upgrading

Upgrade the TruthVouch Governance Gateway by changing the GATEWAY_VERSION environment variable and restarting the stack. All 4 TruthVouch images are released as a coordinated set, so a single version number controls the entire deployment.

Before You Upgrade

1. Check Release Notes

Review the release notes for every version between your current version and the target version:

Terminal window
# View releases on GitLab
open https://gitlab.com/sentinal2/Sentinal/-/releases

Look for:

  • Breaking changes — API contract changes, configuration format changes, or removed features
  • Required environment variables — New variables that must be set before upgrading
  • Database migrations — Any schema changes (these are applied automatically, but you should be aware of them)

2. Check the Compatibility Matrix

Verify your target version is compatible with your TruthVouch cloud subscription and SDK versions. See the Compatibility Matrix for details.

3. Back Up Your Database

Always back up the gateway database before upgrading:

Terminal window
# Create a database backup
docker compose exec gateway-db pg_dump \
  -U vt_gateway_user \
  -d truthvouch_gateway \
  --format=custom \
  --file=/tmp/gateway-backup-$(date +%Y%m%d).dump


# Copy the backup to your host
docker compose cp gateway-db:/tmp/gateway-backup-*.dump ./backups/

4. Verify Current Deployment Health

Confirm all services are healthy before starting the upgrade:

Terminal window
docker compose ps
# All services should show "healthy"

Upgrade Process

Standard Upgrade

Terminal window
# 1. Set the target version
export GATEWAY_VERSION=1.1.0


# 2. Pull the new images
docker compose pull


# 3. Restart the stack with the new images
docker compose up -d

Docker Compose detects which images have changed and only restarts the affected containers. Services are restarted in dependency order (database first, then AI engine, then API and gateway, then sync agent).

Verify the Upgrade

Terminal window
# Check all containers are running the new version and healthy
docker compose ps


# Verify health endpoints
curl -s http://localhost:8090/health
curl -s http://localhost:5010/healthz
curl -s http://localhost:8091/healthz

Version Scheme

All 4 TruthVouch container images share the same version tag for every release:

ImageTag Example
ghcr.io/truthvouch/governance-gateway1.1.0
ghcr.io/truthvouch/gateway-api1.1.0
ghcr.io/truthvouch/ai-engine1.1.0
ghcr.io/truthvouch/gateway-sync1.1.0

Do not mix versions across images. The services communicate via gRPC and share a database schema — version mismatches can cause protocol errors or data inconsistencies.

Each release tag follows Semantic Versioning:

  • Major (e.g., 2.0.0) — Breaking changes; review migration guide before upgrading
  • Minor (e.g., 1.1.0) — New features, backward-compatible
  • Patch (e.g., 1.0.1) — Bug fixes and security patches, backward-compatible

Database Migrations

Database schema migrations are applied automatically when the gateway and API containers start. The init scripts embedded in the containers detect the current schema version and apply any pending migrations.

You do not need to run migrations manually. However:

  • Always back up before upgrading (see above)
  • Migrations are forward-only — there is no automatic rollback of schema changes
  • Check release notes for any migration-specific instructions (e.g., expected downtime for large tables)

Rollback

If the new version causes issues, roll back by reverting to the previous version:

Terminal window
# Set the previous version
export GATEWAY_VERSION=1.0.0


# Pull and restart
docker compose pull
docker compose up -d

Important caveats:

  • If the new version applied database migrations, rolling back the container images does not revert the schema. The previous version must be compatible with the new schema (minor and patch versions are designed for this).
  • If a major version upgrade applied breaking schema changes, you may need to restore from your database backup:
    Terminal window
    # Stop the stack
    docker compose down
    

    # Restore the database backup
    docker compose up -d gateway-db
    docker compose exec -T gateway-db pg_restore \
      -U vt_gateway_user \
      -d truthvouch_gateway \
      --clean \
      /tmp/gateway-backup-20260403.dump
    

    # Restart with the previous version
    export GATEWAY_VERSION=1.0.0
    docker compose up -d

Pinning Your Version in .env

Rather than exporting GATEWAY_VERSION in your shell, pin it in your .env file for persistence across reboots and deployments:

.env
GATEWAY_VERSION=1.1.0

This ensures docker compose up -d always uses the pinned version, even if the shell variable is not set.

Checking for New Releases

Monitor for new releases via:

  • GitLab Releases — gitlab.com/sentinal2/Sentinal/-/releases
  • Sync Agent — The sync agent reports the currently deployed version to TruthVouch cloud, which can notify you when a newer version is available via the dashboard

Next Steps