Complete configuration catalog

This reference is generated from Clearplane's validated configuration catalog. Each directive lists its supported sources, defaults, validation, apply behavior, and UI location.

Resolution and ownership

Runtime values resolve independently per setting in this order: environment variable → validated Clearplane container label → saved UI value → built-in default.

Environment variables carry bootstrap settings and secrets only. Every other runtime setting uses its documented container label or the UI; a label makes the matching UI field read-only until the label is removed. The MaxMind license key is the one runtime setting that also accepts an environment variable, because it is a secret.

Secret environment settings also accept the listed _FILE twin, which is read from a file mounted into the container; setting both forms is an error. Bootstrap settings are read once at process start, so every bootstrap change needs a restart, and an invalid bootstrap value stops the process with a message naming the variable. Container-discovered resources are read only from Docker labels; Clearplane never reads the labeled container's environment variables.

• Bootstrap: environment-only and applied at process startup.
• Runtime: may be changed through its documented sources and reports the effective source.
• Service resource: label-only configuration attached to a discovered proxy route or standalone redirect container.
• Immediate: consumed without an explicit Edge apply. Validated: accepted only after validation succeeds. Staged: saved until Edge configuration is applied. Restart required: effective after the owning process restarts.

Label values

• Names are the API field names in kebab-case. Related fields share dotted groups such as brotli.* or waf.challenge.*. Boolean subfeatures use <group>.enabled, such as brotli.enabled or waf.websocket.enabled. Proxy policy families use their root label with Inherit, On or Off; they do not have an .enabled label. Units end the name: -seconds, -minutes, -bytes, -megabytes.
• Enumerations are written like the REST API and the UI, for example On, Prevention or MemoryOnly. Matching ignores case; numeric backing values are not accepted. Fields documented with literal numeric choices, such as redirect status codes, accept those listed numbers instead.
• Booleans are true or false, ignoring case.
• Lists are whitespace-delimited. YAML's folded form works because line breaks become spaces.
• Invalid owner-runtime values under clearplane.core.*, clearplane.edge.*, clearplane.ui.* or clearplane.container-proxy.* are reported as warnings. The setting retains its previous valid label value; when none exists, the invalid label supplies no value and normal source resolution applies. Invalid service-resource values reject the discovered container and keep its previous route.
• Unknown owner-runtime keys under those prefixes are reported as warnings and ignored. An unknown key does not preserve the override from a known runtime label it replaced; normal label-removal fallback still applies. Unknown service-resource keys reject the discovered container, except under clearplane.proxy.cache.* (but not cache.key.*), compression.*, error-page.*, group.*, redirect.* and clearplane.redirect.group.*. Those families cannot weaken protection, so an unknown key there is also reported as a warning and ignored.

Each semantic collection uses indexed structured labels shaped as <semantic-collection>.<index>.<field>. Indices are one-based, may contain gaps, and are ordered numerically. Every indexed item must include its required fields; malformed, incomplete, duplicate, unknown, or out-of-range entries are rejected.

Every proxy policy family has the same envelope. The root label clearplane.proxy.<family> is Inherit (the default, which applies the family's enabled Global policies), On (the route's own policies, which replace the Global ones) or Off (no policy, even when a Global policy exists). Other family labels require the root label and reject the container without it; under Inherit or Off they are kept without validation. With On, clearplane.proxy.<family>.policy selects existing policies by system name; otherwise the family's labels create an inline route-scoped policy and every omitted field takes its documented default. Named and inline fields cannot be combined. Authentication has no defaults to fall back on, so an inline authentication policy needs type and its credentials or keys.

Core directives

Edge directives

UI directives

ContainerProxy directives

Proxy directives

Redirect directives

Compose-only and framework settings

These values are outside Clearplane's typed application catalog because Docker Compose or ASP.NET Core consumes them before Clearplane configuration binding. Set Compose inputs in the invoking shell, a sibling .env file, or a file passed with --env-file.

Clearplane UI and API proxy routes

Core and UI are ordinary discovered services. The shipped Compose file gives both containers one YAML anchor, x-clearplane-management-labels, with ordinary route policy labels: access control that blocks every address except CLEARPLANE_MANAGEMENT_ALLOW_ADDRESSES, a 600-request rate limit, automatic bans, request and response headers with the management Content-Security-Policy, the WAF in Detection with the Management profile, branded 403/502/503/504 error pages, and caching off. Each route owns its inline policies, placed in the System resource group.

The routes ship disabled. A deployment override enables them and supplies the public host:

services:
  clearplane-core:
    labels:
      clearplane.proxy.enabled: "true"
      clearplane.proxy.host: "waf.example.com"
  clearplane-ui:
    labels:
      clearplane.proxy.enabled: "true"
      clearplane.proxy.host: "waf.example.com"

Change any management policy by overriding its label on both containers; these are secure defaults, not immutable behavior.

Examples

Core configuration

Runtime Core settings use validated labels on the Core container or the UI. The MaxMind license key is the only runtime setting that also accepts an environment variable and _FILE twin:

CLEARPLANE_CORE_GEO_IP_LICENSE_KEY=replace-with-your-key

The non-secret MaxMind settings can be labels on the Core container:

services:
  clearplane-core:
    labels:
      clearplane.core.geo-ip.enabled: "true"
      clearplane.core.geo-ip.provider: "MaxMind"

Edge configuration

Edge bootstrap settings are environment-only. Runtime Edge settings use validated labels on the Edge container or the UI:

CLEARPLANE_EDGE_BOOTSTRAP_CORE_URI=https://clearplane-core:8443

services:
  clearplane-edge:
    labels:
      clearplane.edge.connections.maximum-per-ip: "100"

HTTP/1.1, HTTP/2, and HTTP/3 default to enabled on public HTTPS, with HTTP/3 available when QUIC is supported. Select any nonempty combination through System / Settings / Edge, or set it with labels on the Edge container, which lock the UI fields. This example disables HTTP/1.1 on HTTPS while allowing HTTP/2 and HTTP/3. The plain HTTP listener retains HTTP/1.1 for redirects, ACME, and health checks. Changes require an Edge restart; HTTP/3 also requires UDP port 443. HTTP/3 alone requires a QUIC-capable runtime and clients that can discover or directly request it, because the usual HTTP/1.1 or HTTP/2 discovery response is unavailable.

services:
  clearplane-edge:
    labels:
      clearplane.edge.http1.enabled: "false"
      clearplane.edge.http2.enabled: "true"
      clearplane.edge.http3.enabled: "true"

Upstream destination restrictions are opt-in. This label blocks selected address classes globally while preserving Docker's ordinary private-network upstreams:

services:
  clearplane-edge:
    labels:
      clearplane.edge.upstream.restricted-destination-classes: "Loopback LinkLocal CloudMetadata ControlPlaneNetwork"

A proxy policy family takes effect on a route only with its root label set to On. Set policy to the SystemName of an existing policy (lowercase ASCII letters, digits, and single internal dashes); the multi-policy families accept a space-separated list. Without policy, the family creates an inline policy. Set the root label to Off to opt the route out of a Global policy while retaining the family's other labels. Generated names use clearplane.proxy.name (or the discovery key) plus the family suffix:

services:
  app:
    labels:
      clearplane.proxy.response-headers: "On"
      clearplane.proxy.response-headers.policy: "shared-security-headers"
      clearplane.proxy.cors: "Off"
  api:
    labels:
      clearplane.proxy.name: "api"
      clearplane.proxy.response-headers: "On"
      clearplane.proxy.response-headers.content-security-policy: "default-src 'self'"

UI configuration

UI settings are bootstrap settings and are supplied to the UI container as environment variables:

CLEARPLANE_UI_BOOTSTRAP_LOGS_PATH=/app/logs

ContainerProxy configuration

ContainerProxy settings are bootstrap settings and are supplied to the ContainerProxy container as environment variables:

CLEARPLANE_CONTAINER_PROXY_BOOTSTRAP_SOCKET_PATH=/var/run/docker.sock

Standalone external redirect

A container can declare a redirect without publishing an upstream port or joining the proxy network. Set clearplane.redirect.certificate.enabled to request a certificate whose domain defaults to the source host. Additional source hosts become certificate identifiers. A container must not enable both clearplane.proxy.enabled and clearplane.redirect.enabled.

services:
  drive-redirect:
    image: alpine:latest
    command: ["sleep", "infinity"]
    labels:
      clearplane.redirect.enabled: "true"
      clearplane.redirect.name: "sharepoint-drive"
      clearplane.redirect.source-host: "drive.example.com"
      clearplane.redirect.certificate.enabled: "true"
      clearplane.redirect.target-uri: "https://target.example.com"
      clearplane.redirect.status-code: "308"

Inline access control

With clearplane.proxy.access-control: "On" and no policy, the access-control labels create an inline policy. Country codes are normalized to uppercase. default-action: Block blocks everything the allow-lists do not name, so this example permits only the listed address and countries:

services:
  app:
    image: example/app
    labels:
      clearplane.proxy.enabled: "true"
      clearplane.proxy.name: "sample-app"
      clearplane.proxy.host: "app.example.com"
      clearplane.proxy.port: "8080"
      clearplane.proxy.access-control: "On"
      clearplane.proxy.access-control.default-action: "Block"
      clearplane.proxy.access-control.allow-addresses: "203.0.113.10"
      clearplane.proxy.access-control.allow-countries: "NL CW"

Whitespace lists may also use YAML's folded form. Line breaks become spaces, so this is equivalent to one quoted whitespace-delimited value:

services:
  app:
    labels:
      clearplane.proxy.access-control: "On"
      clearplane.proxy.access-control.allow-countries: >-
        NL
        CW
      clearplane.proxy.cache: "On"
      clearplane.proxy.cache.key.headers: >-
        Accept-Language
        X-Tenant

Inline policy labels are reconciled transactionally with the discovered route. The container owns its inline policies: their labelled settings are read-only in the API and UI, and discovery recreates a deleted inline policy on its next pass. Invalid labels leave the last accepted configuration in place. Set the family's policy label instead of inline fields to reference an existing policy.

Inline Basic authentication

Basic authentication uses complete indexed credential entries. Password label values are hashed before persistence and never rendered by APIs, diagnostics, logs, or this reference:

services:
  app:
    labels:
      clearplane.proxy.authentication: "On"
      clearplane.proxy.authentication.type: "Basic"
      clearplane.proxy.authentication.key-location: "Edge"
      clearplane.proxy.authentication.basic.realm: "Restricted"
      clearplane.proxy.authentication.basic.credentials.1.username: "alice"
      clearplane.proxy.authentication.basic.credentials.1.password: "replace-with-a-password"

Inline JWT bearer authentication

JWT signing-key material is always treated as secret metadata. Symmetric material is encrypted before persistence; RSA and EC public keys use PEM block values:

services:
  api:
    labels:
      clearplane.proxy.authentication: "On"
      clearplane.proxy.authentication.type: "JwtBearer"
      clearplane.proxy.authentication.jwt.issuer: "https://identity.example.com"
      clearplane.proxy.authentication.jwt.audiences: "clearplane-api account-api"
      clearplane.proxy.authentication.jwt.signing-keys.1.kind: "Symmetric"
      clearplane.proxy.authentication.jwt.signing-keys.1.material: "a-secret-signing-key-at-least-32-characters"
      clearplane.proxy.authentication.jwt.required-claims.1.claim: "scope"
      clearplane.proxy.authentication.jwt.required-claims.1.value: "clearplane.read"

The shipped bootstrap environment values live under each service's environment: block in docker-compose.yml. Deployment overrides belong in docker-compose.override.yml. Runtime settings use validated labels or the UI; only documented secret runtime settings have environment-variable twins. Container-resource labels are label-only.