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.

CLEARPLANE_EDGE_BOOTSTRAP_CORE_URI must be an HTTPS origin such as https://clearplane-core:8443. Edge uses it for the mutually authenticated control-plane connection; HTTP, credentials, paths, queries, and fragments are rejected.

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_PROFILE_1_NAME: cloudflare-production
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_1_API_TOKEN_FILE: /run/secrets/cloudflare-api-token
    secrets:
      - cloudflare-api-token

secrets:
  cloudflare-api-token:
    file: ./secrets/cloudflare-api-token

To mount a JSON file:

services:
  clearplane-core:
    environment:
      CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILES_FILE: /run/secrets/acme-dns-profiles.json
    secrets:
      - acme-dns-profiles

secrets:
  acme-dns-profiles:
    file: ./secrets/acme-dns-profiles.json

Example file content:

{"profiles":[{"name":"cloudflare-production","provider":"Cloudflare","apiToken":"replace-with-a-scoped-token","propagationSeconds":30}]}

Each JSON profile accepts name, provider, apiToken and the optional propagationSeconds (1–3600, omitted for the provider default); any other property is an error. Keep both example secret files outside source control. Numbered and JSON profiles can coexist when their names are unique.

When a numbered profile is invalid, startup reports the exact expanded variable, for example CLEARPLANE_CORE_BOOTSTRAP_ACME_DNS_PROFILE_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.