Configure ZITADEL
This guide assumes you are already familiar with running ZITADEL with the most minimal configuration possible.
Configuration Files
Runtime Configuration
See a description of all possible runtime configuration options with their defaults in the source code.
The zitadel
binary expects the --config
flag for this configuration.
Database Initialization
Apart from these options, ZITADEL uses a different configuration for database initialization steps.
The zitadel
binary expects the --steps
flag for this configuration.
Split Configuration
ZITADEL merges multiple configurations passed via multiple --config
and/or multiple --steps
flags.
This is especially useful, if you want to treat secret configuration files differently from standard configuration.
For example, you can check configuration with information like the database hostname in to git.
Other configration that contains information like your databases admin username and password, you can hand to a secret manager.
Environment variables
All configuration properties are also configurable via environemnt variables. Prefix the key with ZITADEL_, uppercase the propery and join sections by an underscore _. For example, if you want to configure the default ZITADEL IAM admin username and password, make sure the ZITADEL binary runtime has the variables ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME and ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD set.
Proxy configuration
If your organisation uses a proxy for outgoing connections, it can be configured using the environemnt variables HTTP_PROXY
for outgoint HTTP requests and HTTPS_PROXY
for outgoint HTTPS requests. The variables are used as proxy url.
If specific hosts should be excluded from proxying, the NO_PROXY
environment variable ca be used. The value is interpreted as comma separated string. More details about the variable can be found here.
Masterkey
The masterkey is used to AES256-encrypt other generated encryption keys. It needs to have 32 bytes. You can pass the masterkey in either of three possible ways to the zitadel binary:
- By value: Use the flag
--masterkey My_Master_Key_Which_Has_32_Bytes
- By environment variable
ZITADEL_MASTERKEY
: Use the flag--masterkeyFromEnv
- By file: Use the flag
--masterkeyFile /path/to/file
Passing the configuration
- Linux and Unix
- Docker Compose
- Kubernetes (Helm)
Configure by Files
By executing the commands below, you will download the following files:
example-zitadel-config.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
Log:
Level: 'info'
# Make ZITADEL accessible over HTTP, not HTTPS
ExternalSecure: false
# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
Database:
cockroach:
Host: 'my-cockroach-db'
User:
SSL:
Mode: 'verify-full'
RootCert: "/crdb-certs/ca.crt"
Cert: "/crdb-certs/client.zitadel_user.crt"
Key: "/crdb-certs/client.zitadel_user.key"
Admin:
SSL:
Mode: 'verify-full'
RootCert: "/crdb-certs/ca.crt"
Cert: "/crdb-certs/client.root.crt"
Key: "/crdb-certs/client.root.key"
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 CockroachDB
Database:
cockroach:
User:
# If the user doesn't exist already, it is created
Username: 'zitadel_user'
Admin:
Username: 'root'
example-zitadel-init-steps.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
FirstInstance:
Org:
Human:
# use the loginname root@zitadel.localhost
Username: 'root'
Password: 'RootPassword1!'
# Download and adjust the example configuration file containing standard configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/manage/production/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/manage/production/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/manage/production/example-zitadel-init-steps.yaml
# A single ZITADEL instance always needs the same 32 characters long masterkey
# If you haven't done so already, you can generate a new one
# The key must be passed as argument
ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 </dev/urandom | head -c 32)"
# Pass zitadel configuration by configuration files
zitadel start-from-init \
--config ./example-zitadel-config.yaml \
--config ./example-zitadel-secrets.yaml \
--steps ./example-zitadel-init-steps.yaml \
--masterkey "${ZITADEL_MASTERKEY}"
Configure by Environment Variables
# Set runtime environment variables
export ZITADEL_DATABASE_COCKROACH_HOST="my.database"
export ZITADEL_DATABASE_COCKROACH_USER_USERNAME="my_zitadel_db_user"
export ZITADEL_DATABASE_COCKROACH_USER_PASSWORD="Secret_DB_User_Password"
export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME="root"
export ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD="RootPassword1!"
# A single ZITADEL instance always needs the same 32 characters long masterkey
# If you haven't done so already, you can generate a new one
# The key must be passed as argument
export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 </dev/urandom | head -c 32)"
# Let the zitadel binary read configuration from environment variables
zitadel start-from-init --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled
The docker compose example mounts the example zitadel configuration files to the ZITADEL container.
By executing the commands below, you will download the following files:
docker-compose.yaml
version: "3.8"
services:
zitadel:
restart: "always"
networks:
- "zitadel"
image: "ghcr.io/zitadel/zitadel:stable"
command: 'start-from-init --config /example-zitadel-config.yaml --config /example-zitadel-secrets.yaml --steps /example-zitadel-init-steps.yaml --masterkey "${ZITADEL_MASTERKEY}" --tlsMode disabled'
depends_on:
certs:
condition: "service_completed_successfully"
ports:
- "8080:8080"
volumes:
- "./example-zitadel-config.yaml:/example-zitadel-config.yaml:ro"
- "./example-zitadel-secrets.yaml:/example-zitadel-secrets.yaml:ro"
- "./example-zitadel-init-steps.yaml:/example-zitadel-init-steps.yaml:ro"
- "zitadel-certs:/crdb-certs:ro"
certs:
image: "cockroachdb/cockroach:v22.2.2"
entrypoint: ["/bin/bash", "-c"]
command:
[
"cp /certs/* /zitadel-certs/ && cockroach cert create-client --overwrite --certs-dir /zitadel-certs/ --ca-key /zitadel-certs/ca.key zitadel_user && chown 1000:1000 /zitadel-certs/*",
]
volumes:
- "certs:/certs:ro"
- "zitadel-certs:/zitadel-certs:rw"
depends_on:
my-cockroach-db:
condition: "service_healthy"
my-cockroach-db:
restart: "always"
networks:
- "zitadel"
image: "cockroachdb/cockroach:v22.2.2"
command: "start-single-node --advertise-addr my-cockroach-db"
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"
volumes:
- "certs:/cockroach/certs:rw"
- "data:/cockroach/cockroach-data:rw"
networks:
zitadel:
volumes:
certs:
zitadel-certs:
data:
example-zitadel-config.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
Log:
Level: 'info'
# Make ZITADEL accessible over HTTP, not HTTPS
ExternalSecure: false
# If not using the docker compose example, adjust these values for connecting ZITADEL to your CockroachDB
Database:
cockroach:
Host: 'my-cockroach-db'
User:
SSL:
Mode: 'verify-full'
RootCert: "/crdb-certs/ca.crt"
Cert: "/crdb-certs/client.zitadel_user.crt"
Key: "/crdb-certs/client.zitadel_user.key"
Admin:
SSL:
Mode: 'verify-full'
RootCert: "/crdb-certs/ca.crt"
Cert: "/crdb-certs/client.root.crt"
Key: "/crdb-certs/client.root.key"
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 CockroachDB
Database:
cockroach:
User:
# If the user doesn't exist already, it is created
Username: 'zitadel_user'
Admin:
Username: 'root'
example-zitadel-init-steps.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml
FirstInstance:
Org:
Human:
# use the loginname root@zitadel.localhost
Username: 'root'
Password: 'RootPassword1!'
# Download the docker compose example configuration for a secure CockroachDB.
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/manage/production/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/manage/production/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/manage/production/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/manage/production/example-zitadel-init-steps.yaml
# A single ZITADEL instance always needs the same 32 characters long masterkey
# If you haven't done so already, you can generate a new one
# For example:
export ZITADEL_MASTERKEY="$(tr -dc A-Za-z0-9 </dev/urandom | head -c 32)"
# Run the database and application containers
docker compose up --detach
By default, the chart installs a secure ZITADEL and CockroachDB. The example files makes an insecure ZITADEL accessible by port forwarding the ZITADEL service to localhost. For more configuration options, go to the chart repo descriptions. For a secure installation with Docker Compose, go to the loadbalancing example
By executing the commands below, you will download the following files:
example-zitadel-values.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
zitadel:
configmapConfig:
Log:
Level: 'info'
# Make ZITADEL accessible over HTTP, not HTTPS
ExternalSecure: false
ExternalDomain: localhost
# the configmap is also passed to the zitadel binary via the --steps flag
FirstInstance:
Org:
Human:
# use the loginname root@zitadel.localhost
Username: 'root'
Password: 'RootPassword1!'
example-zitadel-values-secrets.yaml
# All possible options and their defaults: https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml
zitadel:
masterkey: 'MasterkeyNeedsToHave32Characters'
secretConfig:
Database:
cockroach:
User:
# If the user doesn't exist already, it is created
Username: 'zitadel_user'
Password: 'Secret_DB_User_Password'
Admin:
Username: 'root'
Password: ''
# Download and adjust the example configuration file containing standard configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/manage/production/example-zitadel-values.yaml
# Download and adjust the example configuration file containing secret configuration
wget https://raw.githubusercontent.com/zitadel/zitadel/main/docs/docs/self-hosting/manage/production/example-zitadel-values-secrets.yaml
# Install an insecure zitadel release that works with localhost
helm install --namespace zitadel --create-namespace my-zitadel zitadel/zitadel \
--values ./example-zitadel-values.yaml \
--values ./example-zitadel-values-secrets.yaml
# Forward the ZITADEL service port to your local machine
kubectl --namespace zitadel port-forward svc/my-zitadel 8080:80
Open your favorite internet browser at http://localhost:8080/ui/console. This is the IAM admin users login according to your configuration in the example-zitadel-init-steps.yaml:
- username: root@zitadel.localhost
- password: RootPassword1!
What's next
- Read more about the login process.
- If you want to run ZITADEL in production, you most certainly need to customize your own domain.
- Check out all possible runtime configuration properties and their defaults in the source code
- Check out all possible setup step configuration properties and their defaults in the source code
The ZITADEL management console requires end-to-end HTTP/2 support