Developer quickstart with Docker Compose

Get started with Docker Compose to run Camunda 8 Self-Managed locally. The default lightweight configuration includes the Orchestration Cluster (Zeebe, Operate, and Tasklist consolidated), Connectors, and Elasticsearch. The full configuration additionally includes Optimize, Console, Management Identity, Web Modeler, Keycloak, and PostgreSQL. Docker Compose also supports document storage and management with document handling.

note

The Docker images are supported for production usage; however, the Docker Compose files are intended for developers to run an environment locally and are not designed for production. For production deployments, use Kubernetes with Helm.

Prerequisites

The following prerequisites are required to run Camunda Self-Managed via Docker Compose:

Prerequisite	Description
Docker Compose	Version 2.24.0 or later, which supports the Compose attributes used by the distribution.
Docker	Version 20.10.16 or later.

Troubleshooting unsupported attributes

If Docker Compose reports errors such as "unsupported attribute" when loading the Camunda Compose files:

• Confirm you are using Docker Compose version 2.24.0 or later:

  docker compose version

• Run the commands in this guide with docker compose (plugin syntax), not docker-compose (legacy standalone binary).

• Upgrade Docker Desktop or Docker Engine/Compose plugin to a recent supported version, then retry.

Run Camunda 8 with Docker Compose

To start the default lightweight Camunda 8 Self-Managed environment locally:

1. Download the Camunda 8 Docker Compose archive, then extract it. Keep the complete directory, including .env and the hidden component configuration directories.

2. In the extracted directory, run:

   docker compose up -d

3. Wait for the environment to initialize. This can take several minutes. Run docker compose ps to check service health, or docker compose logs -f orchestration connectors to follow the lightweight startup.

Run Compose commands from the extracted directory. If Compose reports that image-version variables are unset or .env is missing, download and extract the complete distribution archive again instead of downloading an individual Compose file.

Docker Compose configurations

Camunda provides three Docker Compose configurations in the Camunda Distributions releases:

Configuration File	Description
docker-compose.yaml	Default lightweight configuration - Includes the core Orchestration Cluster (Zeebe, Operate, and Tasklist combined), Connectors, and Elasticsearch. Ideal for most developers who want to model, deploy, and test processes.
docker-compose-full.yaml	Full-stack configuration - Includes all Camunda 8 components including the Orchestration Cluster, Connectors, Optimize, Console, Management Identity, Keycloak, PostgreSQL, and Web Modeler. Use this when you need management components, process optimization, or modeling.
docker-compose-web-modeler.yaml	Standalone Web Modeler - Runs only Web Modeler and its dependencies (Identity, Keycloak, PostgreSQL). See Deploy with Web Modeler.

Access components

Once the containers are running, you can access the components in your browser.

You can log in to the component web interfaces with the default credentials:

• Username: demo
• Password: demo

Orchestration Cluster (lightweight and full configurations)

The Orchestration Cluster is the core of Camunda 8, providing process automation capabilities.

Component	URL	Description
Operate	http://localhost:8088/operate	Monitor and troubleshoot process instances. See Introduction to Operate and Process instance creation.
Tasklist	http://localhost:8088/tasklist	Complete user tasks in running process instances. See User tasks.
Orchestration Cluster Identity	http://localhost:8088/identity	Manage users and permissions for Orchestration Cluster (lightweight).
Orchestration Cluster REST API	http://localhost:8088/v2	REST API for process automation.
Orchestration Cluster gRPC API	localhost:26500	gRPC API for high-performance process automation.

note

By default, the Orchestration Cluster uses Basic authentication. The full configuration uses Keycloak for Management Identity authentication.

Management and modeling components (full configuration only)

Component	URL	Description
Console	http://localhost:8087	Manage clusters and component configurations
Optimize	http://localhost:8083	Analyze and improve process performance
Management Identity	http://localhost:8084	Manage users for Console, Optimize, and Web Modeler
Web Modeler	http://localhost:8070	Model BPMN processes, DMN decisions, and forms

External dependencies

Component	Configuration	URL	Description
Elasticsearch	Lightweight and full	http://localhost:9200	Used by the Orchestration Cluster as secondary storage (and Optimize in the full configuration).
Keycloak	Full	http://localhost:18080/auth/	OIDC provider for Management Identity. The lightweight configuration uses the embedded Orchestration Cluster Identity instead. Access with admin / admin.
PostgreSQL	Full	Internal only	Database for Management Identity and Web Modeler.

Configuration files and options

To start specific configurations:

• Lightweight (default)

  docker compose up -d

• Full configuration

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

• Standalone Web Modeler

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

Customize application configuration

The lightweight setup keeps Orchestration Cluster and Connectors application YAML inline under configs in docker-compose.yaml. The full and standalone setups mount component-owned files from the extracted distribution:

Setup and component	Application configuration source
Full Orchestration Cluster	.orchestration/application.yaml
Full Connectors	.connectors/application.yaml
Full Optimize	Files under .optimize/
Full Console	Files under .console/
Full and standalone Management Identity	.identity/application.yaml; the standalone-only client overlay remains inline in docker-compose-web-modeler.yaml
Full and standalone Web Modeler	.web-modeler/application.yaml; the full setup mounts .web-modeler/application-full.yaml as the primary file, which adds the cluster registrations and imports the shared file

Choose the configuration mechanism based on the value you need to change:

Goal	Configuration method
Change lightweight application defaults	Edit the inline configs.content YAML in docker-compose.yaml.
Change full or standalone defaults	Edit the component-owned YAML file. Keep the existing authentication and component wiring when you change a subsection.
Change a provided runtime value or secret	Edit .env. The mounted YAML resolves placeholders such as ${VARIABLE:default} from the container environment.
Maintain a separate environment set	Copy the complete .env file, update the copy, and run docker compose --env-file <file> .... The custom file must retain image versions and other required values. --env-file only replaces the variable interpolation source, and the Camunda services still load .env itself through env_file, so keep both files in sync.
Override an additional Spring property	Add the environment variable to the relevant service in docker-compose.override.yaml. Spring environment variables override values from mounted application YAML.
Provide connector secrets	Add local development secrets to connector-secrets.txt. Do not put connector credentials in application YAML.

PostgreSQL, Keycloak, Elasticsearch, Web Modeler WebSockets, the separate Web Modeler webapp, Console, and other non-Spring services continue to use the environment settings defined by their Compose services. Keep the distribution's example credentials for local development only.

Authentication

Lightweight configuration (default)

• Web UI: Log in to Operate and Tasklist with demo / demo
• APIs: REST and gRPC APIs are publicly accessible (no authentication required)

Full configuration

• Web UI: Log in to all components (Operate, Tasklist, Console, Optimize, Web Modeler) with demo / demo.

• APIs: REST and gRPC APIs require OAuth authentication with the following settings:

  • Client ID: orchestration (from ORCHESTRATION_CLIENT_ID in the .env file)
  • Client Secret: secret (from ORCHESTRATION_CLIENT_SECRET in the .env file)
  • OAuth URL: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
  • Audience: orchestration-api

  For details, see the REST API authentication guide.

Stop Camunda 8

To stop all containers and remove associated data:

docker compose down -v

# or for the full configuration:
docker compose -f docker-compose-full.yaml down -v

# or for standalone Web Modeler:
docker compose -f docker-compose-web-modeler.yaml down -v

caution

The -v flag deletes all volumes, removing all data (process instances, users, etc.). Omit -v to keep your data.

Connectors

Both the lightweight and full Docker Compose configurations include built-in connectors for integrating with external systems. The connector runtime executes both outbound connectors (called from BPMN processes) and inbound connectors (triggering process instances from external events).

For details on available connectors and how to use them, see:

• Available connectors
• Connector installation guide

Connector secrets

When running Camunda locally with Docker Compose, some connectors require authentication credentials or API keys to connect with external services (for example, Slack, SendGrid, or AWS). These values should be stored securely as secrets instead of being hardcoded in your process models.

You can add secrets to the connector runtime using the included connector-secrets.txt file:

1. Open connector-secrets.txt in the extracted directory.
2. Add secrets in the format NAME=VALUE, one per line:

   SLACK_TOKEN=xoxb-your-token-here
   SENDGRID_API_KEY=SG.your-api-key

3. Save the file. The secrets become available in connector configurations using the syntax {{secrets.NAME}}. For example, {{secrets.SLACK_TOKEN}}.

warning

Do not commit connector-secrets.txt to version control with real credentials. Use placeholder values in the repository and configure actual secrets in each environment.

For more details, see the connector secrets documentation.

Custom connectors

In addition to the built-in connectors, you can add your own custom connectors.

To include custom connectors:

• Option 1: Create a new Docker image that bundles your connectors, as described in the Connectors repository.
• Option 2: Mount the connector JARs as volumes into the /opt/app directory in the Docker Compose file.

Each connector JAR must include all required dependencies inside the JAR to run correctly.

Modeling and process execution

You can deploy and execute processes using either Desktop Modeler or Web Modeler.

Deploy with Desktop Modeler

Desktop Modeler is a free, open-source desktop application for modeling BPMN, DMN, and Camunda Forms.

Lightweight configuration

To deploy from Desktop Modeler to the lightweight configuration:

1. Open Desktop Modeler and click the deployment icon (rocket symbol).
2. Select Camunda 8 Self-Managed.
3. Configure the connection:
   • Cluster endpoint: http://localhost:8088/v2
   • Authentication: Select None (no authentication required by default)
4. Click Deploy.

For more details, see the Desktop Modeler deployment guide.

Full configuration

To deploy from Desktop Modeler to the full configuration:

1. Open Desktop Modeler and click the deployment icon.
2. Select Camunda 8 Self-Managed.
3. Configure the connection:
   • Cluster endpoint: http://localhost:8088/v2
   • Authentication: Select OAuth
   • OAuth URL: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
   • Client ID: orchestration (from .env file: ORCHESTRATION_CLIENT_ID)
   • Client Secret: secret (from .env file: ORCHESTRATION_CLIENT_SECRET)
   • Audience: orchestration-api
4. Click Deploy.

tip

The full configuration uses Keycloak for OIDC authentication. The client credentials (orchestration / secret) are pre-configured in the .env file and Identity configuration.

Deploy with Web Modeler

info

Non-production installations of Web Modeler are limited to five collaborators per project. See licensing.

Web Modeler provides a browser-based interface for creating and deploying BPMN, DMN, and form diagrams.
It is included in the full configuration by default but can also run as a standalone setup.

Standalone setup

To start Web Modeler and its dependencies independently, run:

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

To stop and remove all data and volumes, run:

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

Deploy or execute a process

When using the full configuration, Web Modeler connects automatically to the local Orchestration Cluster started by docker-compose-full.yaml. You can deploy and run processes directly from the Web Modeler interface.

1. Log in to Web Modeler at http://localhost:8070 with demo / demo.
2. Create a new project or open an existing BPMN diagram.
3. Use the visual modeler to design your BPMN process.
4. Click Deploy to deploy the diagram to the pre-configured Orchestration Cluster.
5. After deployment, you can create process instances and monitor them in Operate.

Web Modeler uses the BEARER_TOKEN authentication method to communicate with the Orchestration Cluster. The user's authentication token from Management Identity is automatically used for deployment.

note

Web Modeler is not included in the lightweight configuration. To use Web Modeler with the lightweight configuration:

1. Run Web Modeler separately using docker-compose-web-modeler.yaml.
2. Manually configure the cluster connection in Web Modeler's configuration.
3. Use NONE or BASIC authentication for the lightweight Orchestration Cluster.

See the Web Modeler cluster configuration guide for details.

Emails

The Docker Compose setup includes Mailpit as a test SMTP server. Mailpit 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.

Enable multi-tenancy

Multi-tenancy requires an authenticated API. How you enable it depends on the configuration you run.

Lightweight configuration

Create a docker-compose.override.yaml next to the compose file that protects the API and switches on the tenancy checks:

services:
  orchestration:
    environment:
      CAMUNDA_SECURITY_AUTHENTICATION_UNPROTECTEDAPI: "false"
      CAMUNDA_SECURITY_MULTITENANCY_CHECKSENABLED: "true"
      CAMUNDA_SECURITY_MULTITENANCY_APIENABLED: "true"
  connectors:
    environment:
      CAMUNDA_CLIENT_AUTH_METHOD: basic
      CAMUNDA_CLIENT_AUTH_USERNAME: demo
      CAMUNDA_CLIENT_AUTH_PASSWORD: demo

Start the stack with docker compose up -d and manage tenants through the Orchestration Cluster API or the Identity UI at http://localhost:8088/identity:

# Create a tenant
curl -u demo:demo -X POST http://localhost:8088/v2/tenants \
  -H 'Content-Type: application/json' -d '{"tenantId": "tenant-a", "name": "Tenant A"}'
# Assign the demo user to it
curl -u demo:demo -X PUT http://localhost:8088/v2/tenants/tenant-a/users/demo

With the API protected, clients must authenticate with Basic authentication (camunda.client.auth.method=basic plus username and password in the Camunda client SDKs).

Full configuration

The full configuration already protects the API through Keycloak, so only the tenancy checks need to be switched on. Add the following to .env:

CAMUNDA_SECURITY_MULTITENANCY_CHECKSENABLED=true
CAMUNDA_SECURITY_MULTITENANCY_APIENABLED=true

Start the stack with docker compose -f docker-compose-full.yaml up -d and manage tenants through the Orchestration Cluster API with an OAuth token, or the Identity UI at http://localhost:8088/identity:

TOKEN=$(curl -s -X POST 'http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token' \
  -d 'grant_type=client_credentials' -d 'client_id=orchestration' -d 'client_secret=secret' | jq -r .access_token)
# Create a tenant
curl -X POST http://localhost:8088/v2/tenants -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' -d '{"tenantId": "tenant-a", "name": "Tenant A"}'
# Assign the demo user to it
curl -X PUT http://localhost:8088/v2/tenants/tenant-a/users/demo -H "Authorization: Bearer $TOKEN"

Next steps

Now that you have Camunda 8 running locally, explore these resources:

• Getting started: Follow the getting started guide to create a Java project and connect to your local cluster.
• BPMN modeling: Learn BPMN fundamentals and best practices.
• User tasks: Implement user tasks and forms for human workflows.
• Connectors: Explore out-of-the-box connectors for common integrations.
• APIs: Use the Orchestration Cluster REST API or client libraries to interact programmatically.
• Production deployment: When ready, deploy to production with Kubernetes and Helm.