Set up Zitadel with Docker Compose

This guide is the entrypoint for running the Zitadel platform locally for the first time. It is for demonstration and development purposes only and does not set up a production-ready and security hardened instance of Zitadel. Once Zitadel up is and running, learn more about a production setup in the What's Next section.

Prerequisites

The setup is likely to work with other software versions too, but it is tested against the following environment:

Ubuntu 24.04.1
Docker 28.3.2
Docker Compose v2.38.2
curl 8.5.0

Docker compose

The following commands set up services for a PostgreSQL database, a Zitadel API and a Zitadel login:

Download the docker-compose.yaml file from the Zitadel repository:

curl -L https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/deploy/docker-compose.yaml -o docker-compose.yaml

Make sure the containers use the latest image versions.
```
docker compose pull
```
Run the PostgreSQL database, the Zitadel API, and the Zitadel login.
```
docker compose up --detach --wait
```
Verify the containers are running and healthy.
```
docker compose ps
```

Visit http://localhost:8080/ui/console?login_hint=zitadel-admin@zitadel.localhost and enter Password1! to log in.

What's next

Before proceeding, review the downloaded docker-compose.yaml file: The comments give context to the used variables and show examples for commonly used configuration variants.

docker-compose.yaml

services:
  zitadel:
    restart: unless-stopped
    image: ghcr.io/zitadel/zitadel:latest
    command: start-from-init --masterkey "MasterkeyNeedsToHave32Characters"
    environment:
      # See "What's next" to learn about how to serve Zitadel on a different domain or IP.
      ZITADEL_EXTERNALDOMAIN: localhost

      # See "What's next" to learn about how to enable TLS.
      ZITADEL_EXTERNALSECURE: false
      ZITADEL_TLS_ENABLED: false

      # Database connection settings.
      ZITADEL_DATABASE_POSTGRES_HOST: db
      ZITADEL_DATABASE_POSTGRES_PORT: 5432
      # The database is created by the init job if it does not exist.
      ZITADEL_DATABASE_POSTGRES_DATABASE: zitadel
      # The admin user must already exist in the database.
      ZITADEL_DATABASE_POSTGRES_ADMIN_USERNAME: postgres
      ZITADEL_DATABASE_POSTGRES_ADMIN_PASSWORD: postgres
      ZITADEL_DATABASE_POSTGRES_ADMIN_SSL_MODE: disable
      # The zitadel user is created by the init job if it does not exist.
      ZITADEL_DATABASE_POSTGRES_USER_USERNAME: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_PASSWORD: zitadel
      ZITADEL_DATABASE_POSTGRES_USER_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'
      # Activate the login v2 on an installation from scratch.
      # To activate the login v2 on an existing installation, read the "What's next" section.
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED: true # To use the login v1, set this to false.
      ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI: http://localhost:3000/ui/v2/login
      # Configure the redirection paths to the login v2.
      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_PAT_EXPIRATIONDATE: '2029-01-01T00:00:00Z'
      
      # To change the initial human admin users username and password, uncomment the following lines.
      # The first login name is formatted like this: <username>@<org_name>.<external_domain>
      # With the following incommented configuration, this would be root@my-organization.localhost
      # Visit http://localhost:8080/ui/console to check if the login name works.
      # If you can't log in, check the available login names:
      # echo "select * from projections.login_names3;" | psql -h localhost -U postgres -d zitadel
      # The postgres users password is postgres.
      # ZITADEL_FIRSTINSTANCE_ORG_NAME: My Organization
      # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME: root
      # ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: RootPassword1!

      # Enable debug logs
      # ZITADEL_LOG_LEVEL: debug     
      # Write Access Logs to stdout.
      # ZITADEL_LOGSTORE_ACCESS_STDOUT_ENABLED: true

    healthcheck:
      test:
        - CMD
        - /app/zitadel
        - ready
      interval: 10s
      timeout: 60s
      retries: 5
      start_period: 10s
    user: "0"
    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 variables ZITADEL_API_URL=http://zitadel:8080 and 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
    network_mode: service:zitadel
    user: "0"
    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
    ports:
      - 5432:5432
    volumes:
      - 'data:/var/lib/postgresql/data:rw'

networks:
  zitadel:

volumes:
  data:

Here are some natural steps forward to go from the current setup to production:

Use a different master key: Set up an instance from scratch and use a different master key. For example, generate one by running tr -dc A-Za-z0-9 </dev/urandom | head -c 32
Use files for secrets instead of environment variables, and don't commit them to Git: Learn how to configure the platform
Run the containers as non-root users: Remove the user: "0" lines from the docker-compose.yaml file.
Configure a different external domain or IP: Beware that the login only works with HTTPS on non-localhost domains. Run and configure a reverse proxy
Serve the API and the UI together on the same port: Run and configure a reverse proxy
Encrypt Traffic: Run and configure a reverse proxy

For more detailed recommendations, read the Zitadel Production Setup Guide.

Read this if the environment uses the login v1

The login v2 is the next generation of the Zitadel login. Its code and deployment are easily customizable. Unlike the login v1, it runs in its own process. The login v2 is enabled by default in new installations. But if an existing docker-compose.yaml file is updated by following this guide, an additional zitadel-login service is now running which is actually not doing anything, yet. The following steps give guidance on how to enable the login v2 in an environment.

Read the login v2 related comments in the docker-compose.yaml.
Manually create a login client personal access token (PAT) for the now running v2 login.
Move the PAT to ./login-client.pat
Restart the login process: docker compose restart login
Enable the Login UI for all users

Prerequisites​

Docker compose​

What's next​

Prerequisites

Docker compose

What's next