Skip to content

Configuration

Verity uses pydantic-settings for configuration management. Each service reads environment variables with a service-specific prefix, falling back to sensible defaults for local development.

How Configuration Works

flowchart LR
    ENV[".env file<br/>or shell exports"] --> DC["docker-compose.yml<br/><code>x-app-env</code> anchor"]
    DC --> SVC["Service container"]
    SVC --> PS["pydantic-settings<br/><code>BaseSettings</code>"]
    PS --> CFG["Typed config object"]

    style ENV fill:#7c4dff,color:#fff,stroke:none
    style PS fill:#536dfe,color:#fff,stroke:none
    style CFG fill:#40c4ff,color:#000,stroke:none
  1. .env file — top-level defaults loaded by Docker Compose
  2. docker-compose.yml — the x-app-env YAML anchor injects shared variables into every service
  3. Per-service overrides — individual service blocks can add or override variables
  4. pydantic-settings — each service has a BaseSettings subclass with an env_prefix that maps environment variables to typed Python attributes

Prefix convention

A variable like API_DB_HOST=postgres is read by the API Gateway's APIConfig class (which has env_prefix = "API_") as self.db_host.

Shared Infrastructure Variables

These variables are injected into every service via the x-app-env anchor in docker-compose.yml:

PostgreSQL / TimescaleDB

Variable Default Description
VERITY_PG_HOST postgres PostgreSQL hostname
VERITY_PG_PORT 5432 PostgreSQL port
VERITY_PG_USER verity Database user
VERITY_PG_PASSWORD verity_dev Database password
VERITY_PG_DATABASE verity Database name
DB_HOST postgres Alias — used by some services
DB_PORT 5432 Alias — used by some services
DB_USER verity Alias — used by some services
DB_PASSWORD verity_dev Alias — used by some services
DB_DATABASE verity Alias — used by some services

Dual variable names

Both VERITY_PG_* and DB_* forms exist for compatibility. The VERITY_PG_* form is canonical; DB_* is provided as a convenience for services that use the shorter prefix.

Kafka

Variable Default Description
KAFKA_BOOTSTRAP_SERVERS kafka:9092 Comma-separated list of Kafka broker addresses

Redis

Variable Default Description
REDIS_URL redis://redis:6379 Full Redis connection URL (supports redis:// and rediss:// schemes)

Temporal

Variable Default Description
TEMPORAL_HOST temporal:7233 Temporal server gRPC endpoint

ClickHouse

Variable Default Description
CLICKHOUSE_HOST clickhouse ClickHouse server hostname
CLICKHOUSE_PORT 8123 ClickHouse HTTP interface port

Per-Service Configuration

Each service uses pydantic-settings with a unique env_prefix. Variables are formed as {PREFIX}{FIELD_NAME} in UPPER_SNAKE_CASE.

API Gateway — API_ prefix

The API Gateway is the primary entry point for all client traffic. Configuration class: services/api-gateway/config.py.

Variable Type Default Description
API_HOST str 0.0.0.0 Bind address
API_PORT int 8000 Listen port
API_WORKERS int 4 Uvicorn worker count
API_LOG_LEVEL str INFO Log level (DEBUG, INFO, WARNING, ERROR)
API_DB_HOST str localhost PostgreSQL host
API_DB_PORT int 5432 PostgreSQL port
API_DB_USER str verity PostgreSQL user
API_DB_PASSWORD str verity PostgreSQL password
API_DB_NAME str verity PostgreSQL database
API_DB_MIN_POOL int 2 Minimum connection pool size
API_DB_MAX_POOL int 10 Maximum connection pool size
API_REDIS_URL str redis://localhost:6379/0 Redis URL for caching
API_KAFKA_BOOTSTRAP_SERVERS str localhost:9092 Kafka brokers
API_TEMPORAL_HOST str localhost:7233 Temporal gRPC endpoint
API_TEMPORAL_NAMESPACE str verity Temporal namespace
API_CLICKHOUSE_HOST str localhost ClickHouse host
API_CLICKHOUSE_PORT int 8123 ClickHouse HTTP port
API_CLICKHOUSE_USER str default ClickHouse user
API_CLICKHOUSE_PASSWORD str (empty) ClickHouse password
API_CLICKHOUSE_DB str verity ClickHouse database
API_CORS_ORIGINS str * Allowed CORS origins (comma-separated)
API_DEV_MODE bool false Enable dev mode (disables auth)

Decay Engine — DECAY_ prefix

Computes and persists access-decay scores.

Variable Type Default Description
DECAY_SCORE_THRESHOLD float 70.0 Score above which a grant is flagged for review
DECAY_BATCH_SIZE int 500 Number of grants processed per batch
DECAY_SCHEDULE_INTERVAL int 3600 Seconds between scoring cycles

Audit Writer — AUDIT_WRITER_ prefix

Consumes audit events from Kafka and writes them to ClickHouse.

Variable Type Default Description
AUDIT_WRITER_BATCH_SIZE int 1000 Rows per ClickHouse batch insert
AUDIT_WRITER_FLUSH_INTERVAL int 5 Seconds between flushes

Workflow Engine — WORKFLOW_ prefix

Orchestrates review and remediation workflows via Temporal.

Variable Type Default Description
WORKFLOW_TEMPORAL_HOST str temporal:7233 Temporal gRPC endpoint
WORKFLOW_TEMPORAL_NAMESPACE str verity Temporal namespace
WORKFLOW_REVIEW_SLA_HOURS int 72 Default SLA for review completion
WORKFLOW_ESCALATION_HOURS int 48 Hours before auto-escalation

Review Generator — REVIEW_GEN_ prefix

Creates review packets when decay scores exceed thresholds.

Variable Type Default Description
REVIEW_GEN_MIN_SCORE float 70.0 Minimum decay score to trigger a review
REVIEW_GEN_BATCH_SIZE int 200 Grants evaluated per cycle

Remediation Executor — REMEDIATION_ prefix

Executes approved access revocations against source platforms.

Variable Type Default Description
REMEDIATION_DRY_RUN bool true When true, log actions without executing
REMEDIATION_MAX_CONCURRENT int 10 Maximum concurrent revocation operations

Azure AD Connector — AAD_ prefix

Variable Type Default Description
AAD_TENANT_ID str — Azure AD tenant ID
AAD_CLIENT_ID str — App registration client ID
AAD_CLIENT_SECRET str — App registration client secret
AAD_POLL_INTERVAL int 300 Seconds between audit log polls

Authentication Configuration

Verity uses Azure AD (Entra ID) for production authentication via OpenID Connect.

Development Mode

By default, docker compose sets API_DEV_MODE=true, which:

  • Disables Azure AD token validation
  • Returns a synthetic admin principal for all requests
  • Allows unauthenticated access to all API endpoints

Never use dev mode in production

Dev mode bypasses all authentication and authorisation. Always set API_DEV_MODE=false in production deployments.

Production Authentication

To enable Azure AD authentication:

# Required — identifies your Azure AD tenant and app registration
API_DEV_MODE=false
API_AZURE_TENANT_ID=your-tenant-id-here
API_AZURE_CLIENT_ID=your-client-id-here
API_AZURE_CLIENT_SECRET=your-client-secret-here   # for backend flows

The API Gateway will:

  1. Validate JWT bearer tokens against your tenant's OIDC discovery endpoint
  2. Extract user identity from the oid and preferred_username claims
  3. Map the authenticated user to a Verity principal via external ID matching
Azure AD App Registration Setup
  1. Register an application in Azure AD
  2. Add a Web redirect URI: http://localhost:3000/auth/callback
  3. Create a client secret under Certificates & Secrets
  4. Under API Permissions, add User.Read and AuditLog.Read.All (for the AAD connector)
  5. Grant admin consent for your organisation

Configuration File Locations

File Purpose
.env.example Template with all supported variables and defaults
.env Your local overrides (git-ignored)
docker-compose.yml x-app-env anchor + per-service environment blocks
services/api-gateway/config.py API Gateway pydantic-settings model
services/analytics/decay-engine/config.py Decay Engine config
services/decision/workflow-engine/config.py Workflow Engine config

Environment Layering

Configuration is resolved with the following precedence (highest wins):

1. Shell environment variable          (highest priority)
2. docker-compose.yml service block
3. docker-compose.yml x-app-env anchor
4. .env file
5. pydantic-settings default value     (lowest priority)

Override example

To temporarily increase the API worker count without modifying files:

API_WORKERS=8 docker compose up -d api-gateway

Next Steps