Zitadel Local Setup

Setting up Zitadel , a multi-tenant, API-first identity platform offering authentication and authorization with an open source platform, can be rather opaque. The project seems to be fast moving and the documentation is not always kept up to date, which can lead to fustration during deployment. Let’s try and simplify and disambiguate some of the startup to get a lightweight local test deployment.

The recipe for the setup is as follows:

Prerequisites
1. A working Kubernetes cluster, if you need a direction you could check here
2. Helm , version 3 or 4 does not matter
3. Traefik - the ingress used by the project
4. Postgres - a basic setup would be easiest, you can leverage it as both Zitadel’s database and your own application database

Deploy both Traefik and Postgres to the cluster

Installing Traefik

helm repo add traefik https://helm.traefik.io/traefik
helm repo update traefik
helm install traefik traefik/traefik -n kube-system

Deploying Postgres, something like the following manifest would work:

apiVersion: apps/v1
kind: Deployment
metadata:
name: postgres
labels:
    app: postgres
spec:
replicas: 1
selector:
    matchLabels:
    app: postgres
template:
    metadata:
    labels:
        app: postgres
    spec:
    containers:
        - name: postgres
        image: postgres:16-alpine
        ports:
            - containerPort: 5432
        env:
            - name: POSTGRES_USER
            value: postgres
            - name: POSTGRES_PASSWORD
            value: postgres
        resources:
            requests:
            cpu: 100m
            memory: 256Mi
            limits:
            cpu: 500m
            memory: 512Mi
---
apiVersion: v1
kind: Service
metadata:
name: postgres
labels:
    app: postgres
spec:
type: LoadBalancer
selector:
    app: postgres
ports:
    - port: 5432
      targetPort: 5432

For Zitadel itself let’s just create a secret with the login and password for Postgres with k apply -f. We’ll follow up that apply with deploying the Zitadel helm chart, now that all the prequisites have been covered. Find the secret manifest and helm values below:

secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: zitadel-db-credentials
type: Opaque
stringData:
  config-yaml: |
    Database:
      Postgres:
        User:
          Password: postgres
        Admin:
          Password: postgres

zitadel-values.yaml

replicaCount: 1

zitadel:
  masterkey: "uKcgKb/A8A/T9h65YJOBfEOWHN4AJqdq5Gg+av5Cw1U=
  configSecretName: zitadel-db-credentials
  configSecretKey: config-yaml
  configmapConfig:
    ExternalDomain: localhost
    ExternalSecure: false
    ExternalPort: 8080
    TLS:
      Enabled: false
    Database:
      Postgres:
        Host: postgres
        Port: 5432
        Database: zitadel
        User:
          Username: postgres
          SSL:
            Mode: disable
        Admin:
          Username: postgres
          SSL:
            Mode: disable
    FirstInstance:
      Org:
        Human:
          UserName: admin
          FirstName: Zitadel
          LastName: Admin
          Email: admin@localhost
          Password: "Password1!"
          PasswordChangeRequired: false

ingress:
  enabled: true
  className: traefik
  hosts:
    - host: localhost
      paths:
        - path: /
          pathType: Prefix

login:
  enabled: true
  ingress:
    enabled: true
    className: traefik
    hosts:
      - host: localhost
        paths:
          - path: /ui/v2/login
            pathType: Prefix

# disable bundled postgres -- we use our own
postgres:
  enabled: false

helm repo add zitadel https://charts.zitadel.com
helm repo update zitadel
helm upgrade --install zitadel zitadel/zitadel -f <your-path>/zitadel-values.yaml --version 9.26.0

Once all this is complete we should now be able to access the zitael interface at localhost/ui/console. From there refer to the Zitadel docs for setting up your application, find a link in the references.

References

secret.yaml

zitadel-values.yaml

References

See also