Environment variables
Complete reference of internal/config.Load's environment-variable surface — nothing
here is inferred; every entry below is read directly from internal/config/profile.go.
General
| Variable | Default | Purpose |
|---|---|---|
CNS_HTTP_ADDR | :8080 | Listen address. |
CNS_ENV | dev | Deployment environment name — stamped onto every event's source.environment and used as the AWS SSM secrets path segment (/cns/<env>/...). |
CNS_DEFAULT_TENANT_ID | katyayani (shipped default — set your own) | Phase-1 single-tenant shortcut: seeds tenant.Resolver's allow-list, so a token asserting any other tenant is rejected. |
CNS_ADMIN_BOOTSTRAP_SUBJECT | (unset) | Grants platform-operator to this one subject_id at boot — the only way to escape the RBAC bootstrap deadlock. |
CNS_ADMIN_STATE_PATH | (unset = in-memory) | Path to a durable JSON snapshot for admin-API state (tenants, apps, policies, RBAC, audit). Unset means every admin mutation is lost on restart. |
CNS_IDENTITY_STATE_PATH | var/identities.json | Identity-map state path. |
CNS_OPERATOR_BOOTSTRAP_EMAIL | (unset) | Read at boot; see source for current wiring. |
CNS_TENANT_ADMIN_BOOTSTRAP_EMAIL | (unset) | Read at boot; see source for current wiring. |
Store
| Variable | Purpose |
|---|---|
CNS_CLICKHOUSE_ENDPOINT | Presence alone selects the clickhouse store implementation. |
CNS_CLICKHOUSE_DATABASE | ClickHouse database name. |
CNS_CLICKHOUSE_TABLE | ClickHouse events table name. |
CNS_CLICKHOUSE_USERNAME | ClickHouse auth. |
CNS_CLICKHOUSE_PASSWORD | ClickHouse auth. |
CNS_STORE_IMPL=memory | Only consulted when CNS_CLICKHOUSE_ENDPOINT is unset — selects the in-process, non-persistent store (dev/test only; required for the dev fixture). |
Neither set → noop (every store call returns "not implemented").
Realtime
| Variable | Purpose |
|---|---|
CNS_CENTRIFUGO_ADDR | Presence alone selects the centrifugo realtime implementation. |
CNS_CENTRIFUGO_API_KEY | Centrifugo HTTP API key. |
Unset → noop, which fails AuthorizeSubscribe closed — see
Realtime & streaming for what that means for
GET /v1/stream.
Identity
| Variable | Purpose |
|---|---|
CNS_SSO_JWT_HMAC_SECRET | Static HMAC signing secret. Presence selects sso-jwt via HMAC. |
CNS_SSO_JWT_JWKS_URL | JWKS endpoint. Presence selects sso-jwt via JWKS (checked only if the HMAC secret is unset). |
CNS_SSO_JWT_ISSUER | Expected iss claim. |
CNS_SSO_JWT_AUDIENCE | Expected aud claim. |
CNS_SSO_JWT_STATIC_TENANT_ID | Fallback tenant id when the token carries no tenant claim (e.g. a non-native IdP — see Wiring a non-native IdP). |
CNS_SSO_JWT_CLAIM_TENANT_ID | Override the claim name read for tenant id. |
CNS_SSO_JWT_CLAIM_EMAIL | Override the claim name read for email. |
CNS_SSO_JWT_CLAIM_PHONE | Override the claim name read for phone. |
Neither signing-key variable set → noop (every request is unauthenticated-fails).
Secrets
| Variable | Default | Purpose |
|---|---|---|
CNS_SECRETS_IMPL | ssm | ssm (AWS SSM, ed25519 local-sign), memory (in-process keystore — no AWS calls at all, required for the dev fixture), or noop. |
The env setting passed to the secrets adapter is always CNS_ENV's value — not a
separate variable.
Dev fixture only
These are never meant for a real deployment — setting CNS_DEV_FIXED_SUBJECT_ID
outside a fixture would collapse every distinct identity onto the same subject_id.
| Variable | Purpose |
|---|---|
CNS_DEV_FIXTURE=1 | Enables the dev-fixture guard rail (see Profiles & adapter selection) — Load refuses to boot unless the rest of the config is provably harmless (loopback address, CNS_ENV=dev, store/secrets = memory, realtime = noop). |
CNS_DEV_FIXED_SUBJECT_ID | Requires CNS_DEV_FIXTURE=1. Pins identity-map resolution to always return this literal subject_id, so a fixture script can pre-compute a bootstrap subject id that's guaranteed correct. |
CNS_DEV_SEED_SUBJECT | If set and the store is memory, seeds a handful of synthetic events for this subject at boot. |
See The dev fixture for how scripts/dev-fixture.sh uses all
three together.