Installation

CCD ships as a single Docker container. You pull it, run it, and log in, the same way you already run croit.

What you need

A host with Docker, reachable by your users, on linux/amd64. That is the only architecture CCD is published for, which covers ordinary servers. On an ARM machine, including an Apple Silicon Mac, see Running on an ARM machine below.
Network access from that host to each cluster's API. Self-signed certificates are fine and never need an exception.
An OpenID Connect identity provider: authentik, Keycloak, Entra ID, Okta, Google Workspace, whatever you already run. CCD has no passwords of its own, so this is required. Single Sign-On walks through it.
Per cluster, a read-only credential, created in that cluster's own user management:
- croit: an API token, or a user with read-only permissions.
- Ceph: a read-only dashboard user, because the Ceph API issues no long-lived tokens:
```
ceph mgr module enable dashboard
ceph dashboard ac-user-create ccd -i password-file read-only
```
  If the dashboard was not running before, it also needs a certificate: ceph dashboard create-self-signed-cert.
If your identity provider's certificate is signed by a private CA, a bundle with that CA. CCD verifies the provider's certificate and only trusts the public CAs it ships with. Mount a bundle and point SSL_CERT_FILE at it; it replaces the built-in one, so include the public CAs if you still need them.
To open a cluster's full interface through CCD in production, wildcard DNS and TLS for the CCD hostname, plus reverse-proxy routing for that wildcard. The fleet dashboard works without this, but the Open full UI link does not. First Steps has the details.

Starting the container

Generate the secret key once and keep it, because CCD needs the same key on every start:

openssl rand -hex 32 > ccd-secret-key
chmod 600 ccd-secret-key

docker run -d --name ccd -p 8234:8234 -v ccd-data:/data \
  -e CCD_PUBLIC_URL=http://localhost:8234 \
  -e CCD_SECRET_KEY="$(cat ccd-secret-key)" \
  -e OIDC_DISCOVERY_URL=https://id.example.com/application/o/ccd/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=ccd \
  -e OIDC_CLIENT_SECRET=... \
  oci.croit.io/croit/ccd:latest

CCD_PUBLIC_URL, CCD_SECRET_KEY and the three OIDC_* values are required, because CCD signs in through your own identity provider. Without them CCD does not start, and docker logs ccd names the missing setting.

CCD runs as user and group 65532. A named volume like ccd-data just works. If you mount a host directory instead, make it writable for that user first, for example chown 65532:65532 /srv/ccd.

IMPORTANT

Back up CCD_SECRET_KEY (here ccd-secret-key). It encrypts every stored cluster credential, and CCD cannot read its stored clusters without it: losing it means starting over with an empty data volume and adding every cluster again.

With Docker Compose

Save this as docker-compose.yml, put your values in ccd.env next to it, and run docker compose up -d:

services:
  ccd:
    image: oci.croit.io/croit/ccd:latest
    env_file: ccd.env
    ports:
      - "8234:8234"
    volumes:
      - ccd-data:/data
    restart: unless-stopped

volumes:
  ccd-data:

# ccd.env
CCD_PUBLIC_URL=https://ccd.example.com
CCD_SECRET_KEY=<output of: openssl rand -hex 32>

OIDC_DISCOVERY_URL=https://id.example.com/application/o/ccd/.well-known/openid-configuration
OIDC_CLIENT_ID=ccd
OIDC_CLIENT_SECRET=<from your identity provider>
OIDC_ROLE_MAPPING={"storage-admins":"admin","noc":"viewer"}

ccd.env holds secrets. Keep it readable only by the user running Docker.

Every setting CCD understands is listed in the Configuration Reference.

Running on an ARM machine

CCD is published for linux/amd64 only. On an ARM host, an Apple Silicon Mac being the usual case, Docker still pulls the image and runs it under emulation, but warns on every start:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

Ask for the amd64 image explicitly to confirm that is what you want, and the warning goes away:

docker run -d --name ccd --platform linux/amd64 -p 8234:8234 ...

In compose, add one line to the service:

services:
  ccd:
    image: oci.croit.io/croit/ccd:latest
    platform: linux/amd64

Emulation is noticeably slower, which is fine for a look around and not something to run a production installation on. Put CCD on an ordinary amd64 server for that.

On this Page:

Installation

What you need

Starting the container

With Docker Compose

Running on an ARM machine