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 | Hourly limits per API key. On the agent gateway every copy of an ISO shares one key, and proofs and log archives are counted apart, so the unit value is the number of machines one ISO can wipe per hour (default 100, production 1000). |
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. There is no renewal, so set it to the lifetime of an ISO (production: 43800h, 5 years); the agent CA must outlive it. |
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. |
Blockchain Anchoring (Hedera HCS) link
Per ADR 0002, anchoring uses two Hedera Consensus Service (HCS) topics per
configured chain instead of EVM smart contracts. Variables are namespaced
BLOCKCHAIN_<CHAIN>_*, chain hedera-testnet shown:
| Variable | Use |
|---|
BLOCKCHAIN_ENABLED | Master switch for anchoring; false keeps certificates at CERTIFIED_NO_ANCHOR. |
BLOCKCHAIN_DEFAULT_CHAIN / BLOCKCHAIN_CHAINS | Default chain ID and the set of enabled chains routed by chain_registry. |
BLOCKCHAIN_HEDERA_TESTNET_NETWORK | testnet, previewnet, or mainnet. |
BLOCKCHAIN_HEDERA_TESTNET_OPERATOR_ID | Exaion operator account (0.0.x). |
BLOCKCHAIN_HEDERA_TESTNET_OPERATOR_KEY_ID | Signer key reference for the operator ED25519 key. |
BLOCKCHAIN_HEDERA_TESTNET_ANCHOR_TOPIC | Anchor topic ID (0.0.x); submit key is the KeyList of currently authorized party keys. |
BLOCKCHAIN_HEDERA_TESTNET_REGISTRY_TOPIC | Registry topic ID (0.0.x); records authorize/revoke events for party accounts. |
BLOCKCHAIN_HEDERA_TESTNET_MIRROR_NODE_URL | Mirror node REST base URL (defaults per network); used for free public verification reads. |
*_ANCHOR_CONTRACT, *_ADDRESS_REGISTRY, and *_GAS (the previous EVM
contract variables) are removed. Anchoring keys accept both the historical EVM
long-zero form (0x…) and the native Hedera account ID (0.0.x); the adapter
normalises to 0.0.x. Provision topics and manage party authorization with
cmd/hedera-hcs (create-topics, authorize, revoke, info, smoke); see
Proofs And Certificates for the
anchoring lifecycle.
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. |