Skip to main content
Version: 8.6

Docker Compose

A Docker Compose configuration to run Camunda Self-Managed components (Zeebe, Operate, Tasklist, Optimize, Identity, and Connectors).

danger

While the Docker images themselves are supported for production usage, the Docker Compose files are designed to be used by developers to run an environment locally, and are not designed to be used in production. We recommend Kubernetes for production use cases.

Prerequisites​

  • Docker Compose: Version 1.27.0+ (supports the latest compose specification).
  • Docker: Version 20.10.16+
  • Keycloak: (Local development only). Add Keycloak to resolve to 127.0.0.1 on your local machine, and set KEYCLOAK_HOST=keycloak in the .env file for token refresh and logout functionality.

Run Camunda 8 with Docker Compose​

To start a complete instance of Camunda 8 Self-Managed environment locally:

  1. Clone the Camunda Self-Managed repository, and navigate to the directory of the desired Camunda version (for example, /version/camunda-8.6).
  2. Run the following command:
docker compose up -d
  1. Wait for the environment to initialize. This may take several minutes. Monitor the logs, especially the Keycloak container log, to ensure the components have started.

Configuration options​

Running docker compose up -d starts all Camunda components, including Identity. The Camunda Self-Managed repository also contains additional configuration files for lightweight development.

  • docker-compose.yaml: Contains all Camunda 8 Components for a full stack deployment: Zeebe, Operate, Tasklist, Connectors, Optimize, Identity, Elasticsearch, Keycloak, Web Modeler, and PostgreSQL.
  • docker-compose-core.yaml: Contains Camunda 8 Orchestration cluster components: Zeebe, Tasklist, Operate, and Connectors.
  • docker-compose-web-modeler.yaml: Contains the Camunda 8 Web Modeler standalone installation. For more information, see the Web Modeler instructions.

To start Camunda with an alternate configuration, specify a file using the following command:

docker compose -f docker-compose-core.yaml up -d

Access components​

Running components can be accessed with the username demo and password demo:

Keycloak is used to manage users, and can be accessed with the user admin and password admin:

The workflow engine Zeebe is available using gRPC:

  • Zeebe: localhost:26500

Stop Camunda 8​

Run the following command to stop Camunda 8:

docker compose down -v
caution

This will also delete any data you created.

To tear down the environment and keep any data, run the following command:

docker compose down

Modeling and process execution​

Web Modeler​

info

Non-production installations of Web Modeler are restricted to five collaborators per project. Refer to the licensing documentation for more information.

Standalone setup​

Web Modeler is included by default when running the docker-compose.yaml configuration, but can be run independently using Identity, Keycloak and Postgres as dependencies.

The following command uses the provided docker-compose-web-modeler.yaml configuration file to only start Web Modeler and its dependencies:

docker compose -f docker-compose-web-modeler.yaml up -d

To tear down the environment (including all data and volumes), run the following command:

docker compose -f docker-compose-web-modeler.yaml down -v

Deploy or execute a process​

The local Zeebe instance started when using the provided docker-compose.yaml is pre-configured in Web Modeler.

Once you are ready to deploy or execute a process, this instance can be used without needing to enter the cluster endpoint manually. The correct authentication type is also preset based on the ZEEBE_AUTHENTICATION_MODE environment variable.

If you enabled authentication for gRPC requests on Zeebe, use the following client credentials when deploying and executing processes:

  • Client ID: zeebe
  • Client secret: zecret
note

The correct OAuth token URL and audience are preset internally.

Emails​

The provided configuration includes Mailpit as a test SMTP server. It captures all emails sent by Web Modeler, but does not forward them to the actual recipients.

You can access emails in Mailpit's Web UI at http://localhost:8075.

Desktop Modeler​

info

Desktop Modeler is open source and free to use.

Download the Desktop Modeler and start modeling BPMN, DMN and Camunda Forms on your local machine.

Use the CLI​

If you enabled authentication for GRPC requests on Zeebe, provide the following client credentials when deploying and executing processes:

  • Authentication: OAuth
  • URL: http://localhost:26500
  • Client ID: zeebe
  • Client secret: zecret
  • OAuth URL: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
  • Audience: zeebe-api

Secure the Zeebe API​

By default, the Zeebe GRPC API is publicly accessible without requiring any client credentials for development purposes.

To enable authentication of GRPC requests in Zeebe, setting the environment variable ZEEBE_AUTHENTICATION_MODE to identity, for example:

ZEEBE_AUTHENTICATION_MODE=identity docker compose up -d

The default value can also be modified directly in the included .env file.

Connectors​

Both the full and lightweight Docker Compose files contain a configuration for Out-of-the-box Connectors. Refer to the Connector installation guide for details on how to provide the related Connector templates for modeling.

Connector secrets​

Secrets can be added into the Connector runtime using the included connector-secrets.txt file. Add secrets in the format NAME=VALUE per line. The secrets will then be available in the Connector runtime in the format secrets.NAME.

Custom connectors​

To add custom Connectors, create a new Docker Image bundling them as described in the Connectors repository.

Alternatively, you can mount new Connector JARs as volumes into the /opt/app folder by adding this to the Docker Compose file. Keep in mind that the Connector JARs must include all necessary dependencies inside the JAR.

Kibana​

A Kibana profile is available in the provided configuration files to support inspection and exploration of the Camunda 8 data in Elasticsearch.

Enable the profile by adding --profile kibana to your Docker Compose command:

docker compose --profile kibana up -d

This profile will start Kibana in addition to the default components. Kibana can be used to explore the records exported by Zeebe into Elasticsearch, or to discover the data in Elasticsearch used by the other components (for example, Operate).

Navigate to the Kibana web application and explore the data without login credentials:

note

You need to configure the index patterns in Kibana before you can explore the data.

  • Go to Management > Stack Management > Kibana > Index Patterns.
  • Create a new index pattern. For example, zeebe-record-* matches the exported records.
    • If you don't see any indexes then make sure to export some data first (e.g. deploy a process). The indexes of the records are created when the first record of this type is exported.
  • Go to Analytics > Discover and select the index pattern.