Set up ZITADEL with Docker Compose

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

Docker compose

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

docker-compose.yaml

services:
  zitadel:
    restart: 'always'
    networks:
      - 'zitadel'
    image: 'ghcr.io/zitadel/zitadel:latest'
    command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
    environment:
      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
      ZITADEL_EXTERNALSECURE: false
    depends_on:
      db:
        condition: 'service_healthy'
    ports:
      - '8080:8080'

  db:
    restart: 'always'
    image: postgres:16-alpine
    environment:
      PGUSER: postgres
      POSTGRES_PASSWORD: postgres
    networks:
      - 'zitadel'
    healthcheck:
      test: ["CMD-SHELL", "pg_isready", "-d", "zitadel", "-U", "postgres"]
      interval: '10s'
      timeout: '30s'
      retries: 5
      start_period: '20s'

networks:
  zitadel:

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

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

Open your favorite internet browser and navigate to http://localhost:8080/ui/console. This is the default IAM admin users login:

• username: zitadel-admin@zitadel.localhost
• password: Password1!

info

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

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

VideoGuide

Docker compose with service account

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

docker-compose-sa.yaml

services:
  zitadel:
    # The user should have the permission to write to ./machinekey
    user: "${UID:-1000}"
    restart: 'always'
    networks:
      - 'zitadel'
    image: 'ghcr.io/zitadel/zitadel:latest'
    command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
    environment:
      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
      ZITADEL_EXTERNALSECURE: false
      ZITADEL_FIRSTINSTANCE_MACHINEKEYPATH: /machinekey/zitadel-admin-sa.json
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_USERNAME: zitadel-admin-sa
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINE_NAME: Admin
      ZITADEL_FIRSTINSTANCE_ORG_MACHINE_MACHINEKEY_TYPE: 1
    depends_on:
      db:
        condition: 'service_healthy'
    ports:
      - '8080:8080'
    volumes:
      - ./machinekey:/machinekey

  db:
    restart: 'always'
    image: postgres:16-alpine
    environment:
      PGUSER: postgres
      POSTGRES_PASSWORD: postgres
    networks:
      - 'zitadel'
    healthcheck:
      test: ["CMD-SHELL", "pg_isready", "-d", "zitadel", "-U", "postgres"]
      interval: '10s'
      timeout: '30s'
      retries: 5
      start_period: '20s'

networks:
  zitadel:

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

# create the machine key directory
mkdir machinekey

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

# then you can move your machine key
mv ./machinekey/zitadel-admin-sa.json $HOME/zitadel-admin-sa.json

This key can be used to provision resources with for example Terraform.

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