Skip to main content

Load Balancing Example

With this example configuration, you create a near production environment for ZITADEL with Docker Compose.

The stack consists of three long-running containers:

  • A Traefik reverse proxy with upstream HTTP/2 enabled, issuing a self-signed TLS certificate.
  • A secure ZITADEL container configured for a custom domain. As we terminate TLS with Traefik, we configure ZITADEL for --tlsMode external.
  • A secure CockroachDB.

The setup is tested against Docker version 20.10.17 and Docker Compose version v2.2.3

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

docker-compose.yaml
version: '3.8'
services:

  traefik:
    networks:
      - 'zitadel'
    image: "traefik:v2.10.1"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "./example-traefik.yaml:/etc/traefik/traefik.yaml"

  zitadel:
    restart: 'always'
    networks:
      - 'zitadel'
    image: 'ghcr.io/zitadel/zitadel:stable'
    command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode external'
    depends_on:
      certs:
        condition: 'service_completed_successfully'

    volumes:
      - './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-certs:/crdb-certs:ro'

  certs:
    image: 'cockroachdb/cockroach:v22.2.2'
    entrypoint: [ '/bin/bash', '-c' ]
    command: [ 'cp /certs/* /zitadel-certs/ && cockroach cert create-client --overwrite --certs-dir /zitadel-certs/ --ca-key /zitadel-certs/ca.key zitadel_user && chown 1000:1000 /zitadel-certs/*' ]
    volumes:
      - 'certs:/certs:ro'
      - 'zitadel-certs:/zitadel-certs:rw'
    depends_on:
      my-cockroach-db:
        condition: 'service_healthy'

  my-cockroach-db:
    restart: 'always'
    networks:
      - 'zitadel'
    image: 'cockroachdb/cockroach:v22.2.2'
    command: 'start-single-node --advertise-addr my-cockroach-db'
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health?ready=1"]
      interval: '10s'
      timeout: '30s'
      retries: 5
      start_period: '20s'
    ports:
      - '9090:8080'
      - '26257:26257'
    volumes:
      - 'certs:/cockroach/certs:rw'
      - 'data:/cockroach/cockroach-data:rw'

networks:
  zitadel:

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

accessLog: {}

entrypoints:
  web:
    address: ":80"

  websecure:
    address: ":443"

tls:
  stores:
    default:
      # generates self-signed certificates
      defaultCertificate:

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

http:

  middlewares:
    zitadel:
      headers:
        isDevelopment: false
        allowedHosts:
        - 'my.domain'
        customRequestHeaders:
          :authority: 'my.domain'
    redirect-to-https:
      redirectScheme:
        scheme: https
        port: 443
        permanent: true

  routers:
    # Redirect HTTP to HTTPS
    router0:
      entryPoints:
      - web
      middlewares:
      - redirect-to-https
      rule: 'HostRegexp(`my.domain`, `{subdomain:[a-z]+}.my.domain`)'
      service: zitadel
    # The actual ZITADEL router
    router1:
      entryPoints:
      - websecure
      service: zitadel
      middlewares:
      - zitadel
      rule: 'HostRegexp(`my.domain`, `{subdomain:[a-z]+}.my.domain`)'
      tls:
        domains:
          - main: "my.domain"
            sans:
              - "*.my.domain"
              - "my.domain"

  # Add the service
  services:
    zitadel:
      loadBalancer:
        servers:
          # h2c is the scheme for unencrypted HTTP/2
        - 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
Log:
  Level: 'info'

# Make ZITADEL accessible over HTTP, not HTTPS
ExternalSecure: true
ExternalDomain: my.domain
ExternalPort: 443

# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
Database:
  cockroach:
    Host: 'my-cockroach-db'
    User:
      SSL:
        Mode: 'verify-full'
        RootCert: "/crdb-certs/ca.crt"
        Cert: "/crdb-certs/client.zitadel_user.crt"
        Key: "/crdb-certs/client.zitadel_user.key"
    Admin:
      SSL:
        Mode: 'verify-full'
        RootCert: "/crdb-certs/ca.crt"
        Cert: "/crdb-certs/client.root.crt"
        Key: "/crdb-certs/client.root.key"

LogStore:
  Access:
    Stdout:
      Enabled: true
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 CockroachDB
Database:
  cockroach:
    User:
      # If the user doesn't exist already, it is created
      Username: 'zitadel_user'
    Admin:
      Username: 'root'
example-zitadel-init-steps.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
FirstInstance:
  Org:
    Name: 'My Org'
    Human:
      # use the loginname root@my-org.my.domain
      Username: 'root'
      Password: 'RootPassword1!'
# 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 characters long masterkey
# If you haven't done so already, you can generate a new one.
# For example:
export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 </dev/urandom | head -c 32)"

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

Make 127.0.0.1 available at my.domain. For example, this can be achived with an entry 127.0.1.1 my.domain in the /etc/hosts file.

Open your favorite internet browser at https://my.domain/ui/console/. You can safely proceed, if your browser warns you about the insecure self-signed TLS certificate. This is the IAM admin users login according to your configuration in the example-zitadel-init-steps.yaml:

  • username: root@my-org.my.domain
  • password: RootPassword1!

Read more about the login process.

Troubleshooting​

You can connect to cockroach like this: docker exec -it loadbalancing-example-my-cockroach-db-1 cockroach sql --host my-cockroach-db --certs-dir /cockroach/certs/ For example, to show all login names: docker exec -it loadbalancing-example-my-cockroach-db-1 cockroach sql --database zitadel --host my-cockroach-db --certs-dir /cockroach/certs/ --execute "select * from projections.login_names2"