Skip to main content

Set up Zitadel with Docker Compose

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.3.2 and Docker Compose version v2.38.2

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:v4.0.0-rc.2'
    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'
    image: 'ghcr.io/zitadel/zitadel:v4.0.0-rc.2'
    command: [ setup, --config, /current-dir/example-zitadel-config.yaml, --config, /current-dir/example-zitadel-secrets.yaml, --steps, /current-dir/example-zitadel-init-steps.yaml, --masterkey, MasterkeyNeedsToHave32Characters ]
    depends_on:
      zitadel-init:
        condition: 'service_completed_successfully'
        restart: false
    volumes:
      - '.:/current-dir:rw'

  zitadel:
    restart: 'unless-stopped'
    networks:
      - 'backend'
      - 'storage'
    labels:
      - "traefik.http.routers.zitadel.rule=!PathPrefix(`/ui/v2/login`)"
      - "traefik.http.routers.zitadel.tls=true" # Traefik uses a self-signed certificate
      - "traefik.http.services.zitadel.loadbalancer.passhostheader=true"
      - "traefik.http.services.zitadel.loadbalancer.server.scheme=h2c"
      - "traefik.http.services.zitadel.loadbalancer.server.port=8080"
    image: 'ghcr.io/zitadel/zitadel:v4.0.0-rc.2'
    command: [ start, --config, /example-zitadel-config.yaml, --config, /example-zitadel-secrets.yaml, --masterkey, MasterkeyNeedsToHave32Characters ]
    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'
    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

  login:
    restart: 'unless-stopped'
    labels:
      - "traefik.http.routers.login.rule=PathPrefix(`/ui/v2/login`)"
      - "traefik.http.routers.login.tls=true" # Traefik uses a self-signed certificate
      - "traefik.http.services.login.loadbalancer.passhostheader=true"
      - "traefik.http.services.login.loadbalancer.server.port=3000"
    image: 'ghcr.io/zitadel/zitadel-login:v4.0.0-rc.2'
    # If you can't use the network_mode service:zitadel, you can pass the environment variable CUSTOM_REQUEST_HEADERS=Host:localhost instead.
    network_mode: service:zitadel
    environment:
      - ZITADEL_API_URL=http://localhost:8080
      - NEXT_PUBLIC_BASE_PATH=/ui/v2/login
      - ZITADEL_SERVICE_USER_TOKEN_FILE=/current-dir/login-client-pat
    user: "${UID:-1000}"
    volumes:
      - '.:/current-dir:ro'
    depends_on:
      zitadel-setup:
        condition: 'service_completed_successfully'
        restart: false

  traefik:
    image: traefik:latest
    command: --providers.docker --api.insecure=true --entrypoints.websecure.address=:443 --log.level=DEBUG --accesslog
    networks:
      - 'backend'
    ports:
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      zitadel:
        condition: 'service_healthy'
      login:
        condition: 'service_started'

networks:
  storage:
  backend:


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

ExternalSecure: true
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'

# 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:
  LoginClientPatPath: '/current-dir/login-client-pat'
  Org:
    # We want to authenticate immediately at the console without changing the password
    Human.PasswordChangeRequired: false
    LoginClient:
      Machine:
        Username: 'login-client'
        Name: 'Automatically Initialized IAM Login Client'
      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/docker-compose.yaml

# Download and adjust the example configuration file containing standard configuration.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/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/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/example-zitadel-init-steps.yaml

# Make sure you have the latest version of the images
docker compose pull

# Run the containers
docker compose up

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

Read more about the login process.