Configuration Reference

Everything is set through environment variables. CCD reads them once at start, so restart the container after a change. A missing or invalid value stops CCD at start, and the log names each setting at fault.

Basics

Setting	Required	Meaning
CCD_PUBLIC_URL	yes	The address your users type into the browser, for example https://ccd.example.com. It builds the single sign-on redirect URI, so it must match what your provider allows, and the per-cluster hosts that Open full UI uses (see First Steps). Use https:// in production.
CCD_SECRET_KEY	yes	32 random bytes that encrypt stored cluster credentials and the links that open a cluster's own interface. Generate with openssl rand -hex 32; CCD refuses to start with a key shorter than 32 characters. Back it up: without it CCD cannot read its stored clusters, and the only way back is an empty data volume and adding every cluster again.
PORT	no	Port inside the container, default 8234. Change the port mapping too if you change this.
CCD_DB	no	SQLite database URL. Default sqlite:///data/ccd.db, which uses the mounted volume.
CCD_DEMO_CLUSTER	no	on by default: on the first start without any cluster, registers four demo clusters once. Set to off before the first start to skip them. Once registered, they stay until you delete them in the interface, and deleting them is permanent.
CCD_LOG_LEVEL	no	debug, info (default), warn or error.
CCD_LOG_FORMAT	no	text (default) or json, for a log collector that parses lines.

Single sign-on

Setting	Required	Meaning
OIDC_DISCOVERY_URL	yes	Your provider's discovery document, usually ending in /.well-known/openid-configuration.
OIDC_CLIENT_ID	yes	The client id issued for CCD.
OIDC_CLIENT_SECRET	yes	The matching client secret.
OIDC_ROLE_MAPPING	no	Maps a group to a CCD role, as JSON, for example {"storage-admins":"admin","noc":"viewer"}. Roles are admin and viewer. Empty by default, so every user gets OIDC_DEFAULT_ROLES.
OIDC_DEFAULT_ROLES	no	Roles for a user whose groups match nothing. Default ["viewer"].
OIDC_GROUPS_CLAIM	no	Which claim carries the group names, default groups.
OIDC_SCOPES	no	Requested scopes, default openid email profile.
OIDC_CLIENT_AUTH	no	basic (default) or post. Change only if your provider requires it.

Single Sign-On walks through filling these in, with authentik as the worked example.

Everything together

A complete docker-compose.yml with every setting in place. Copy it, replace the five values marked CHANGE ME, and delete the optional lines you do not need:

services:
  ccd:
    image: oci.croit.io/croit/ccd:latest
    restart: unless-stopped
    ports:
      # host:container. Change the host side if 8234 is taken; put CCD behind
      # your own reverse proxy for TLS.
      - "8234:8234"
    volumes:
      # Cluster list, capacity history, audit trail and settings. Back this up.
      - ccd-data:/data
    environment:
      # ---- required ----------------------------------------------------------
      # The address your users open. Must match the redirect URI you registered.
      CCD_PUBLIC_URL: https://ccd.example.com          # CHANGE ME
      # openssl rand -hex 32 -- back this up, see the note below.
      CCD_SECRET_KEY: change-me-to-the-output-of-openssl-rand-hex-32  # CHANGE ME

      OIDC_DISCOVERY_URL: https://id.example.com/application/o/ccd/.well-known/openid-configuration  # CHANGE ME
      OIDC_CLIENT_ID: ccd                              # CHANGE ME
      OIDC_CLIENT_SECRET: change-me                    # CHANGE ME

      # ---- optional ------------------------------------------------------------
      # Which of your groups may change things. Empty by default, so everyone is
      # read-only; the group names here are examples.
      OIDC_ROLE_MAPPING: '{"storage-admins":"admin","noc":"viewer"}'

      # ---- optional, shown with their defaults -------------------------------
      OIDC_DEFAULT_ROLES: '["viewer"]'
      OIDC_GROUPS_CLAIM: groups
      OIDC_SCOPES: openid email profile
      OIDC_CLIENT_AUTH: basic

      PORT: 8234
      CCD_DB: sqlite:///data/ccd.db
      # Set to off to start without the four built-in demo clusters.
      CCD_DEMO_CLUSTER: "on"
      CCD_LOG_LEVEL: info
      CCD_LOG_FORMAT: text

volumes:
  ccd-data:

Note the quoting: OIDC_ROLE_MAPPING, OIDC_DEFAULT_ROLES and CCD_DEMO_CLUSTER need single or double quotes in YAML, because {, [ and a bare on mean something else there.

Prefer to keep secrets out of the compose file? Replace the whole environment: block with env_file: ccd.env and put the same KEY=value lines in that file, without quotes.