Environment variable reference
Clearplane uses environment variables for bootstrap settings and secrets only. Every other runtime setting uses a container label or the UI. Bootstrap settings are read once at startup; an invalid value stops the service with a message naming the variable. The complete configuration catalog lists every supported variable with its accepted values, default, resolution order, and apply behavior. Service and redirect resources are label-only; Clearplane never reads environment variables from discovered application containers.
Trusted proxies and the ordered client IP headers are runtime settings: configure clearplane.edge.trusted-proxies and clearplane.edge.client-ip-headers with Edge labels or System → Settings → Edge → Network, not environment variables. See client address resolution.
Every setting has a built-in default for the published images, so the shipped Compose file sets no Clearplane environment variables. Set one only to override its default, in that service's environment: block, in the Compose file itself or an override file. A .env file beside docker-compose.yml feeds only Compose interpolation and never reaches the containers. An unknown CLEARPLANE_CORE_*, CLEARPLANE_EDGE_*, CLEARPLANE_UI_* or CLEARPLANE_CONTAINER_PROXY_* variable stops that service at startup with a message naming it, so a typo or a removed variable never passes silently. The catalog lists development-only variables separately; production deployments set none of them. Core generates the machine secrets in the data volumes, and Core and Edge read them from there; their direct variables are accepted only in Development.
Using an LLM or coding agent? Open the plain-text environment variable reference, the LLM documentation index, or the complete documentation file.
DNS-profile secret files
An individual numbered profile can read its token from a mounted file instead of a scalar environment value:
services:
clearplane-core:
environment:
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_1_NAME: cloudflare-production
CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_1_API_TOKEN_FILE: /run/secrets/cloudflare-api-token
secrets:
- cloudflare-api-token
secrets:
cloudflare-api-token:
file: ./secrets/cloudflare-api-token
Keep the example secret file outside source control.
When a numbered profile is invalid, startup reports the exact expanded variable, for example CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_2_API_TOKEN, rather than the <INDEX> template. Secret values are never included in the error.
Docker Compose inputs
Set these values in the invoking shell, a sibling .env file, or a file passed with Compose --env-file. Service environment blocks do not participate in Compose interpolation.
| Environment variable | What it does |
|---|---|
COMPOSE_PROJECT_NAME |
Overrides the Compose project name, which defaults to clearplane. Core reads the project from its own container to verify first-party container ownership. |
CLEARPLANE_IMAGE_TAG |
Overrides the image tag for all four services. This does not provide database rollback. |