Skip to main content

Configure ZITADEL

This guide assumes you are familiar with running ZITADEL using the least amount of configuration possible.

Configuration Files​

Runtime Configuration File​

You can configure the runtime using the --config flag of the zitadel binary. For a description of all runtime configuration options and their defaults, read the ZITADEL source code.

Database Initialization File​

ZITADEL uses a different configuration file for database initialization steps. Use the --steps flag of the zitadel binary to provide this configuration file.

Multiple Configuration Files​

ZITADEL merges configuration files when multiple --config and --steps flags are provided. You can use these flags to handle standard configuration files differently from secret configuration files. For example, standard configuration files stored in git may contain public information such as a database hostname. To use private information — such as a database admin credential — without storing it in git, use an extra --config or --steps flag that requests the private information from a secret manager.

Environment Variables​

All configuration properties are configurable using environment variables. ZITADEL environment variable keys are prefixed with ZITADEL_. For example, to configure the default ZITADEL IAM admin username and password, set the zitadel binary runtime environment variables ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME and ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD.

Proxy Configuration​

A proxy for outgoing connections can be configured using the environment variables: Use HTTP_PROXY for outgoing HTTP requests, and HTTPS_PROXY for outgoing HTTPS requests. These environment variables are used as a proxy URL. To exclude specific hosts from proxying, set the NO_PROXY environment variable: The value is interpreted as a comma separated string. For more information on the NO_PROXY environment variable, read the httpproxy Go doc.

Masterkey​

The masterkey is used to AES256-encrypt other generated encryption keys. It must be 32 bytes. There are three ways to pass the masterkey 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