Environment variables

Celum is configured entirely through the environment. This page lists what the backend and the dashboard actually read — nothing here is aspirational, and anything absent from this page is ignored if you set it.

Values in angle brackets are placeholders. Defaults shown as — mean the variable is empty unless you set it, and the feature it belongs to stays off.

Core

Variable	Default	Purpose
`PORT`	`8080`	Port the API listens on
`DATABASE_URL`	—	PostgreSQL connection string. Without it there is no IAM evaluator, so authorization passes through.
`KUBECONFIG_PATH`	—	Kubeconfig for requests that name no supervisor (`__default__`). It adds no supervisor: a supervisor is a kubeconfig registered under Settings → Kubeconfigs and kept in the database.

Without KUBECONFIG_PATH, requests that name no supervisor use Celum’s own in-cluster service account when Celum runs inside Kubernetes, and ~/.kube/config otherwise.

Authentication

Variable	Default	Purpose
`OIDC_ISSUER`	—	Discovery URL. Auto-built as `https://login.microsoftonline.com/<tenant>/v2.0` when unset and `AZURE_AD_TENANT_ID` is present.
`OIDC_CLIENT_ID`	—	Falls back to `AZURE_AD_CLIENT_ID`
`OIDC_CLIENT_SECRET`	—	Falls back to `AZURE_AD_CLIENT_SECRET`
`OIDC_REDIRECT_URL`	—	`https://<api-host>/auth/callback`, registered with your provider
`OIDC_MAPPING_SOURCE`	`groups`	Which claim maps to IAM groups: `groups` or `roles`
`OIDC_GROUPS_CLAIM`	derived	Explicit claim-name override; takes precedence over `OIDC_MAPPING_SOURCE`
`SESSION_SECRET`	generated	HMAC key for session JWTs
`SESSION_MAX_AGE`	`86400`	Session lifetime in seconds
`FRONTEND_URL`	`http://localhost:3000`	Redirect target after login and logout
`COOKIE_DOMAIN`	—	Cookie domain, e.g. `.example.com` for cross-subdomain sessions
`AUTH_DISABLED`	`false`	Development only. Injects a mock admin and skips token validation.
`AZURE_AD_TENANT_ID`	—	Used to construct `OIDC_ISSUER` and as the Azure Key Vault tenant fallback

Leaving SESSION_SECRET unset does not fail the boot — the backend generates a random key and logs a warning. Every session is then invalidated on restart. Set it explicitly in any deployment you expect to restart.

Authorization

Variable	Default	Purpose
`IAM_ENABLED`	`false`	`true` enforces policies; anything else logs would-be denials and allows the request
`IAM_DEBUG`	`false`	Logs each check with the resolved action, KRN, and matching statement
`LICENSE_ENFORCED`	see purpose	`true` makes Celum read-only without a valid licence, after 30 days from the first start; `false` only logs what a licence would refuse. Unset means `true` when `APPLIANCE_AIRGAP` is present (every appliance’s environment has it) and `false` otherwise.

Observability

Variable	Default	Purpose
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	OTLP/HTTP endpoint. Empty installs a no-op tracer, so there is no cost when unconfigured.
`OTEL_SERVICE_NAME`	`celum-backend`	Service name on emitted spans
`LOG_FORMAT`	auto	`text`, `json`, or empty for text on a TTY
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, or `error`
`SENTRY_DSN`	—	Sentry-protocol error sink (Sentry, GlitchTip). Empty disables error reporting. Read from the secret store first.
`SENTRY_ENVIRONMENT`	—	Environment tag on reported errors, for example `prod`.
`SENTRY_RELEASE`	`<OTEL_SERVICE_NAME>@<APP_VERSION>`	Overrides the release tag on reported errors.
`SENTRY_TRACES_SAMPLE_RATE`	`0`	Share of API requests recorded as performance transactions, from `0` to `1`. Any other value means `0`.

Integrations

Variable	Default	Purpose
`GITHUB_TOKEN`	—	Optional PAT for the GitHub Releases API used by version pickers. Unset means anonymous rate limits. No scopes needed for public repositories.
`GODADDY_API_KEY`	—	GoDaddy DNS API key
`GODADDY_API_SECRET`	—	GoDaddy DNS API secret
`GODADDY_BASE_URL`	—	GoDaddy API base URL
`ACME_EMAIL`	built-in	Registration address for Let’s Encrypt. Ships with a default — set your own.
`DEX_ISSUER_URL`	—	Base URL of a Dex broker for Grafana sign-in. There is no built-in value. Empty means no Dex: the Monitoring step does not offer Dex broker, and an install that asks for it is refused.
`OMNI_API_URL`	—	Omni gRPC endpoint. Empty disables the integration and the wizard falls back to detecting pod CIDRs from node specs.
`OMNI_SERVICE_ACCOUNT_KEY`	—	Base64 PGP service-account key for Omni
`MCP_ENABLED`	`false`	Mounts the Model Context Protocol endpoint at `/mcp`, authenticated by Bearer token
`SLACK_BOT_TOKEN`	—	Slack bot token (`xoxb-…`). Empty disables Slack notifications entirely.
`SLACK_APP_TOKEN`	—	Slack app-level token (`xapp-…`, scope `connections:write`). Enables Socket Mode — inbound interactivity over an outbound WebSocket, for firewalled deployments.
`SLACK_SIGNING_SECRET`	—	Verifies the inbound Request URL interactivity callback. Alternative to Socket Mode; needs a public endpoint.
`SLACK_CHANNEL`	—	Target channel id (`C0…`) or `#name`
`ALERT_WEBHOOK_URL`	—	The URL that a supervisor’s Alertmanager posts alerts to: this Celum’s `https://<api-host>/api/alerts/webhook`. With `ALERT_WEBHOOK_TOKEN` also set, the Monitoring step offers Send this supervisor’s alerts to Slack. Set it on only one Celum for each set of supervisors, because two Celums that set it take each other’s alerts.
`ALERT_WEBHOOK_TOKEN`	—	The bearer token that Alertmanager presents to `POST /api/alerts/webhook`. Empty disables the endpoint, which then answers `503`. If the secret store cannot be read, the boot continues and the feature stays off.

Celum does not write to Git. GITLAB_URL, GITLAB_TOKEN, GITLAB_PROJECT_ID and GITLAB_BRANCH, which older deployments set, are not read; setting them does nothing.

Appliance

The Celum appliance writes these into the backend’s environment. Do not set them on another deployment.

Variable	Default	Purpose
`APPLIANCE_REGISTRY`	—	The name of the registered registry that is the appliance’s own Harbor. Its presence tells the backend that it runs on an appliance (`GET /api/appliance/posture`). Onboarding then declares each new supervisor’s image mirror from that Harbor.
`APPLIANCE_AIRGAP`	`off`	`off` or `strict`. With `strict`, the image mirror that Celum declares from the appliance has Strict air-gap on, unless Flux already runs on that supervisor. Any other value stops the backend from starting. Its presence also turns `LICENSE_ENFORCED` on by default.
`APPLIANCE_IMAGE_S3_ENDPOINT`	—	The S3 endpoint (an `http` or `https` URL) of the image-library source that the appliance offers every supervisor without an S3 connection of its own.
`APPLIANCE_IMAGE_S3_BUCKET`	—	The bucket of that source.
`APPLIANCE_IMAGE_S3_ACCESS_KEY`	—	The access key of that source.
`APPLIANCE_IMAGE_S3_SECRET_KEY`	—	The secret key of that source; read from the secret store first. If any of the four is missing, the backend ignores the source and logs which one.

Secret store

Credential-shaped values can come from Vault or Azure Key Vault instead of the environment. Set SECRET_BACKEND to switch it on.

Variable	Default	Purpose
`SECRET_BACKEND`	—	`vault`, `azure-kv`, or empty for environment-only
`SECRETS_OPTIONAL`	`false`	`true` lets the boot continue when the store is unreachable. Development and CI only.

Vault
Azure Key Vault

Variable	Default	Purpose
`VAULT_ADDR`	—	Required. Vault address.
`VAULT_ROLE_ID`	—	Required. AppRole role ID.
`VAULT_SECRET_ID`	—	Required. AppRole secret ID.
`VAULT_KV_MOUNT`	`celum`	KV v2 secrets-engine mount — the first path segment.
`VAULT_APPROLE_PATH`	`approle`	AppRole auth-method mount.
`VAULT_BOOT_TIMEOUT`	`120s`	Total retry budget for the initial connection.
`VAULT_WRITE_ROLE_ID`	read pair	Optional separate credential for the write path.
`VAULT_WRITE_SECRET_ID`	read pair	Optional separate credential for the write path.
`VAULT_BOOTSTRAP_ROLE_ID`	—	Optional third credential, and the most privileged one. See the warning below.
`VAULT_BOOTSTRAP_SECRET_ID`	—	Its secret id. Both must be set, or bootstrapping stays off.
`VAULT_BOOTSTRAP_ALLOW`	—	Allowlist of what may be bootstrapped. Empty means deny everything.
`VAULT_PKI_CLUSTERS_MOUNT`	`pki-clusters`	The PKI mount that signs supervisor certificates for the Appliance CA issuer in the Certificates step. Change it only when the clusters intermediate is mounted elsewhere.

Variable	Default	Purpose
`AZURE_KEYVAULT_URL`	—	Required. `https://<name>.vault.azure.net/`
`AZURE_TENANT_ID`	—	Required, falls back to `AZURE_AD_TENANT_ID`.
`AZURE_CLIENT_ID`	—	Required.
`AZURE_CLIENT_SECRET`	—	Required.
`AZURE_KEYVAULT_PREFIX`	`celum`	Leading segment of every secret name — Key Vault’s equivalent of a mount.

Which values the store resolves

Variable	Path in the store	Key
`SESSION_SECRET`	`backend/session`	`secret`
`OIDC_CLIENT_SECRET`	`backend/oidc`	`client_secret`
`GITHUB_TOKEN`	`backend/github`	`token`
`GODADDY_API_KEY`	`backend/godaddy`	`api_key`
`GODADDY_API_SECRET`	`backend/godaddy`	`api_secret`
`OMNI_SERVICE_ACCOUNT_KEY`	`backend/omni`	`service_account_key`
`SLACK_BOT_TOKEN`	`backend/slack`	`bot_token`
`SLACK_APP_TOKEN`	`backend/slack`	`app_token`
`SLACK_SIGNING_SECRET`	`backend/slack`	`signing_secret`
`ALERT_WEBHOOK_TOKEN`	`backend/alerts`	`webhook_token`
`SENTRY_DSN`	`backend/sentry`	`dsn`
`APPLIANCE_IMAGE_S3_SECRET_KEY`	`backend/appliance`	`image_s3_secret_key`

Under Vault the mount is prepended, so backend/github is read from celum/backend/github by default. Non-credential values, such as URLs and IDs, stay in the environment.

VAULT_BOOTSTRAP_ROLE_ID / VAULT_BOOTSTRAP_SECRET_ID are a third credential and the only one that can change Vault itself: with them the backend may enable auth mounts and write celum-eso-* policies, so that a new supervisor’s External Secrets Operator can be wired without a human in Vault. That is a much larger grant than reading and writing secrets, which is why it is opt-in, off by default, and gated by VAULT_BOOTSTRAP_ALLOW — an empty allowlist denies everything, and the backend logs the effective list on every boot that has bootstrapping enabled.

Precedence

The store wins

A non-empty value from the store is used, and the environment variable is ignored.

Absent or empty falls back to the environment

A missing secret, or one present but empty, falls through to the environment variable. A mistyped path therefore degrades to the old value rather than blanking the credential.

Any other error fails the boot

Denied, sealed, or unreachable stops the backend from starting. It does not fall back — booting with empty credentials would log everyone out and break integrations silently.Three credentials are optional and do not stop the boot: ALERT_WEBHOOK_TOKEN, SENTRY_DSN and APPLIANCE_IMAGE_S3_SECRET_KEY. When the store denies or cannot serve one of them, the backend uses the environment value. If that is empty too, the feature stays off. The startup line then names the source as env(after <backend> error) or unavailable(optional).

One log line at startup names every credential and where it came from — env, env(fallback), the backend name, or ERROR. Names and sources only, never values. Check it when a hotfix value you set in the environment appears to have no effect: store-wins means it was ignored.

With a store configured, an empty session secret is a boot failure, not a warning. Auto-generating one would invalidate every session on each restart, so the backend refuses to start until backend/session#secret exists.

Dashboard

The Next.js dashboard reads a much smaller set:

Variable	Default	Purpose
`BACKEND_URL`	—	Internal API URL for server-side fetches, e.g. `http://backend:8080`
`BACKEND_PUBLIC_URL`	—	Public API URL, injected into the browser at request time. Falls back to `BACKEND_URL`, then `http://localhost:8080`.
`AUTH_DISABLED`	`false`	Mirrors the backend flag for development
`APP_VERSION`	—	Version string shown in the UI

BACKEND_PUBLIC_URL is injected at request time rather than baked in at build time, so one image runs against any environment. No NEXT_PUBLIC_ variables are used.

Quickstart

A working Compose stack using these variables.

Authentication & IAM

What the OIDC variables do in the sign-in flow.

Permissions model

IAM_ENABLED and IAM_DEBUG in context.

Glossary

Terms used across these settings.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Administration

Environment variables

Core

Authentication

Authorization

Observability

Integrations

Appliance

Secret store

Which values the store resolves

Precedence

Dashboard

Quickstart

Authentication & IAM

Permissions model

Glossary

​Core

​Authentication

​Authorization

​Observability

​Integrations

​Appliance

​Secret store

​Which values the store resolves

​Precedence

​Dashboard

​Related

Quickstart

Authentication & IAM

Permissions model

Glossary

Core

Authentication

Authorization

Observability

Integrations

Appliance

Secret store

Which values the store resolves

Precedence

Dashboard

Related