Environment Variables Reference
All variables are set in .env (development) or Kubernetes ConfigMap/Secret (production). Variables marked Secret must never appear in ConfigMap or be committed to source control.
App
| Variable | Default | Description |
|---|
NODE_ENV | development | Set to production in production builds |
PORT | 3000 | HTTP port the Next.js server listens on |
NEXT_PUBLIC_APP_URL | http://localhost:3000 | Public-facing URL (used in client-side code) |
NextAuth
| Variable | Default | Required | Secret |
|---|
NEXTAUTH_URL | http://localhost:3000 | Yes | No |
NEXTAUTH_SECRET | (none) | Yes | Yes |
NEXTAUTH_URL must match the exact HTTPS URL that browsers use (including scheme and host). Mismatches break session cookies.NEXTAUTH_SECRET must be at least 32 bytes. Generate with: openssl rand -base64 32.
MongoDB
| Variable | Default | Required | Secret |
|---|
MONGODB_URI | mongodb://localhost:27018/core_admin | Yes | Yes |
MONGODB_DB | core_admin | Yes | No |
MONGO_ROOT_USER | (none) | Prod only | Yes |
MONGO_ROOT_PASSWORD | (none) | Prod only | Yes |
MONGODB_URI should include the database name and authentication credentials for production. The development default connects to the MongoDB container started by make dev.
Proxy (BFF → Proxy mTLS)
| Variable | Default | Required | Secret |
|---|
PROXY_LOGIN_URL | https://127.0.0.1:8088/api/v1/user/login | Yes | No |
PROXY_APP_ID | 2 | Yes | No |
PROXY_SERVER_NAME | proxy.local | Yes | No |
PROXY_TLS_CERT_FILE | ./certs/client/core.crt | Yes | No |
PROXY_TLS_KEY_FILE | ./certs/client/core.key | Yes | Yes |
PROXY_TLS_CA_FILE | ./certs/ca/ca.crt | Yes | No |
BFF_PROXY_EMAIL | (none) | Yes | Yes |
BFF_PROXY_PASSWORD | (none) | Yes | Yes |
BFF_PROXY_EMAIL / BFF_PROXY_PASSWORD are the service account credentials used by the BFF to obtain a JWT from Proxy. They are not end-user credentials — they never appear in the UI and are cached in process memory only.
Core API
| Variable | Default | Required | Secret |
|---|
CORE_API_URL | http://localhost:8080 | Yes | No |
CORE_HEALTH_URL | http://127.0.0.1:8092/health | Yes | No |
NEXT_PUBLIC_CORE_URL | (none) | No | No |
CORE_ADMIN_API_KEY | (none) | Yes | Yes |
CORE_TLS_CERT_FILE | ./certs/client/core.crt | mTLS only | No |
CORE_TLS_KEY_FILE | ./certs/client/core.key | mTLS only | Yes |
CORE_TLS_CA_FILE | ./certs/ca/ca.crt | mTLS only | No |
CORE_TLS_SERVER_NAME | core.local | mTLS only | No |
CORE_API_URL: use https:// in production to enable mTLS. Automatically disables mTLS for http:// URLs.CORE_HEALTH_URL: plain HTTP on port 8092 — no mTLS, separate from the admin API port. Intentionally kept HTTP so certificate issues don't make the health probe lie.NEXT_PUBLIC_CORE_URL: shown to users in trigger-mode campaign integration snippets. Leave empty to display $CORE_URL as a placeholder.CORE_ADMIN_API_KEY: sent as X-API-Key header to Core admin endpoints (/api/v1/admin/*, /api/v1/aerospike/*).
| Variable | Default | Description |
|---|
CORE_HEADERS_TIMEOUT_MS | 30000 | Max time (ms) for Core to send the first response-header byte, including mTLS handshake |
CORE_BODY_TIMEOUT_MS | 60000 | Max idle time (ms) between response body chunks for regular API calls |
CORE_UPLOAD_BODY_TIMEOUT_MS | 1800000 | Max idle time (ms) between body chunks for file uploads (30 min — sized for 1 GB over 10 Mbit WAN) |
CORE_AGENT_CONNECTIONS | 32 | Max concurrent keep-alive connections to Core per origin |
CORE_MAX_RESPONSE_BYTES | 16777216 | Hard cap on response body size in bytes (16 MB default) |
Tuning guidance:
- Raise
CORE_BODY_TIMEOUT_MS if fanout or large-list endpoints time out under load.
- Lower
CORE_AGENT_CONNECTIONS if Core is overloaded — the default 32 allows up to 32 simultaneous requests from the BFF.
CORE_MAX_RESPONSE_BYTES protects the Node.js heap. Admin fanout routes can override per-call up to 64 MB. Raise the default only if you see PAYLOAD_TOO_LARGE errors on standard list endpoints.
See Capacity Planning for sizing recommendations.
Upload
| Variable | Default | Description |
|---|
UPLOAD_MAX_BYTES | 1073741824 | Server-side cap on recipient file uploads (1 GB). Governs POST /api/uploads for direct API callers only — the wizard UI enforces an independent 50 MB cap. |
Uploads are streamed end-to-end (disk → Core) without accumulating the file in memory, so the cap is a policy choice rather than a memory constraint.
Audit
| Variable | Default | Description |
|---|
AUDIT_RETENTION_DAYS | 90 | Days before audit log entries are automatically deleted by MongoDB's TTL index. Set to 0 to disable expiry. |
After changing this variable, re-run make migrate — migration v6 idempotently recreates the TTL index with the new value. MongoDB does not update TTL indexes automatically.
Grafana
| Variable | Default | Description |
|---|
GRAFANA_PUBLIC_URL | (empty) | Full URL of the Grafana dashboard to embed in /monitoring as an iframe. Leave empty to hide the monitoring section. |
Grafana must have GF_SECURITY_ALLOW_EMBEDDING=true set for iframe embedding to work. The URL must be reachable from end-users' browsers (not just from the server).
Seed
| Variable | Default | Description |
|---|
SEED_SUPER_ADMIN_EMAIL | admin@example.com | Email address for the super admin account |
SEED_SUPER_ADMIN_NAME | Super Admin | Display name for the super admin account |
SEED_SUPER_ADMIN_PASSWORD | (auto-generated) | Password — auto-generated and written back to .env if empty |
SEED_DEFAULT_WORKSPACE_SLUG | main | URL slug for the default workspace |
SEED_DEFAULT_WORKSPACE_NAME | Main | Display name for the default workspace |
Feature Flags
| Variable | Default | Description |
|---|
ADMIN_DIAGNOSTICS_ENABLED | false | Enables the Aerospike diagnostics panel (/diagnostics/admin). Server-side check only. |
GAP_TRACKER_URL | (empty) | URL for the 🚧 GapBadge popover (internal roadmap tracker). Leave empty to hide gap badges. |
OpenAPI Codegen (Development Only)
| Variable | Default | Description |
|---|
OPENAPI_SRC | ../../core/docs/openapi.yaml | Path to the Core OpenAPI spec used by make sync-openapi. Only relevant for developers running codegen. |
Next Steps