Skip to main content

A Zitadel Load Balancing Example

The stack consists of four long-running containers and a couple of short-lived containers:

  • A Traefik reverse proxy container with upstream HTTP/2 enabled, issuing a self-signed TLS certificate.
  • A Login container that is accessible via Traefik at /ui/v2/login
  • A Zitadel container that is accessible via Traefik at all other paths than /ui/v2/login.
  • An insecure PostgreSQL.

The Traefik container and the login container call the Zitadel container via the internal Docker network at h2c://zitadel:8080

The setup is tested against Docker version 28.0.4 and Docker Compose version v2.34.0

By executing the commands below, you will download the following files:

docker-compose.yaml
services:

  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=root
      - POSTGRES_PASSWORD=postgres
    networks:
      - 'storage'
    healthcheck:
      test: ["CMD-SHELL", "pg_isready", "-d", "db_prod"]
      interval: 10s
      timeout: 60s
      retries: 5
      start_period: 10s
    volumes:
      - 'data:/var/lib/postgresql/data:rw'

  zitadel-init:
    restart: 'no'
    networks:
      - 'storage'
    image: 'ghcr.io/zitadel/zitadel:latest'
    command: 'init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml'
    depends_on:
      db:
        condition: 'service_healthy'
    volumes:
      - './example-zitadel-config.yaml:/example-zitadel-config.yaml:ro'
      - './example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro'

  zitadel-setup:
    restart: 'no'
    networks:
      - 'storage'
    # We use the debug image so we have the environment to
    # - create the .env file for the login to authenticate at Zitadel
    # - set the correct permissions for the .env-file folder
    image: 'ghcr.io/zitadel/zitadel:latest-debug'
    user: root
    entrypoint: '/bin/sh'
    command:
    - -c
    - >
      /app/zitadel setup
      --config /example-zitadel-config.yaml
      --config /example-zitadel-secrets.yaml
      --steps /example-zitadel-init-steps.yaml
      --masterkey ${ZITADEL_MASTERKEY} &&
      mv /pat /.env-file/pat || exit 0 &&
      echo ZITADEL_SERVICE_USER_TOKEN=$(cat /.env-file/pat) > /.env-file/.env &&
      chown -R 1001:${GID} /.env-file &&
      chmod -R 770 /.env-file
    environment:
      - GID
    depends_on:
      zitadel-init:
        condition: 'service_completed_successfully'
        restart: false
    volumes:
      - './.env-file:/.env-file:rw'
      - './example-zitadel-config.yaml:/example-zitadel-config.yaml:ro'
      - './example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro'
      - './example-zitadel-init-steps.yaml:/example-zitadel-init-steps.yaml:ro'

  zitadel:
    restart: 'unless-stopped'
    networks:
      - 'backend'
      - 'storage'
    image: 'ghcr.io/zitadel/zitadel:latest'
    command: >
      start --config /example-zitadel-config.yaml
      --config /example-zitadel-secrets.yaml
      --masterkey ${ZITADEL_MASTERKEY}
    depends_on:
      zitadel-setup:
        condition: 'service_completed_successfully'
        restart: true
    volumes:
      - './example-zitadel-config.yaml:/example-zitadel-config.yaml:ro'
      - './example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro'
    ports:
      - "8080:8080"
    healthcheck:
      test: [
        "CMD", "/app/zitadel", "ready",
        "--config", "/example-zitadel-config.yaml",
        "--config", "/example-zitadel-secrets.yaml"
      ]
      interval: 10s
      timeout: 60s
      retries: 5
      start_period: 10s

  # The use-new-login service configures Zitadel to use the new login v2 for all applications.
  # It also gives the setupped machine user the necessary IAM_LOGIN_CLIENT role.
  use-new-login:
    restart: 'on-failure'
    user: "1001"
    networks:
      - 'backend'
    image: 'badouralix/curl-jq:alpine'
    entrypoint: '/bin/sh'
    command:
      - -c
      - >
        curl -X PUT -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/v2/features/instance -d '{"loginV2": {"required": true}}' &&
        LOGIN_USER=$(curl --fail-with-body  -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/auth/v1/users/me | jq -r '.user.id') &&
        curl -X PUT  -H "Host: 127.0.0.1.sslip.io" -H "Authorization: Bearer $(cat ./.env-file/pat)" --insecure http://zitadel:8080/admin/v1/members/$${LOGIN_USER} -d '{"roles": ["IAM_OWNER", "IAM_LOGIN_CLIENT"]}'
    volumes:
      - './.env-file:/.env-file:ro'
    depends_on:
      zitadel:
        condition: 'service_healthy'
        restart: false

  login:
    restart: 'unless-stopped'
    networks:
      - 'backend'
    image: 'ghcr.io/zitadel/login:main'
    environment:
      - ZITADEL_API_URL=http://zitadel:8080
      - CUSTOM_REQUEST_HEADERS=Host:127.0.0.1.sslip.io
      - NEXT_PUBLIC_BASE_PATH="/ui/v2/login"
    user: "${UID:-1000}"
    volumes:
      - './.env-file:/.env-file:ro'
    depends_on:
      zitadel:
        condition: 'service_healthy'
        restart: false

  traefik:
    restart: 'unless-stopped'
    networks:
      - 'backend'
    image: "traefik:latest"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./example-traefik.yaml:/etc/traefik/traefik.yaml"
    depends_on:
      zitadel:
        condition: 'service_healthy'
      login:
        condition: 'service_started'

networks:
  storage:
  backend:

volumes:
  data:
example-traefik.yaml
log:
  level: DEBUG

accessLog: {}

entrypoints:
  websecure:
    address: ":443"

providers:
  file:
    filename: /etc/traefik/traefik.yaml

http:
  routers:
    login:
      entryPoints:
        - websecure
      service: login
      rule: 'Host(`127.0.0.1.sslip.io`) && PathPrefix(`/ui/v2/login`)'
      tls: {}
    zitadel:
      entryPoints:
      - websecure
      service: zitadel
      rule: 'Host(`127.0.0.1.sslip.io`) && !PathPrefix(`/ui/v2/login`)'
      tls: {}

  services:
    login:
      loadBalancer:
        servers:
          - url: http://login:3000
        passHostHeader: true
    zitadel:
      loadBalancer:
        servers:
        - url: h2c://zitadel:8080
        passHostHeader: true

example-zitadel-config.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml

ExternalSecure: true
ExternalDomain: 127.0.0.1.sslip.io
ExternalPort: 443

# Traefik terminates TLS. Inside the Docker network, we use plain text.
TLS.Enabled: false

# If not using the docker compose example, adjust these values for connecting ZITADEL to your PostgreSQL
Database:
  postgres:
    Host: 'db'
    Port: 5432
    Database: zitadel
    User.SSL.Mode: 'disable'
    Admin.SSL.Mode: 'disable'

# By default, ZITADEL should redirect to /ui/v2/login
OIDC:
  DefaultLoginURLV2: "/ui/v2/login/login?authRequest=" # ZITADEL_OIDC_DEFAULTLOGINURLV2
  DefaultLogoutURLV2: "/ui/v2/login/logout?post_logout_redirect=" # ZITADEL_OIDC_DEFAULTLOGOUTURLV2
SAML.DefaultLoginURLV2: "/ui/v2/login/login?authRequest=" # ZITADEL_SAML_DEFAULTLOGINURLV2

# Access logs allow us to debug Network issues
LogStore.Access.Stdout.Enabled: true

# Skipping the MFA init step allows us to immediately authenticate at the console
DefaultInstance.LoginPolicy.MfaInitSkipLifetime: "0s"
example-zitadel-secrets.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml

# If not using the docker compose example, adjust these values for connecting ZITADEL to your PostgreSQL
Database:
  postgres:
    User:
      # If the user doesn't exist already, it is created
      Username: 'zitadel_user'
      Password: 'zitadel'
    Admin:
      Username: 'root'
      Password: 'postgres'
example-zitadel-init-steps.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
FirstInstance:
  PatPath: '/pat'
  Org:
    # We want to authenticate immediately at the console without changing the password
    Human:
      PasswordChangeRequired: false
    Machine:
      Machine:
        Username: 'login-container'
        Name: 'Login Container'
      Pat.ExpirationDate: '2029-01-01T00:00:00Z'
# Download the docker compose example configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/loadbalancing-example/docker-compose.yaml

# Download the Traefik example configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/loadbalancing-example/example-traefik.yaml

# Download and adjust the example configuration file containing standard configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-config.yaml

# Download and adjust the example configuration file containing secret configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-secrets.yaml

# Download and adjust the example configuration file containing database initialization configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/loadbalancing-example/example-zitadel-init-steps.yaml

# A single ZITADEL instance always needs the same 32 bytes long masterkey
# Generate one to a file if you haven't done so already and pass it as environment variable
LC_ALL=C tr -dc '[:graph:]' </dev/urandom | head -c 32 > ./zitadel-masterkey
export ZITADEL_MASTERKEY="$(cat ./zitadel-masterkey)"

# Run the database and application containers
docker compose up --detach --wait

Open your favorite internet browser at https://127.0.0.1.sslip.io/ui/console?login_hint=zitadel-admin@zitadel.127.0.0.1.sslip.io. Your browser warns you about the insecure self-signed TLS certificate. As 127.0.0.1.sslip.io resolves to your localhost, you can safely proceed. Use the password Password1! to log in.

Read more about the login process.