Environment variable groups that operators must review before running a non-local instance.
Configuration Reference link
The backend is configured from environment variables. The canonical local list
is backend/.env.example; the root compose file supplies defaults for the
reference stack.
Core HTTP And Public URLs link
| Variable | Use |
|---|
DEPLOYMENT_MODE | cloud, onprem, or airgapped; do not rely on it alone for network policy. |
HTTP_ADDRESS | API bind address, usually :8080. |
HTTP_SHUTDOWN_TIMEOUT | Graceful shutdown window. |
HTTP_CORS_ALLOW_ORIGINS | Browser origins allowed to call the API directly. |
HTTP_HSTS_ENABLED | Enables HSTS when TLS terminates at the API or trusted proxy chain. |
PUBLIC_VERIFY_BASE_URL | Base URL used in certificate QR and public verification links. |
PUBLIC_INVITATION_BASE_URL | Base URL used in invitation acceptance links. |
Security Controls link
| Variable | Use |
|---|
ADMIN_API_ALLOWED_CIDRS | Explicit IP/CIDR allowlist for /admin/api/v1. |
ADMIN_API_ALLOW_INTERNAL_NETWORKS | Allows loopback/private/link-local admin clients for internal deployments. |
SENSITIVE_ACTION_MFA_MAX_AGE | Recent-MFA window for sensitive writes; 0 disables local-only checks. |
SECURITY_OUTBOUND_ALLOWED_HOSTS | Host allowlist for IdP metadata, branding URLs, and webhooks. |
SECURITY_OUTBOUND_ALLOWED_CIDRS | Explicit IP ranges allowed by outbound URL policy. |
SECURITY_OUTBOUND_ALLOW_PRIVATE_NETWORKS | Only enable for controlled internal deployments. |
VERIFY_RATE_LIMIT_PER_MINUTE / VERIFY_RATE_LIMIT_PER_HOUR | Public verification rate limits. |
VERIFY_CAPTCHA_SECRET / VERIFY_CAPTCHA_VERIFY_URL | Optional Turnstile/hCaptcha-style siteverify integration. |
Identity And Keycloak link
| Variable | Use |
|---|
KEYCLOAK_MASTER_ISSUER / KEYCLOAK_EXAWIPE_ISSUER | Public issuer URLs that must match JWT iss. |
KEYCLOAK_MASTER_AUDIENCE / KEYCLOAK_EXAWIPE_AUDIENCE | Expected JWT audiences. |
KEYCLOAK_MASTER_JWKS_URL / KEYCLOAK_EXAWIPE_JWKS_URL | JWKS endpoints used by the API. |
KEYCLOAK_JWKS_CACHE_TTL | JWKS cache duration. |
KEYCLOAK_ADMIN_* | Optional Admin API service-account configuration for provisioning users and IdPs. |
For the new frontend BFF, configure APP_BASE_URL, API_INTERNAL_URL,
KEYCLOAK_ISSUER_MASTER, KEYCLOAK_ISSUER_EXAWIPE, KEYCLOAK_INTERNAL_URL,
web client IDs/secrets, and a 32-byte or longer SESSION_SECRET.
Database, Queue, And Migrations link
| Variable | Use |
|---|
DATABASE_DSN | Main application DSN. |
DATABASE_AUTOMIGRATE | Kept for developer compatibility; production should rely on SQL migrations. |
DATABASE_SEED_DEV | Seeds local demo data; disable outside local/dev. |
QUEUE_BACKEND | Current implementation is table. |
MIGRATIONS_DATABASE_URL | DSN for the migrator image. |
MIGRATIONS_ACTION | version, up, or other migrator command. |
Ingest And Agent Trust link
| Variable | Use |
|---|
INGEST_EMBEDDED | true embeds /ingest/v1 in the API; false expects standalone cmd/ingest. |
INGEST_HTTP_ADDRESS | Standalone ingest bind address. |
INGEST_DATABASE_DSN | Least-privilege ingest DB role; falls back to DATABASE_DSN when empty. |
INGEST_RATE_LIMIT_UNIT_PER_HOUR / INGEST_RATE_LIMIT_BATCH_PER_HOUR | Per-agent-key proof submission limits. |
AGENT_TRUST_MODE | dev, ed25519, or x509 proof-signature verification mode. |
AGENT_CA_CERT_FILE / AGENT_CA_KEY_FILE | Operator CA for issued agent mTLS certificates. |
AGENT_CLIENT_CERT_TTL | Lifetime for issued agent client certificates. |
PROOF_MIN_AGENT_VERSION | Minimum accepted proof payload agent version. |
Signer And PAdES link
| Variable | Use |
|---|
SIGNER_MODE | test locally; production depends on final remote signer protocol. |
SIGNER_ENDPOINT / SIGNER_TIMEOUT | Remote signer endpoint and timeout. |
SIGNER_BEARER_TOKEN | Optional bearer credential when the remote protocol uses it. |
SIGNER_TLS_CA_FILE, SIGNER_TLS_CLIENT_CERT_FILE, SIGNER_TLS_CLIENT_KEY_FILE | mTLS material. |
CONSUMPTION_RECEIPT_SIGNATURE_KEY_ID | Key ID used for signed consumption receipts. |
PADES_MODE | dev or eidas. |
PADES_TSA_URL and credentials | RFC 3161 timestamp authority integration. |
LICENSE_DEV_MODE=true enables dev grant-signature bypasses and is refused when
the environment declares production. Keep it disabled outside local test data.
Storage And Notifications link
| Variable | Use |
|---|
STORAGE_BACKEND | s3 or filesystem. |
STORAGE_FILESYSTEM_ROOT | Root path for filesystem storage. |
S3_ENDPOINT, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY | S3-compatible storage connection. |
S3_BUCKET_PROOFS, S3_BUCKET_CERTIFICATES, S3_BUCKET_BINARIES, S3_BUCKET_EXPORTS, S3_BUCKET_BILLING_DROP | Required bucket names. |
NOTIFICATION_TRANSPORT | disabled, smtp, or webhook-capable transport behavior. |
NOTIFICATION_SMTP_* | SMTP relay settings. |
Observability, Retention, Reporting link
| Variable | Use |
|---|
OBSERVABILITY_ENABLED | Enables OTel logging/metrics/traces. |
OBSERVABILITY_SERVICE_NAME | Optional override; binaries set useful defaults. |
OBSERVABILITY_ENVIRONMENT | Environment label for signals. |
OBSERVABILITY_OTLP_ENDPOINT, OBSERVABILITY_OTLP_INSECURE, OBSERVABILITY_OTLP_HEADERS | OTel exporter settings. |
RETENTION_AUDIT_LOG_TTL | Audit log retention, default intent 5 years. |
RETENTION_VERIFICATION_LOG_TTL | Public verification log retention, default intent 5 years. |
RETENTION_VERIFICATION_METADATA_TTL | IP/user-agent hash anonymization, default intent 90 days. |
RETENTION_CLEANUP_INTERVAL, RETENTION_BATCH_SIZE | Maintenance worker cadence and batch size. |
REPORTING_CO2_KG_PER_DEVICE | CO2 estimate factor used in usage/billing reporting. |