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.

Received the Celum Appliance OVA? It already includes Celum, a registry, an identity provider and a secret store in one VM. Follow Deploy the appliance instead of this page.

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. 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
      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}
    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.

3. 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 opens the first supervisor you can access, at /s/{supervisor}/. While no supervisor is registered you land on /welcome, which sends you to Settings → Kubeconfigs. If supervisors exist but IAM grants you none of them, 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:celum:admin — assign that claim to yourself, or edit the group to match a claim you already have. See Authentication & IAM.

4. Register your first supervisor

Celum reads no kubeconfig files. A supervisor is a kubeconfig registered in the dashboard and kept in the database. After you sign in, Celum opens on Welcome to Celum: drop the kubeconfig there, or upload it under Settings → Kubeconfigs. Register a supervisor walks through it.

Welcome to Celum: no supervisor selected, a choice between Upload a kubeconfig and Set up access first, and an Add your first supervisor drop zone — The first page while no supervisor is registered

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 kubeconfig is registered yet. Register one under Settings → Kubeconfigs.

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

Administration

Prerequisites

Docker + Compose

Registry access

OIDC application

TLS + DNS

1. Configure environment

2. Define the stack

3. Start the stack

What happens on first load

4. Register your first supervisor

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. Define the stack

​3. Start the stack

​What happens on first load

​4. Register your first supervisor

​What commonly goes wrong

​Next steps

Authentication & IAM

Supervisors & clusters

Create a cluster

Environment variables

Prerequisites

1. Configure environment

2. Define the stack

3. Start the stack

What happens on first load

4. Register your first supervisor

What commonly goes wrong

Next steps