Configuration¶

All runtime configuration is provided through environment variables in infra/compose/.env (copied from infra/compose/.env.example).

Environment variable reference¶

PostgreSQL (required)¶

Gateway API¶

Internal service auth (required)¶

Egress proxy¶

Signing¶

Risk engine — checker email delivery¶

The EU AI Act checker's "email a copy" feature posts to the risk engine's POST /v1/checker/email. Every other part of the checker runs entirely in the browser and needs none of this.

OPENCOMPLAI_SMTP_HOST is the switch: with it unset the endpoint returns 503 MAILER_NOT_CONFIGURED and nothing else in the stack is affected.

Configuring SMTP is not sufficient to enable the button on the public docs site. That also requires the browser to be allowed to reach the risk engine — see the checker email section.

Observability (Phase 15)¶

CLI environment variables¶

The opencomplai CLI also reads one environment variable:

AI plugin data egress¶

The optional opencomplai-ai plugin classifies detected AI usage. Every model in the catalog except saas runs entirely on this machine and sends nothing.

The saas backend posts code snippets to https://api.opencomplai.com. It is gated three ways:

1. Offline mode. With OPENCOMPLAI_OFFLINE set it never runs, whatever else is configured.
2. One-time consent. opencomplai ai configure --model saas shows what would leave the machine and records an explicit opt-in in ~/.opencomplai/ai-config.yaml. Without a current grant the backend sends nothing and reports why. Non-interactive runs are refused rather than defaulted in either direction.
3. Redaction. Snippets are scrubbed for secret- and PII-shaped content before transmission. This is a mitigation, not a guarantee — pattern matching cannot catch a credential that reads like ordinary text. For a regulated deployment the real control is OPENCOMPLAI_OFFLINE=1 or a local model.

Model downloads are pinned to an immutable upstream revision and checksum- verified where the catalog records one — on download and on every cache hit, so a later local modification of a cached model is caught. An unpinned model is refused outright when stdin is not interactive: unattended is exactly where an upstream substitution would go unnoticed.

EU AI Act checker email on the docs site¶

Enabling "email a copy" on a hosted docs site takes three independent changes. Any one of them alone leaves the feature non-functional, so they are listed together here:

1. Give the risk engine an SMTP server — see Risk engine — checker email delivery above. Without OPENCOMPLAI_SMTP_HOST the endpoint returns 503 MAILER_NOT_CONFIGURED.

2. Tell the widget where the risk engine is. Set the origin in docs/src/assets/js/checker-config.js:

window.OCOC_RISK_ENGINE_URL = "https://api.example.com";

While this is empty the widget hides the email form rather than showing a button that cannot work. The JSON, Markdown, and print exports are unaffected and need no backend.

1. Allow the browser to reach that origin. Add it to connect-src in the Content-Security-Policy header in vercel.json:

connect-src 'self' https://api.example.com;

Without this the browser blocks the request no matter what step 2 says.

There is no public risk-engine deployment today, so all three are deliberately left unset and the email form does not render on the published docs.

When the docs are served from localhost (e.g. mkdocs serve), the widget falls back to http://localhost:8001 on the assumption that a developer is running the stack locally. It does not do this on any other host — that address would be the visitor's own machine.

Minimum .env for a quickstart¶

POSTGRES_PASSWORD=use_a_strong_random_password_here
INTERNAL_SERVICE_TOKEN_SECRET=use_a_strong_random_secret_here

These two are fail-closed with no default — the stack will not start without them. All other variables have safe defaults.