Skip to main content

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​

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

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​

caution

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