Dibbla Docs Get started Guides Workflows Changelog
Open Console
Self-host

Self-hosting

Interactive walkthrough for installing the Dibbla platform on your own Kubernetes cluster.

This is the guided path. Make a few choices and we’ll walk you through logging into your server, bootstrapping the cluster, gathering secrets, installing the platform, wiring TLS, and the first sign-in — and generate a tailored values.yaml you can copy. For the full per-component reference, see the Self-host section.

Cluster
Auth
Data plane
TLS

Hover the ? next to each row if you’re unsure which option to pick.

0. Log into your server

You already have a Kubernetes cluster — skip to step 1. The rest of the install runs from your laptop using kubectl, not from the server itself.

1. Bring up your cluster

Make sure your cluster meets the overview prerequisites: Kubernetes 1.27+, an ingress controller (nginx or Traefik), a default StorageClass, and ideally cert-manager already installed. Then skip ahead to step 2.

Point a wildcard DNS record at your ingress

*.example.com.   IN  A   <your-ingress-ip>
example.com.     IN  A   <your-ingress-ip>

The platform routes deployed apps by Host header, so a single wildcard covers every app you’ll ever deploy.

2. Gather secrets

You’ll collect a few things before installing. Some are generated locally; one is issued by Dibbla.

  • GHCR PAT — a GitHub access token with read:packages scope that lets your cluster pull platform images from ghcr.io/dibbla-agents/*. The Dibbla team issues this to you — email [email protected] and we’ll send one. You can’t generate it yourself; the platform images are private and the PAT is scoped to a Dibbla-managed account.

Self-hosted auth additionally needs OAuth credentials and signing keys you generate yourself:

  • A Google OAuth client — register one in the Google Cloud Console (type: Web application) and capture the client ID and client secret. (Microsoft Entra also works — see the auth reference.)
  • A JWT secret and a signing key — generate each by running openssl rand -hex 32 once locally. Store them in a secret manager — rotating either invalidates every token your platform has ever issued.

The bundled Postgres needs two passwords — one for the dibbla user, one for the postgres superuser. Generate any way you like (openssl rand -base64 24 is a fine choice).

3. Your tailored values.yaml

values.yaml is the configuration file Helm reads when installing Dibbla into your cluster — it’s how you tell the chart your domain, your secrets, which ingress class to use, whether to bundle Postgres and Redis, and how to handle TLS. The block below is generated from your choices above. Copy it, replace every <your-…> placeholder with a real value, and save it as values.yaml on the machine you’ll run helm install from.

global:
  baseDomain: example.com

  imagePullSecret:
    create: true
    registry: ghcr.io
    username: <your-github-username>
    token: <your-ghcr-pat>

  postgresql:
    enabled: true
    username: dibbla
    password: <your-postgres-password>
    superuserPassword: <your-postgres-superuser-password>

  redis:
    enabled: true

  minio:
    enabled: true
    rootUser: minio
    rootPassword: <your-minio-root-password>

  loki:
    enabled: true

  alloy:
    enabled: true

auth-service:
  google:
    clientId: <your-google-client-id>
    clientSecret: <your-google-client-secret>
  # microsoft:                              # uncomment to enable Microsoft Entra
  #   clientId: <your-ms-client-id>
  #   clientSecret: <your-ms-client-secret>
  #   tenantId: <your-ms-tenant-id>
  jwt:
    secret: <your-jwt-secret>
  signingKey: <your-signing-key>
  redirectBaseUrl: https://app.example.com
  allowedRedirectBaseUrls: https://app.example.com

api-gateway:
  ingress:
    enabled: true
    type: standard
    className: nginx
    hosts:
      - host: app.example.com
      - host: api.example.com
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt
    tls:
      - secretName: dibbla-tls
        hosts:
          - app.example.com
          - api.example.com

deploy-api:
  ingressClass: nginx

workflow-server:
  rootToken: <your-workflow-root-token>
  oauthEncryptionKey: <your-oauth-encryption-key>
  googleClientId: <your-google-client-id>       # mirror auth-service
  googleClientSecret: <your-google-client-secret>
  jwtSecret: <your-jwt-secret>                  # mirror auth-service
  redirectBaseUrl: https://app.example.com

go-toolserver:
  anthropicApiKey: <your-anthropic-key>
  openaiApiKey: <your-openai-key>
  • cert-manager TLS: install cert-manager and create a `letsencrypt` ClusterIssuer (HTTP-01 or DNS-01) before installing the chart.
  • Generate every secret with `openssl rand -hex 32` (or `-base64 24` for Postgres-style passwords). Rotating JWT/signing keys signs every user out.

4. Install

helm install dibbla oci://ghcr.io/dibbla-agents/charts/dibbla \
  --namespace dibbla --create-namespace \
  -f values.yaml

After a minute:

kubectl -n dibbla get pods

You should see dibbla-api-gateway-…, dibbla-auth-service-…, dibbla-deploy-api-…, dibbla-postgresql-0, and dibbla-redis-master-0 all Running.

5. TLS

All traffic to your platform runs over HTTPS. Browsers refuse to send credentials over plain HTTP, OAuth providers require HTTPS callback URLs, and your users’ tokens, sessions, and source uploads are sensitive — TLS is what keeps them confidential in transit. You’ll either let cert-manager issue Let’s Encrypt certificates automatically, or pre-create the certificate yourself.

The chart’s ingress is annotated with cert-manager.io/cluster-issuer: letsencrypt. Create a matching ClusterIssuer and the dibbla-tls secret is provisioned and renewed automatically:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-account-key
    solvers:
      - http01:
          ingress:
            class: <your-ingress-class>

For DNS-01 (required for wildcard certs and recommended on cloud-managed clusters), see the Helm install reference.

6. First sign-in

Once the platform is running, create the first org and admin user:

curl -X POST https://api.example.com/api/v1/admin/orgs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your Org",
    "domains": ["example.com"],
    "admin_email": "[email protected]",
    "admin_name": "Your Name"
  }'

The admin signs in via OAuth at https://app.example.com and lands in the dashboard with owner permissions. Then point the CLI at your platform:

dibbla login --api-url https://api.example.com --api-key dib_…

Field semantics and the Microsoft Entra path are documented on the auth reference page.

Reference pages

When you need more detail on any of the above, the per-component reference covers it in full: