Skip to main content

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
version: '3.8'

services:
zitadel:
restart: 'always'
networks:
- 'zitadel'
image: 'ghcr.io/zitadel/zitadel:latest'
command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
environment:
- 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
- 'ZITADEL_EXTERNALSECURE=false'
depends_on:
crdb:
condition: 'service_healthy'
ports:
- '8080:8080'

crdb:
restart: 'always'
networks:
- 'zitadel'
image: 'cockroachdb/cockroach:v22.2.2'
command: 'start-single-node --insecure'
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'

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

VideoGuide

Docker compose with service account

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

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

services:
zitadel:
restart: 'always'
networks:
- 'zitadel'
image: 'ghcr.io/zitadel/zitadel:stable'
command: 'start-from-init --masterkey "MasterkeyNeedsToHave32Characters" --tlsMode disabled'
environment:
- 'ZITADEL_DATABASE_COCKROACH_HOST=crdb'
- '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:
crdb:
condition: 'service_healthy'
ports:
- '8080:8080'
volumes:
- ./machinekey:/machinekey

crdb:
restart: 'always'
networks:
- 'zitadel'
image: 'cockroachdb/cockroach:v22.2.2'
command: 'start-single-node --insecure'
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'

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

# 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