Skip to content
TruthVouch Docs

Installation

Deploy the TruthVouch Governance Gateway on your own infrastructure with Docker Compose. This guide covers prerequisites, image configuration, security verification, and health check validation.

Prerequisites

Before installing, ensure your host meets the following requirements:

  • Docker 24+ (install guide)
  • Docker Compose v2+ (included with Docker Desktop, or install separately)
  • TruthVouch Enterprise subscription with self-hosted deployment enabled
  • API credentials from the TruthVouch dashboard (Settings > Self-Hosted)

You’ll also need an OpenAI API key for the AI engine’s embedding generation and NLI inference.

Quick Start

1. Download the Deployment Template

Terminal window
# Download the official self-hosted docker-compose file and environment template
curl -sL https://gitlab.com/sentinal2/Sentinal/-/raw/master/docker/gateway/docker-compose.self-hosted.yml -o docker-compose.yml
curl -sL https://gitlab.com/sentinal2/Sentinal/-/raw/master/docker/gateway/.env.example -o .env

2. Configure Your Environment

Open .env and fill in the required values:

Terminal window
vi .env

At minimum, set these variables:

VariableWhere to Find ItDescription
GATEWAY_CLIENT_IDDashboard > Settings > Self-HostedYour organization UUID
DEPLOYMENT_IDDashboard > Settings > Self-Hosted > DeploymentsIdentifies this gateway instance
GATEWAY_API_KEYSDashboard > Settings > API KeysComma-separated keys for your apps to call the gateway
TRUTHVOUCH_CLOUD_API_KEYDashboard > Settings > Self-Hosted > Sync KeyAllows the sync agent to pull policy updates
OPENAI_API_KEYOpenAI dashboardUsed by the AI engine for embeddings and NLI checks
POSTGRES_PASSWORDYou chooseDatabase password — set before first startup

3. Launch the Stack

Terminal window
docker compose up -d

Docker Compose starts the services in dependency order: database and cache first, then AI engine, then the API and gateway, and finally the sync agent.

4. Verify All Services Are Healthy

Terminal window
# Check that all containers report "healthy"
docker compose ps

All 6 services should show a healthy status. If any show starting or unhealthy, check their logs:

Terminal window
docker compose logs <service-name>

Container Images

The self-hosted stack uses 4 TruthVouch container images plus PostgreSQL and Redis:

ImagePurposePorts
ghcr.io/truthvouch/governance-gatewayGovernance pipeline — scans AI requests and responses via gRPC and REST50052 (gRPC), 8090 (REST/health)
ghcr.io/truthvouch/gateway-api.NET 9 Knowledge API — manages knowledge base, policies, and configuration5010 (HTTP)
ghcr.io/truthvouch/ai-enginePython AI service — embedding generation and NLI faithfulness inference50051 (gRPC)
ghcr.io/truthvouch/gateway-syncSync agent — pulls config and policies from TruthVouch cloud, refreshes JWKS keys8091 (HTTP/health)

The stack also provisions:

  • PostgreSQL 16 with TimescaleDB and pgvector extensions (for audit storage and vector embeddings)
  • Redis 7 (L1 response cache with 256 MB LRU eviction)

All 4 TruthVouch images are published to the GitHub Container Registry (GHCR) and built for linux/amd64.

Version Pinning

All 4 TruthVouch images share the same version number — they are released as a coordinated set. Control the version with the GATEWAY_VERSION environment variable.

We strongly recommend pinning to a specific version rather than using latest:

Terminal window
# In your .env file
GATEWAY_VERSION=1.0.0

When GATEWAY_VERSION is set, every container in the stack pulls the exact same release. This ensures compatibility between services and makes deployments reproducible.

To see available versions, check the Releases page or list tags in GHCR:

Terminal window
# List available gateway image tags
docker buildx imagetools inspect ghcr.io/truthvouch/governance-gateway

Image Verification

Every container image published by TruthVouch is signed using Sigstore cosign with keyless OIDC signing. This means the signature is tied to the CI pipeline identity that built the image — there is no private key to manage or rotate.

Verify an Image Signature

Terminal window
cosign verify ghcr.io/truthvouch/governance-gateway:1.0.0 \
  --certificate-identity-regexp="https://gitlab.com/sentinal2/Sentinal//.*" \
  --certificate-oidc-issuer="https://gitlab.com"

A successful verification confirms:

  1. The image was built by a TruthVouch CI pipeline (not tampered with after push)
  2. The Sigstore transparency log contains a matching entry

Repeat for each image (gateway-api, ai-engine, gateway-sync) if you want full verification.

SBOM Inspection

Every published container image has a CycloneDX Software Bill of Materials (SBOM) attached as an OCI artifact. The SBOM lists all direct and transitive dependencies, their versions, and SPDX license identifiers.

Retrieve the Attached SBOM

Terminal window
# Download the SBOM attached to the image as an OCI artifact
cosign download sbom ghcr.io/truthvouch/governance-gateway:1.0.0 > sbom-governance-gateway.cdx.json

SBOMs are also available as downloadable artifacts on each GitLab Release. Each release includes sbom-governance-gateway.cdx.json, sbom-gateway-api.cdx.json, sbom-ai-engine.cdx.json, and sbom-gateway-sync.cdx.json.

Use SBOMs for Vulnerability Scanning

Feed the CycloneDX SBOM into your organization’s vulnerability scanner:

Terminal window
# Example with Grype
grype sbom:sbom-governance-gateway.cdx.json


# Example with Trivy
trivy sbom sbom-governance-gateway.cdx.json

Health Check Verification

After the stack starts, verify each service is responsive:

Terminal window
# Governance Gateway (REST health endpoint)
curl -s http://localhost:8090/health
# Expected: {"status": "healthy", ...}


# Gateway API (.NET Knowledge API)
curl -s http://localhost:5010/healthz
# Expected: Healthy


# Sync Agent
curl -s http://localhost:8091/healthz
# Expected: {"status": "ok", ...}

The PostgreSQL and Redis health checks are handled internally by Docker Compose — docker compose ps reports their status.

Troubleshooting Unhealthy Containers

If a service fails its health check:

Terminal window
# View logs for the failing service
docker compose logs --tail 100 gateway


# Common issues:
# - gateway-db: POSTGRES_PASSWORD not set or port conflict on 5432
# - gateway-ai: OPENAI_API_KEY missing or invalid
# - gateway:    Database not ready (check gateway-db health first)
# - gateway-sync: TRUTHVOUCH_CLOUD_API_KEY missing or cloud API unreachable

Environment Variable Reference

For a complete reference of all configurable environment variables (port overrides, sync intervals, audit retention, CORS origins, and more), see the comments in the .env.example file or the Firewall Configuration Reference.

Next Steps