Developer quickstart with Docker Compose
Get started with a Docker Compose configuration to run Camunda Self-Managed components (Orchestration cluster, Optimize, Console, Web Modeler and Connectors). Docker Compose also supports document storage and management with document handling.
While the Docker images are supported in production, the provided Docker Compose files are only for local development and testing. For production, Camunda recommends Kubernetes.
Prerequisites
The following prerequisites are required to run Camunda Self-Managed via Docker Compose:
| Prerequisite | Description |
|---|---|
| Docker Compose | Version 1.27.0 or higher (supports the latest compose specification). |
| Docker | Version 20.10.16 or higher. |
Run Camunda 8 with Docker Compose
To start a complete Camunda 8 Self-Managed environment locally:
-
Download the artifact for Camunda 8 Docker Compose, then extract it.
-
Run the following command in the extracted directory:
docker compose up -d -
Wait for the environment to initialize (this can take several minutes). Monitor the logs (especially the Keycloak container log) to ensure the components have started.
Access components
You can log in to the component web interfaces with the default credentials:
- Username:
demo - Password:
demo
Configuration options
Running docker compose up -d starts all Camunda components. The Camunda Distributions repository also includes additional configuration files for lightweight deployments.
| Configuration File | Description |
|---|---|
| docker-compose.yaml | Contains all Camunda 8 components for a full-stack deployment, including the Orchestration cluster, Connectors, Optimize, Console, Elasticsearch, Keycloak, Web Modeler, and PostgreSQL. |
| docker-compose-core.yaml | Contains only the Camunda 8 Orchestration cluster components and Connectors. |
| docker-compose-web-modeler.yaml | Contains the standalone Camunda 8 Web Modeler installation. For more information, see the Web Modeler instructions. |
To start Camunda with an alternate configuration, specify the configuration file using the following command:
docker compose -f docker-compose-core.yaml up -d
Orchestration Cluster
| Component | URL |
|---|---|
| Operate | http://localhost:8088/operate |
| Tasklist | http://localhost:8088/tasklist |
| Identity | http://localhost:8088/identity |
| Orchestration cluster REST API | http://localhost:8088/v2 |
| Zeebe API (gRPC) | localhost:26500 |
Management and modeling components
| Component | URL |
|---|---|
| Console | http://localhost:8087 |
| Optimize | http://localhost:8083 |
| Management Identity | http://localhost:8084 |
| Web Modeler | http://localhost:8070 |
External dependencies
| Component | URL | Description |
|---|---|---|
| Elasticsearch | http://localhost:9200 | Used by the Orchestration Cluster (as secondary storage) and Optimize. |
| Keycloak | http://localhost:18080/auth/ | Used to manage users for Management and Modeling components. Users for the Orchestration Cluster are managed within the Orchestration cluster itself. Access with username admin and password admin. |
Stop Camunda 8
Run the following command to stop Camunda 8:
docker compose down -v
This will also delete any data you have created.
To tear down the environment and keep your data, run the following command:
docker compose down
Modeling and process execution
Web Modeler
Non-production installations of Web Modeler are limited to five collaborators per project. See licensing.
Standalone setup
Web Modeler is included by default when running the docker-compose.yaml configuration but can also be run independently with Identity, Keycloak, and Postgres as dependencies.
The following command uses the provided docker-compose-web-modeler.yaml configuration file to start only 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 orchestration cluster started by the provided docker-compose.yaml is pre-configured in Web Modeler.
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.
Use the Orchestration Cluster REST API
- (If authentication is enabled) Authenticate
- Deploy resources
- Create a process instance
Desktop Modeler
You can also use Desktop Modeler instead of Web Modeler in order to model BPMN, DMN, and Camunda Forms on your local machine.
Desktop Modeler is open source and free to use.
Download the Desktop Modeler to start modeling BPMN, DMN, and Camunda Forms on your local machine.
Secure the Orchestration Cluster REST API
By default, the Orchestration cluster REST API is publicly accessible without requiring any client credentials for development purposes.
Connectors
Both the full and lightweight Docker Compose files include a configuration for Camunda connectors. Refer to the Connector installation guide for details on how to provide 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, one per line. The secrets will then be available in the connector runtime as 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 connector JARs must include all necessary dependencies inside the JAR.
Next steps
Check out the getting started guide to start a new Java Project to connect to this local cluster.