METADATA
=======
Title: Environment variable reference
Description: Supply Clearplane bootstrap settings and secrets through environment variables, mounted secret files, and Compose inputs.
Human URL: /docs/configuration/environment-variables/
Last Updated: 2026-09-27

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](/docs/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](/llms/configuration/environment-variables.txt), the [LLM documentation index](/llms.txt), or the [complete documentation file](/llms/llms-full.txt).

## DNS-profile secret files

An individual numbered profile can read its token from a mounted file instead of a scalar environment value:

```yaml
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:

```yaml
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:

```json
{"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.

| Environment variable | What it does |
| --- | --- |
| <code>COMPOSE_PROJECT_NAME</code> | Overrides the Compose project name, which defaults to <code>clearplane</code>. The shipped Compose file passes the effective value to Core so first-party container ownership can be verified. |
| <code>CLEARPLANE_IMAGE_TAG</code> | Overrides the image tag for all four services. This does not provide database rollback. |
| <code>CLEARPLANE_CONTAINER_PROXY_SOCKET_PATH</code> | Selects the local Unix socket bind source, mount target, and Container proxy socket setting. |
| <code>CLEARPLANE_MANAGEMENT_ALLOW_ADDRESSES</code> | Whitespace-delimited IP addresses and CIDR ranges allowed to reach the management UI and API routes. Empty blocks every address. |