Zeebe can be configured through configuration files, environment variables or a mix of both. If both configuration files and environment variables are used, then the latter take precedence over configuration files.

The configuration will be applied during startup of Zeebe. It is not possible to change the configuration at runtime.

Default Configuration

The default configuration is located in config/application.yaml. This configuration contains the most common configuration settings for a standalone broker


The default configuration is not suitable for a standalone gateway node. If you want to run a standalone gateway node, please have a look at /config/gateway.yaml.template

Configuration file templates

We provide templates that contain all possible configuration settings, along with explanations for each setting:

Note that these templates also include the corresponding environment variables to use for every setting.

Editing the configuration

You can either start from scratch or start from the configuration templates listed above.

If you use a configuration template and want to uncomment certain lines, make sure to also uncomment their parent elements:

Valid Configuration

          # host:
          port: 26500

Invalid configuration

    # zeebe:
      # gateway:
        # network:
          # host:
          port: 26500

Uncommenting individual lines is a bit finicky, because YAML is sensitive to indentation. The best way to do it is to position the cursor before the # character and delete two characters (the dash and the space). Doing this consistently will give you a valid YAML file.

When it comes to editing individual settings two data types are worth mentioning:

  • Data Sizes (e.g. logSegmentSize)
    • Human friendly format: 500MB (or KB, GB)
    • Machine friendly format: size in bytes as long
  • Timeouts/Intervals (e.g. requestTimeout)
    • Human friendly format: 15s (or m, h)
    • Machine friendly format: either duration in milliseconds as long, or ISO-8601 Duration format (e.g. PT15S)

Passing configuration file to Zeebe

The configuration file can be passed to Zeebe either by adhering to naming conventions, or by explicitly specifying the configuration file through an environment variable or via a command line argument when launching Zeebe.

Naming conventions

Rename the configuration file to application.yaml and place it in the following location:


Environment Variable

Rename the configuration file to *.yaml and set an environment variable to point to the configuration file:

export SPRING_CONFIG_LOCATION='file:./[path to config file]'

Command line argument

Rename the configuration file to *.yaml and add a command line argument to point to the configuration file:

./bin/broker --spring.config.location=file:./[path to config file]


./bin/gateway --spring.config.location=file:./[path to config file]


Zeebe uses Spring Boot for its configuration parsing. So all other ways to configure a Spring Boot application should also work.

Verifying that configuration was applied

To verify that the configuration was applied, start Zeebe and look at the log.

If the configuration could be read, Zeebe will log out the effective configuration during startup:

17:13:13.120 [] [main] INFO - Starting broker 0 with configuration {
  "network": {
    "host": "",
    "portOffset": 0,
    "maxMessageSize": {
      "bytes": 4194304
    "commandApi": {
      "defaultPort": 26501,
      "host": "",
      "port": 26501,

In some cases of invalid configuration Zeebe will fail to start with a warning that explains which configuration setting could not be read.

17:17:38.796 [] [main] ERROR org.springframework.boot.diagnostics.LoggingFailureAnalysisReporter -



Failed to bind properties under '' to int:

    Value: false
    Origin: System Environment Property "ZEEBE_BROKER_NETWORK_PORTOFFSET"
    Reason: failed to convert java.lang.String to int


Update your application's configuration


Zeebe uses Log4j2 framework for logging. In the distribution and the docker image you can find the default log configuration file in config/log4j2.xml.

Google Stackdriver (JSON) logging

To enable Google Stackdriver compatible JSON logging you can set the environment variable ZEEBE_LOG_APPENDER=Stackdriver before starting Zeebe.

Default logging configuration

  • config/log4j2.xml (applied by default)
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" shutdownHook="disable">

    <Property name="log.path">${sys:app.home}/logs</Property>
    <Property name="log.pattern">%d{yyyy-MM-dd HH:mm:ss.SSS} [%X{actor-name}] [%t] %-5level %logger{36} - %msg%n</Property>
    <Property name="log.stackdriver.serviceName">${env:ZEEBE_LOG_STACKDRIVER_SERVICENAME:-}</Property>
    <Property name="log.stackdriver.serviceVersion">${env:ZEEBE_LOG_STACKDRIVER_SERVICEVERSION:-}</Property>

    <Console name="Console" target="SYSTEM_OUT">

    <Console name="Stackdriver" target="SYSTEM_OUT">
      <StackdriverLayout serviceName="${log.stackdriver.serviceName}"
        serviceVersion="${log.stackdriver.serviceVersion}" />

    <RollingFile name="RollingFile" fileName="${log.path}/zeebe.log"
        <SizeBasedTriggeringPolicy size="250 MB"/>

    <Logger name="io.zeebe" level="${env:ZEEBE_LOG_LEVEL:-info}"/>

    <Logger name="io.atomix" level="${env:ATOMIX_LOG_LEVEL:-warn}"/>

    <Root level="info">
      <AppenderRef ref="RollingFile"/>

      <!-- remove to disable console logging -->
      <AppenderRef ref="${env:ZEEBE_LOG_APPENDER:-Console}"/>


Health Probes

Health probes are set to sensible defaults which cover common use cases.

For specific use cases, it might be necessary to customize health probes: