Quickstart

Celum ships as two container images — the dashboard (app) and the API (backend) — alongside a PostgreSQL database. This guide deploys all three with Docker Compose and connects your first supervisor.

Prerequisites

Docker + Compose

A host with Docker Engine and the Compose plugin.

Registry access

Credentials for the registry that hosts the Celum images.

OIDC application

A client registration with your identity provider (client ID, secret, issuer).

TLS + DNS

Two hostnames (app + API) terminating TLS at a reverse proxy.

You also need at least one kubeconfig for each Cluster API supervisor you want to manage.

Celum sets the session cookie with the Secure flag, so authentication only works over HTTPS. Run Celum behind a TLS-terminating reverse proxy and use https:// URLs throughout — plain HTTP will fail to log in.

Angle-bracket values below are placeholders — <tenant-id>, <version>, <registry>, and so on. Substitute the values for your deployment; nothing here is a working default.

1. Configure environment

Create a .env file next to your docker-compose.yml. Compose interpolates these values into the stack.

.env

# --- Public URLs (HTTPS, served by your reverse proxy) ---
FRONTEND_URL=https://app.example.com
BACKEND_PUBLIC_URL=https://api.example.com
OIDC_REDIRECT_URL=https://api.example.com/auth/callback
COOKIE_DOMAIN=example.com

# --- OIDC ---
OIDC_ISSUER=https://login.microsoftonline.com/<tenant-id>/v2.0
OIDC_CLIENT_ID=<client-id>
OIDC_CLIENT_SECRET=<client-secret>
# Which token claim maps to IAM groups: "groups" or "roles"
OIDC_GROUPS_CLAIM=groups

# --- Sessions & authorization ---
# Generate a strong random key, e.g. `openssl rand -base64 48`
SESSION_SECRET=<random-secret>
IAM_ENABLED=true

# --- Database ---
POSTGRES_PASSWORD=<db-password>

Every variable the backend reads is listed in Environment variables.

2. Add supervisor kubeconfigs

Place one kubeconfig per supervisor in a kubeconfigs/ directory next to the compose file. The filename becomes the supervisor name shown in the UI.

kubeconfigs/
  <supervisor-a>        # → supervisor "<supervisor-a>"
  <supervisor-b>        # → supervisor "<supervisor-b>"

3. Define the stack

docker-compose.yml

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: k8sgate
      POSTGRES_USER: k8sgate
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  backend:
    image: <registry>/vks-manager/backend:<version>
    depends_on:
      - db
    environment:
      PORT: "8080"
      DATABASE_URL: postgres://k8sgate:${POSTGRES_PASSWORD}@db:5432/k8sgate?sslmode=disable
      KUBECONFIGS_DIR: /app/kubeconfigs
      OIDC_ISSUER: ${OIDC_ISSUER}
      OIDC_CLIENT_ID: ${OIDC_CLIENT_ID}
      OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}
      OIDC_REDIRECT_URL: ${OIDC_REDIRECT_URL}
      OIDC_GROUPS_CLAIM: ${OIDC_GROUPS_CLAIM}
      SESSION_SECRET: ${SESSION_SECRET}
      FRONTEND_URL: ${FRONTEND_URL}
      COOKIE_DOMAIN: ${COOKIE_DOMAIN}
      IAM_ENABLED: ${IAM_ENABLED}
    volumes:
      - ./kubeconfigs:/app/kubeconfigs:ro
    restart: unless-stopped

  app:
    image: <registry>/vks-manager/app:<version>
    depends_on:
      - backend
    environment:
      BACKEND_URL: http://backend:8080
      BACKEND_PUBLIC_URL: ${BACKEND_PUBLIC_URL}
    restart: unless-stopped

volumes:
  pgdata:

Pin the image tag to the version you were provided. Route your reverse proxy so that FRONTEND_URL reaches the app service on port 3000 and BACKEND_PUBLIC_URL reaches the backend service on port 8080.

4. Start the stack

docker compose pull
docker compose up -d

The backend applies database migrations automatically on startup. Once the reverse proxy is routing both hostnames, open your dashboard URL:

https://app.example.com

What happens on first load

Unauthenticated requests are redirected to sign in through your OIDC provider. On return, the backend issues a signed session cookie.

Default supervisor

The root route resolves the first supervisor you can access and redirects to /s/{supervisor}/. If you can access none, you land on /no-access.

Grant access

With IAM_ENABLED=true, access is governed by IAM. A fresh database ships an Administrators group carrying the K8sGateAdmin policy, mapped to the OIDC claim value krn:vks:admin — assign that claim to yourself, or edit the group to match a claim you already have. See Authentication & IAM.

What commonly goes wrong

Symptom	Cause
Login loops back to the sign-in page	The stack is served over plain HTTP. The session cookie is `Secure`, so the browser never stores it.
`403` on every page after signing in	`IAM_ENABLED=true` and your OIDC claim matches no group. Nothing in IAM grants you anything, so evaluation ends in the default deny.
Everyone is logged out after a restart	`SESSION_SECRET` was left unset, so the backend generated a random one at startup and the old cookies no longer verify.
The supervisor list is empty	No file in `KUBECONFIGS_DIR` and no kubeconfig uploaded to the database.
Backend refuses to start, naming `GITLAB_TOKEN` or `GITLAB_PROJECT_ID`	`GITLAB_URL` is set, which makes both of those mandatory.

Next steps

Authentication & IAM

Configure OIDC mapping and policies in depth.

Supervisors & clusters

How Celum discovers supervisors and what it reads from them.

Create a cluster

Provision a tenant cluster from a template.

Environment variables

Every variable the backend and dashboard read.

Get Started

Concepts

Clusters

GitOps & Apps

Virtual machines

Networking

Security

Platform Health

Storage

Reference

Prerequisites

Docker + Compose

Registry access

OIDC application

TLS + DNS

1. Configure environment

2. Add supervisor kubeconfigs

3. Define the stack

4. Start the stack

What happens on first load

What commonly goes wrong

Next steps

Authentication & IAM

Supervisors & clusters

Create a cluster

Environment variables

​Prerequisites

Docker + Compose

Registry access

OIDC application

TLS + DNS

​1. Configure environment

​2. Add supervisor kubeconfigs

​3. Define the stack

​4. Start the stack

​What happens on first load

​What commonly goes wrong

​Next steps

Authentication & IAM

Supervisors & clusters

Create a cluster

Environment variables

Prerequisites

1. Configure environment

2. Add supervisor kubeconfigs

3. Define the stack

4. Start the stack

What happens on first load

What commonly goes wrong

Next steps