Configuration Reference

What is the Configuration Reference?

This document provides a comprehensive reference for all CVT environment variables and configuration options. CVT is configured primarily through environment variables, making it easy to customize behavior across different deployment environments.

Quick Reference

Category	Key Variables
Core	`CVT_PORT`, `CVT_METRICS_PORT`, `LOG_LEVEL`
TLS	`CVT_TLS_ENABLED`, `CVT_TLS_CERT_FILE`, `CVT_TLS_KEY_FILE`
Authentication	`CVT_API_KEY_ENABLED`, `CVT_API_KEYS`
Storage	`CVT_STORAGE_ENABLED`, `CVT_STORAGE_TYPE`
PostgreSQL	`CVT_POSTGRES_HOST`, `CVT_POSTGRES_USER`, `CVT_POSTGRES_PASSWORD`
Cache	`CVT_STORAGE_CACHE_ENABLED`, `CVT_STORAGE_CACHE_MAX_SCHEMAS`
SDK Client	TLS, API key, and connection settings for SDK clients
Proxy	`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`

Core Settings

Basic server configuration.

Variable	Default	Description
`CVT_PORT`	`9550`	gRPC server port
`CVT_METRICS_PORT`	`9551`	Prometheus metrics endpoint port
`LOG_LEVEL`	`info`	Set to `debug` for development mode with verbose logging

Example

CVT_PORT=9550 CVT_METRICS_PORT=9551 LOG_LEVEL=debug cvt serve

TLS Configuration

Secure communication settings.

Variable	Default	Description
`CVT_TLS_ENABLED`	`false`	Enable TLS encryption
`CVT_TLS_CERT_FILE`	`/certs/server.crt`	Path to server TLS certificate
`CVT_TLS_KEY_FILE`	`/certs/server.key`	Path to server TLS private key
`CVT_TLS_CA_FILE`	-	Path to CA certificate for mTLS client verification
`CVT_TLS_CLIENT_AUTH`	`none`	Client authentication mode: `none`, `request`, `require`

Client Authentication Modes

Mode	Behavior
`none`	No client certificate required
`request`	Request client certificate but don't require it
`require`	Require valid client certificate (mTLS)

Example: TLS Only

CVT_TLS_ENABLED=true \
CVT_TLS_CERT_FILE=./certs/server.crt \
CVT_TLS_KEY_FILE=./certs/server.key \
cvt serve

Example: Mutual TLS (mTLS)

CVT_TLS_ENABLED=true \
CVT_TLS_CERT_FILE=./certs/server.crt \
CVT_TLS_KEY_FILE=./certs/server.key \
CVT_TLS_CA_FILE=./certs/ca.crt \
CVT_TLS_CLIENT_AUTH=require \
cvt serve

API Key Authentication

Optional API key-based authentication for gRPC requests.

Variable	Default	Description
`CVT_API_KEY_ENABLED`	`false`	Enable API key authentication
`CVT_API_KEYS`	-	Comma-separated list of valid API keys
`CVT_API_KEYS_FILE`	-	Path to JSON file with API key configuration

Example: Inline Keys

CVT_API_KEY_ENABLED=true \
CVT_API_KEYS="key1,key2,key3" \
cvt serve

Example: Keys File

CVT_API_KEY_ENABLED=true \
CVT_API_KEYS_FILE=./config/api-keys.json \
cvt serve

API Keys File Format

{
  "keys": [
    {
      "key": "sk_live_abc123",
      "name": "Production Key",
      "scopes": ["*"]
    },
    {
      "key": "sk_test_xyz789",
      "name": "Test Key",
      "scopes": ["read"]
    }
  ]
}

Each key can have the following fields:

Field	Required	Description
`key`	Yes	The API key value
`name`	No	Human-readable name for the key
`scopes`	No	Array of permission scopes (e.g., `["*"]` for all)
`created_at`	No	ISO 8601 timestamp of creation
`expires_at`	No	ISO 8601 timestamp when the key expires

Sending API Keys

Clients must include the API key in the x-api-key metadata header:

// Node.js SDK
import { ContractValidator } from '@sahina/cvt-sdk';

const validator = new ContractValidator({
  address: 'localhost:9550',
  apiKey: 'your-api-key-here',
});

# Python SDK
from cvt_sdk import ContractValidator, ContractValidatorOptions

validator = ContractValidator(ContractValidatorOptions(
    address='localhost:9550',
    api_key='your-api-key-here',
))

SDK Client Configuration

Configure how SDK clients connect to the CVT server, including TLS and API key authentication.

TLS Configuration

Node.js
Python
Go
Java

import { ContractValidator } from "@sahina/cvt-sdk";

const validator = new ContractValidator({
  address: "cvt.internal:9550",
  tls: {
    enabled: true,
    rootCertPath: "./certs/ca.crt", // Server CA certificate
    certPath: "./certs/client.crt", // Client certificate (mTLS)
    keyPath: "./certs/client.key", // Client private key (mTLS)
  },
});

// Use validator as normal
await validator.registerSchema("petstore", "./openapi.json");
validator.close();

from cvt_sdk import ContractValidator, ContractValidatorOptions, TLSOptions

validator = ContractValidator(ContractValidatorOptions(
    address='cvt.internal:9550',
    tls=TLSOptions(
        enabled=True,
        root_cert_path='./certs/ca.crt',
        cert_path='./certs/client.crt',
        key_path='./certs/client.key',
    )
))

validator.register_schema('petstore', './openapi.json')
validator.close()

validator, err := cvt.NewValidatorWithOptions(cvt.ValidatorOptions{
    Address: "cvt.internal:9550",
    TLS: &cvt.TLSOptions{
        Enabled:      true,
        RootCertPath: "./certs/ca.crt",
        CertPath:     "./certs/client.crt",
        KeyPath:      "./certs/client.key",
    },
})
if err != nil {
    log.Fatal(err)
}
defer validator.Close()

ContractValidator validator = ContractValidator.builder()
    .address("cvt.internal:9550")
    .tlsEnabled(true)
    .rootCertPath("./certs/ca.crt")
    .build();

validator.registerSchema("petstore", "./openapi.json");
validator.close();

API Key Configuration

Node.js
Python
Go
Java

const validator = new ContractValidator({
  address: "cvt.internal:9550",
  apiKey: process.env.CVT_API_KEY, // From environment variable
});

import os
from cvt_sdk import ContractValidator, ContractValidatorOptions

validator = ContractValidator(ContractValidatorOptions(
    address='cvt.internal:9550',
    api_key=os.environ.get('CVT_API_KEY'),
))

validator, _ := cvt.NewValidatorWithOptions(cvt.ValidatorOptions{
    Address: "cvt.internal:9550",
    APIKey:  os.Getenv("CVT_API_KEY"),
})

ContractValidator validator = ContractValidator.builder()
    .address("cvt.internal:9550")
    .apiKey(System.getenv("CVT_API_KEY"))
    .build();

Proxy Configuration

Many enterprise environments require HTTP traffic to go through a corporate proxy. This section covers how to configure CVT and your tests to work behind a proxy.

gRPC Traffic (CVT Server Communication)

gRPC uses HTTP/2 and typically doesn't use standard HTTP proxy environment variables. For CVT server communication:

Option 1: Direct Connection (Recommended)

Configure your network to allow direct connections to the CVT server on port 9550. This is the simplest approach and avoids proxy complications with gRPC.

Option 2: gRPC Proxy Support

If you must proxy gRPC traffic, note that different SDKs have different proxy support:

SDK	Proxy Mechanism
Python (grpcio)	Uses `grpc_proxy` / `no_grpc_proxy` environment variables (via gRPC C-core)
Go (grpc-go)	Uses standard `HTTPS_PROXY` / `NO_PROXY` environment variables
Java (grpc-java)	Uses Java's `ProxySelector` / `Authenticator` mechanism
Node.js (@grpc/grpc-js)	No built-in env var support; requires manual proxy configuration

Python example:

export grpc_proxy=http://proxy.corporate.com:8080
export no_grpc_proxy=localhost,127.0.0.1

Go example:

export HTTPS_PROXY=http://proxy.corporate.com:8080
export NO_PROXY=localhost,127.0.0.1

HTTP Traffic (Schema URLs)

When registering schemas from URLs, standard HTTP proxy environment variables apply:

# Set proxy for HTTP/HTTPS traffic
export HTTP_PROXY=http://proxy.corporate.com:8080
export HTTPS_PROXY=http://proxy.corporate.com:8080

# Bypass proxy for local services
export NO_PROXY=localhost,127.0.0.1,.internal.corp

SDK-Specific Configuration

Node.js
Python
Go
Java

Node.js respects HTTP_PROXY and HTTPS_PROXY environment variables for schema URL fetching:

// Environment variables are picked up automatically
// HTTP_PROXY=http://proxy:8080 npm test

// Or configure programmatically with a custom agent
import { HttpsProxyAgent } from 'https-proxy-agent';

const proxyAgent = new HttpsProxyAgent('http://proxy.corporate.com:8080');
// Use with your HTTP client for API calls

Python requests library respects standard proxy environment variables:

import os

# Set programmatically if needed
os.environ['HTTP_PROXY'] = 'http://proxy.corporate.com:8080'
os.environ['HTTPS_PROXY'] = 'http://proxy.corporate.com:8080'
os.environ['NO_PROXY'] = 'localhost,127.0.0.1'

# Or use requests session with explicit proxy
import requests
session = requests.Session()
session.proxies = {
    'http': 'http://proxy.corporate.com:8080',
    'https': 'http://proxy.corporate.com:8080',
}

Go respects HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables:

import (
    "net/http"
    "net/url"
    "os"
)

// Environment variables are picked up automatically by http.Client

// Or configure explicitly
proxyURL, _ := url.Parse("http://proxy.corporate.com:8080")
transport := &http.Transport{
    Proxy: http.ProxyURL(proxyURL),
}
client := &http.Client{Transport: transport}

Java uses system properties for proxy configuration:

// Set via JVM arguments
// -Dhttp.proxyHost=proxy.corporate.com -Dhttp.proxyPort=8080
// -Dhttps.proxyHost=proxy.corporate.com -Dhttps.proxyPort=8080

// Or programmatically
System.setProperty("http.proxyHost", "proxy.corporate.com");
System.setProperty("http.proxyPort", "8080");
System.setProperty("https.proxyHost", "proxy.corporate.com");
System.setProperty("https.proxyPort", "8080");
System.setProperty("http.nonProxyHosts", "localhost|127.0.0.1");

CI/CD Pipeline Configuration

In CI/CD environments, proxy configuration is typically set at the pipeline level:

GitHub Actions:

env:
  HTTP_PROXY: ${{ secrets.CORPORATE_PROXY }}
  HTTPS_PROXY: ${{ secrets.CORPORATE_PROXY }}
  NO_PROXY: localhost,127.0.0.1

GitLab CI:

variables:
  HTTP_PROXY: http://proxy.corporate.com:8080
  HTTPS_PROXY: http://proxy.corporate.com:8080
  NO_PROXY: localhost,127.0.0.1,cvt

Jenkins:

environment {
    HTTP_PROXY = 'http://proxy.corporate.com:8080'
    HTTPS_PROXY = 'http://proxy.corporate.com:8080'
    NO_PROXY = 'localhost,127.0.0.1'
}

SSL Certificate Issues

Corporate proxies often perform SSL inspection, which can cause certificate validation failures. Solutions:

Add corporate CA to trust store:

# Node.js
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

# Python
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca.crt

# Java
keytool -import -trustcacerts -file corporate-ca.crt -alias corporate -keystore $JAVA_HOME/lib/security/cacerts

Disable SSL verification (development only):

# NOT recommended for production
export NODE_TLS_REJECT_UNAUTHORIZED=0  # Node.js

Security

Never disable SSL verification in production environments. Always use proper certificate configuration.

Persistent Storage

Configure backend storage for schemas, consumers, and validation records.

Storage Architecture

For detailed information about storage backends, caching strategies, and data models, see Storage Layer Architecture.

Variable	Default	Description
`CVT_STORAGE_ENABLED`	`false`	Enable persistent storage (default uses in-memory)
`CVT_STORAGE_TYPE`	`sqlite`	Storage backend: `memory`, `sqlite`, `postgres`
`CVT_STORAGE_DSN`	`cvt.db`	Data source name for SQLite
`CVT_VALIDATION_RETENTION_DAYS`	`90`	Days to retain validation records

Storage Types

Type	Use Case	Persistence
`memory`	Development, testing	None (lost on restart)
`sqlite`	Single-instance deployments	Local file
`postgres`	Production, multi-instance	External database

Example: SQLite

CVT_STORAGE_ENABLED=true \
CVT_STORAGE_TYPE=sqlite \
CVT_STORAGE_DSN=./data/cvt.db \
cvt serve

Example: PostgreSQL

CVT_STORAGE_ENABLED=true \
CVT_STORAGE_TYPE=postgres \
CVT_POSTGRES_HOST=db.example.com \
CVT_POSTGRES_USER=cvt \
CVT_POSTGRES_PASSWORD=secret \
CVT_POSTGRES_DB=cvt \
cvt serve

PostgreSQL Settings

Configuration for PostgreSQL storage backend.

Variable	Default	Description
`CVT_POSTGRES_HOST`	`localhost`	PostgreSQL host
`CVT_POSTGRES_PORT`	`5432`	PostgreSQL port
`CVT_POSTGRES_USER`	`cvt`	PostgreSQL user
`CVT_POSTGRES_PASSWORD`	-	PostgreSQL password
`CVT_POSTGRES_DB`	`cvt`	PostgreSQL database name
`CVT_POSTGRES_SSLMODE`	`disable`	SSL mode: `disable`, `require`, `verify-ca`, `verify-full`
`CVT_POSTGRES_DSN`	-	Full PostgreSQL DSN (alternative to individual settings)
`CVT_POSTGRES_MAX_CONNS`	`25`	Maximum database connections

Individual Settings vs DSN

You can configure PostgreSQL either with individual variables or a single DSN:

Individual Variables:

CVT_POSTGRES_HOST=db.example.com \
CVT_POSTGRES_PORT=5432 \
CVT_POSTGRES_USER=cvt \
CVT_POSTGRES_PASSWORD=secret \
CVT_POSTGRES_DB=cvt \
CVT_POSTGRES_SSLMODE=require \
cvt serve

Single DSN:

CVT_POSTGRES_DSN="postgres://cvt:secret@db.example.com:5432/cvt?sslmode=require" \
cvt serve

If both are provided, CVT_POSTGRES_DSN takes precedence.

SSL Modes

Mode	Description
`disable`	No SSL (not recommended for production)
`require`	Use SSL but don't verify certificate
`verify-ca`	Verify server certificate is signed by trusted CA
`verify-full`	Verify CA and that server hostname matches certificate

Cache Settings

In-memory cache configuration (used with persistent storage).

Variable	Default	Description
`CVT_STORAGE_CACHE_ENABLED`	`true`	Enable in-memory cache with persistent storage
`CVT_STORAGE_CACHE_MAX_SCHEMAS`	`1000`	Maximum number of schemas in cache

The cache uses Ristretto with a 24-hour TTL by default.

Example

CVT_STORAGE_ENABLED=true \
CVT_STORAGE_TYPE=postgres \
CVT_STORAGE_CACHE_ENABLED=true \
CVT_STORAGE_CACHE_MAX_SCHEMAS=5000 \
cvt serve

Port Configuration Summary

Port	Purpose
`9550`	gRPC server (configurable via `CVT_PORT`)
`9551`	Prometheus metrics (configurable via `CVT_METRICS_PORT`)
`9091`	Prometheus UI (when using Docker observability stack)
`3000`	Grafana UI (when using Docker observability stack)

Docker Configuration

docker-compose.yml Example

services:
  cvt-server:
    image: ghcr.io/sahina/cvt:latest
    ports:
      - "9550:9550"
      - "9551:9551"
    environment:
      - CVT_PORT=9550
      - CVT_METRICS_PORT=9551
      - LOG_LEVEL=info
      - CVT_STORAGE_ENABLED=true
      - CVT_STORAGE_TYPE=postgres
      - CVT_POSTGRES_HOST=postgres
      - CVT_POSTGRES_USER=cvt
      - CVT_POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - CVT_POSTGRES_DB=cvt
      # TLS (optional)
      # - CVT_TLS_ENABLED=true
      # - CVT_TLS_CERT_FILE=/certs/server.crt
      # - CVT_TLS_KEY_FILE=/certs/server.key
    volumes:
      - ./certs:/certs:ro
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_USER=cvt
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=cvt
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Environment File (.env)

# Core
CVT_PORT=9550
CVT_METRICS_PORT=9551
LOG_LEVEL=info

# Storage
CVT_STORAGE_ENABLED=true
CVT_STORAGE_TYPE=postgres

# PostgreSQL
CVT_POSTGRES_HOST=localhost
CVT_POSTGRES_PORT=5432
CVT_POSTGRES_USER=cvt
CVT_POSTGRES_PASSWORD=your-secret-password
CVT_POSTGRES_DB=cvt
CVT_POSTGRES_SSLMODE=require

# Security
CVT_API_KEY_ENABLED=true
CVT_API_KEYS_FILE=/etc/cvt/api-keys.json

# TLS
CVT_TLS_ENABLED=true
CVT_TLS_CERT_FILE=/etc/cvt/certs/server.crt
CVT_TLS_KEY_FILE=/etc/cvt/certs/server.key

Production Recommendations

Security

Enable TLS in production environments
Use mTLS for service-to-service communication
Enable API key authentication to control access
Use PostgreSQL SSL mode verify-full for database connections
Rotate API keys regularly

Storage

Use PostgreSQL for production deployments
Configure connection pooling appropriately (CVT_POSTGRES_MAX_CONNS)
Set up database backups for disaster recovery
Monitor disk usage for validation record retention

Observability

Expose metrics endpoint to your monitoring system
Configure log aggregation for centralized logging
Set appropriate log level (info for production, debug for troubleshooting)

Consumer Testing Guide - Test API integrations
CI/CD Integration Guide - Pipeline examples
CLI Reference - Command-line options
Observability Guide - Metrics and monitoring
Development Guide - Local development setup

What is the Configuration Reference?​

Quick Reference​

Core Settings​

Example​

TLS Configuration​

Client Authentication Modes​

Example: TLS Only​

Example: Mutual TLS (mTLS)​

API Key Authentication​

Example: Inline Keys​

Example: Keys File​

API Keys File Format​

Sending API Keys​

SDK Client Configuration​

TLS Configuration​

API Key Configuration​

Proxy Configuration​

gRPC Traffic (CVT Server Communication)​

HTTP Traffic (Schema URLs)​

SDK-Specific Configuration​

CI/CD Pipeline Configuration​

SSL Certificate Issues​

Persistent Storage​

Storage Types​

Example: SQLite​

Example: PostgreSQL​

PostgreSQL Settings​

Individual Settings vs DSN​

SSL Modes​

Cache Settings​

Example​

Port Configuration Summary​

Docker Configuration​

docker-compose.yml Example​

Environment File (.env)​

Production Recommendations​

Security​

Storage​

Observability​

Related Documentation​

What is the Configuration Reference?

Quick Reference

Core Settings

Example

TLS Configuration

Client Authentication Modes

Example: TLS Only

Example: Mutual TLS (mTLS)

API Key Authentication

Example: Inline Keys

Example: Keys File

API Keys File Format

Sending API Keys

SDK Client Configuration

TLS Configuration

API Key Configuration

Proxy Configuration

gRPC Traffic (CVT Server Communication)

HTTP Traffic (Schema URLs)

SDK-Specific Configuration

CI/CD Pipeline Configuration

SSL Certificate Issues

Persistent Storage

Storage Types

Example: SQLite

Example: PostgreSQL

PostgreSQL Settings

Individual Settings vs DSN

SSL Modes

Cache Settings

Example

Port Configuration Summary

Docker Configuration

docker-compose.yml Example

Environment File (.env)

Production Recommendations

Security

Storage

Observability

Related Documentation