Skip to content
TruthVouch Docs

Firewall: Docker

Deploy the TruthVouch Governance Gateway using Docker and docker-compose for a quick, self-contained setup.

Prerequisites

  • Docker 20.10+
  • Docker Compose 2.0+
  • PostgreSQL 14+ (or use Docker Postgres service)
  • 4GB RAM minimum, 8GB recommended

Quick Start

1. Clone the Repository

Terminal window
git clone https://github.com/VouchedTruth/truthvouch
cd truthvouch/docker

2. Configure Environment

Create a .env file:

# Database
POSTGRES_PASSWORD=YourSecurePassword123!
POSTGRES_DB=truthvouch_gateway
POSTGRES_USER=gateway_user


# Gateway
GATEWAY_WORKERS=4
GATEWAY_LOG_LEVEL=INFO
GATEWAY_ENV=production


# LLM Configuration
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

3. Docker Compose File

version: '3.8'


services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-gateway_user}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB:-truthvouch_gateway}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init-db.sql:/docker-entrypoint-initdb.d/01-init.sql
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5


  gateway:
    image: truthvouch/governance-gateway:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      GATEWAY_WORKERS: ${GATEWAY_WORKERS:-4}
      GATEWAY_LOG_LEVEL: ${GATEWAY_LOG_LEVEL:-INFO}
      GATEWAY_ENV: ${GATEWAY_ENV:-production}
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
    ports:
      - "50052:50052"  # gRPC
      - "8080:8080"    # Health checks
      - "9090:9090"    # Prometheus metrics
    volumes:
      - ./config.yaml:/app/config/config.yaml
      - gateway_logs:/app/logs
    healthcheck:
      test: ["CMD", "grpcurl", "-plaintext", "localhost:50052", "list"]
      interval: 30s
      timeout: 10s
      retries: 3
    networks:
      - truthvouch


  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - truthvouch


volumes:
  postgres_data:
  gateway_logs:
  redis_data:


networks:
  truthvouch:
    driver: bridge

4. Start the Services

Terminal window
docker-compose up -d

5. Verify Installation

Terminal window
# Check logs
docker-compose logs gateway


# Test health endpoint
curl http://localhost:8080/health


# Test gRPC connectivity (requires grpcurl)
grpcurl -plaintext localhost:50052 list

Configuration

Environment Variables

VariableDefaultDescription
POSTGRES_USERgateway_userDatabase user
POSTGRES_PASSWORD-Database password (required)
POSTGRES_DBtruthvouch_gatewayDatabase name
DATABASE_URL-Full connection string (auto-generated)
GATEWAY_WORKERS4Number of worker processes
GATEWAY_LOG_LEVELINFOLog level (DEBUG, INFO, WARN, ERROR)
GATEWAY_ENVproductionEnvironment (development, staging, production)
OPENAI_API_KEY-OpenAI API key
ANTHROPIC_API_KEY-Anthropic API key

Custom Configuration File

Create config.yaml:

server:
  host: 0.0.0.0
  port: 50052
  workers: 4
  request_timeout_ms: 30000


database:
  # Connection pool settings
  pool_size: 20
  max_overflow: 40
  pool_timeout_sec: 30


scanning:
  # Enable/disable scan stages
  stages:
    - name: pii_scanner
      enabled: true
    - name: injection_scanner
      enabled: true
    - name: toxicity_scanner
      enabled: true
    - name: hallucination_detector
      enabled: true


  # Scan thresholds
  thresholds:
    toxicity_score: 0.7
    hallucination_score: 0.8
    pii_risk: 0.6


caching:
  # Redis caching for embeddings
  enabled: true
  host: redis
  port: 6379
  ttl_seconds: 3600


logging:
  level: ${GATEWAY_LOG_LEVEL}
  format: json
  file: /app/logs/gateway.log

Volume Mounts

Required Volumes

volumes:
  postgres_data:     # Database persistence
  gateway_logs:      # Application logs
  redis_data:        # Cache persistence

Custom Configuration

Mount your config file into the container:

volumes:
  - ./config.yaml:/app/config/config.yaml:ro
  - ./policies:/app/policies:ro

Network Configuration

Expose the Gateway

The gateway runs on port 50052 (gRPC). Expose it to your application:

Terminal window
# Direct access (for containers in same network)
grpc://gateway:50052


# External access (with reverse proxy)
grpc://gateway.yourcompany.local:50052

Connect Your Application

Python:

import grpc
from truthvouch.gateway import GatewayStub


channel = grpc.aio.secure_channel(
    'gateway:50052',
    grpc.ssl_channel_credentials(
        root_certificates=open('ca.crt').read()
    )
)
stub = GatewayStub(channel)

Node.js:

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');


const packageDef = protoLoader.loadSync('gateway.proto', {});
const grpcLib = grpc.loadPackageDefinition(packageDef);
const client = new grpcLib.truthvouch.Gateway(
    'gateway:50052',
    grpc.credentials.createSsl()
);

Health Checks

HTTP Health Endpoint

Terminal window
curl http://localhost:8080/health
# Response: {"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}

Database Health

Terminal window
docker-compose exec postgres psql -U gateway_user -d truthvouch_gateway -c "SELECT 1"

Cache Health

Terminal window
docker-compose exec redis redis-cli ping
# Response: PONG

Monitoring

View Metrics

Access Prometheus metrics:

Terminal window
curl http://localhost:9090/metrics

Key Metrics

  • gateway_requests_total — Total requests processed
  • gateway_scan_duration_seconds — Scan latency
  • gateway_database_queries — Database query count
  • gateway_cache_hits — Redis cache hit rate

Logs

View Logs

Terminal window
# All services
docker-compose logs -f


# Specific service
docker-compose logs -f gateway


# Tail last 100 lines
docker-compose logs --tail 100 gateway

Log Levels

Set in .env:

GATEWAY_LOG_LEVEL=DEBUG  # Verbose output
GATEWAY_LOG_LEVEL=INFO   # Normal operation
GATEWAY_LOG_LEVEL=WARN   # Warnings and errors
GATEWAY_LOG_LEVEL=ERROR  # Errors only

Scaling

Horizontal Scaling

Run multiple gateway instances:

Terminal window
docker-compose up -d --scale gateway=3

Use a load balancer (Nginx, HAProxy):

upstream gateway_backend {
    server gateway:50052;
    server gateway:50053;
    server gateway:50054;
}

Troubleshooting

Gateway fails to start

Terminal window
# Check logs
docker-compose logs gateway


# Common issue: Port already in use
lsof -i :50052


# Common issue: Database connection failed
docker-compose logs postgres

High memory usage

Terminal window
# Increase memory limit in docker-compose.yml
services:
  gateway:
    mem_limit: 8g
    memswap_limit: 8g

Slow scanning

Terminal window
# Increase worker count in .env
GATEWAY_WORKERS=8


# Check database query performance
docker-compose exec postgres psql -U gateway_user -d truthvouch_gateway

Cleanup

Terminal window
# Stop services
docker-compose down


# Remove volumes (WARNING: deletes data)
docker-compose down -v


# Remove images
docker image rm truthvouch/governance-gateway:latest

Production Deployment

For production, refer to the Kubernetes guide for:

  • High availability setup
  • Automated scaling
  • Resource management
  • Monitoring and alerting