Set up Zitadel with Docker Compose

The setup is tested against Docker version 28.3.2 and Docker Compose version v2.38.2

Docker compose

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

docker-compose.yaml

services:
  zitadel:
    restart: unless-stopped
    image: ghcr.io/zitadel/zitadel:latest
    command: start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled
    environment:
      ZITADEL_EXTERNALSECURE: false
      ZITADEL_TLS_ENABLED: false
      ZITADEL_DATABASE_POSTGRES_HOST: db
      ZITADEL_DATABASE_POSTGRES_PORT: 5432
      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_SSL_MODE: disable
      ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: postgres
      ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: postgres
      ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
      # By configuring a login client, the setup job creates a user of type machine with the role IAM_LOGIN_CLIENT.
      # It writes a PAT to the path specified in ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH.
      # The PAT is passed to the login container via the environment variable ZITADEL_SERVICE_USER_TOKEN_FILE.
      ZITADEL_FIRSTINSTANCE_LOGINCLIENTPATPATH: /current-dir/login-client.pat
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_USERNAME: login-client
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_MACHINE_NAME: Automatically Initialized IAM_LOGIN_CLIENT
      ZITADEL_FIRSTINSTANCE_ORG_LOGINCLIENT_PAT_EXPIRATIONDATE: '2029-01-01T00:00:00Z'
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: true
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI: http://localhost:3000/ui/v2/login
      ZITADEL_OIDC_DEFAULTLOGINURLV2: http://localhost:3000/ui/v2/login/login?authRequest=
      ZITADEL_OIDC_DEFAULTLOGOUTURLV2: http://localhost:3000/ui/v2/login/logout?post_logout_redirect=
      ZITADEL_SAML_DEFAULTLOGINURLV2: http://localhost:3000/ui/v2/login/login?samlRequest=
      # By configuring a machine, the setup job creates a user of type machine with the role IAM_OWNER.
      # It writes a personal access token (PAT) to the path specified in ZITADEL_FIRSTINSTANCE_PATPATH.
      # The PAT can be used to provision resources with [Terraform](/docs/guides/manage/terraform-provider), for example.
      ZITADEL_FIRSTINSTANCE_PATPATH: /current-dir/admin.pat
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME: admin
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME: Automatically Initialized IAM_OWNER
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE: 1

    healthcheck:
      test:
      - CMD
      - /app/zitadel
      - ready
      interval: 10s
      timeout: 60s
      retries: 5
      start_period: 10s
    volumes:
      - .:/current-dir:delegated
    ports:
      - 8080:8080
      - 3000:3000
    networks:
      - zitadel
    depends_on:
      db:
        condition: service_healthy

  login:
    restart: unless-stopped
    image: ghcr.io/zitadel/zitadel-login:latest
    # If you can't use the network_mode service:zitadel, you can pass the environment variable CUSTOM_REQUEST_HEADERS=Host:localhost instead.
    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}"
    network_mode: service:zitadel
    volumes:
      - .:/current-dir:ro
    depends_on:
      zitadel:
        condition: service_healthy
        restart: false

  db:
    restart: unless-stopped
    image: postgres:17-alpine
    environment:
      PGUSER: postgres
      POSTGRES_PASSWORD: postgres
    healthcheck:
      test: 
      - CMD-SHELL
      - pg_isready
      - -d
      - zitadel
      - -U
      - postgres
      interval: 10s
      timeout: 30s
      retries: 5
      start_period: 20s
    networks:
      - zitadel

networks:
  zitadel:

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

# Make sure you have the latest image versions
docker compose pull

# Run the PostgreSQL database, the Zitadel API and the Zitadel login.
docker compose up

Open your favorite internet browser and navigate to http://localhost:8080/ui/console?login_hint=zitadel-admin@zitadel.localhost. Enther the password Password1! to log in.

info

In the above login hint in the URL, replace localhost with your configured external domain, if any. e.g. with zitadel-admin@zitadel.sso.my.domain.tld

info

If you ran these commands for an existing instance that still uses the login v1, create a login client for it to the now running v2 login. Move the login client PAT to ./login-client.pat and restart the login container.

docker compose restart login

Now, enable the Login UI for all users

note

This guide is based on a local setup. If you encounter an error "Instance Not Found" please read the following section: Instance not found

What's next

For running a production grade ZITADEL instance in your environment, go on with the configure ZITADEL section.

caution

The ZITADEL management console requires end-to-end HTTP/2 support

Disclaimer

This guide is for development / demonstration purpose only and does NOT reflect a production setup.

Things such as TLS termination and email verification will not be available unless you

• Use an API gateway with valid certificates in front of the service
• Configure an appropriate email server