For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.10 (unreleased)

Use connectors and deploy processes with Docker Compose

Use this page to work with connectors and local modeling tools in the Docker Compose quickstart.

Use connectors​

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

For connector overviews and installation details, see:

Connector secrets​

When you run Camunda locally with Docker Compose, some connectors require credentials or API keys to connect with external services such as Slack, SendGrid, or AWS. Store those values as secrets instead of hardcoding them in your process models.

Use centralized secrets​

In Camunda 8.10, you can use centralized secrets from local files in both the lightweight and full Docker Compose setups.

  1. In the extracted distribution, open the included secrets/ directory and create a file named OPENAI_API_KEY.

  2. Enter only the secret value, not KEY=value, and save the file as UTF-8 without a byte-order mark.

  3. Start the lightweight setup with docker compose up -d, or the full setup with docker compose -f docker-compose-full.yaml up -d.

  4. Reference the secret in a service-task or connector input mapping:

    =camunda.secrets.OPENAI_API_KEY

You don't need to edit Compose or application YAML. Both setups mount secrets/ read-only into Orchestration at /etc/camunda/secrets and configure camunda.secrets.stores.file.default.path through CAMUNDA_SECRETS_STORES_FILE_DEFAULT_PATH. The directory isn't mounted into Connectors.

Each filename is a secret name, and the file contents are its value. Use letters, numbers, underscores, or dashes in names. One trailing newline is ignored; other whitespace is part of the value. For names containing dashes, use FEEL backticks:

=camunda.secrets.`openai-api-key`

You can add files while the stack is running. Changes and deletions can take up to 20 minutes to affect resolved values because Orchestration caches secrets. To clear the cache immediately, run docker compose restart orchestration, or docker compose -f docker-compose-full.yaml restart orchestration for the full setup.

If a missing secret causes a SECRET_RESOLUTION_ERROR incident, create the file and resolve the incident in Operate. Creating the file alone doesn't resolve an existing incident.

In this Docker Compose setup, the files are plaintext and intended only for local development. The included .gitignore excludes secret files from ordinary commits. Don't force-add secret files, include them in shared archives, or copy their values into BPMN. For production, use a secret store and deployment mechanism that meets your security requirements, such as AWS Secrets Manager or Google Secret Manager.

On native Linux, make sure the container user (UID 1001) can traverse the directory and read the files. Host-user-only permissions can prevent access.

Use legacy connector secrets​

The existing connector-secrets.txt file supplies only the Connectors runtime environment for {{secrets.NAME}} references. The file isn't imported into the centralized store, so the two workflows remain independent.

You can add secrets to the connector runtime with 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 with 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 configure connector secrets.

Custom connectors​

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

To include custom connectors:

  • Create a new Docker image that bundles your connectors, as described in the Connectors repository.
  • 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.

Deploy and execute processes​

You can deploy and execute processes with either Desktop Modeler or Camunda Hub.

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.
  2. Select Camunda 8 Self-Managed.
  3. Configure the connection:
    • Cluster endpoint: http://localhost:8080/v2
    • Authentication: None
  4. Click Deploy.

For more details, see deploy to Self-Managed from Desktop Modeler.

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:8080/v2
    • Authentication: OAuth
    • OAuth URL: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
    • Client ID: orchestration
    • Client secret: secret
    • Audience: orchestration-api
  4. Click Deploy.
tip

The full configuration uses Keycloak for OIDC authentication. The client credentials are preconfigured in the .env file and Management Identity configuration.

Deploy with Camunda Hub​

note

Non-production installations of Camunda Hub are limited to five members per workspace. See Licensing.

Camunda Hub includes a browser-based modeler for creating and deploying BPMN, DMN, and form diagrams. Camunda Hub is included in the full configuration and can also run as a standalone setup.

Standalone setup​

To start Camunda Hub, its WebSockets service, Management Identity, Keycloak, PostgreSQL, and Mailpit independently, run:

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

To stop Camunda Hub and remove all data and volumes, run:

docker compose -f docker-compose-hub.yaml down -v

Deploy or execute a process​

When you use the full configuration, Camunda Hub connects automatically to the local Orchestration Cluster started by docker-compose-full.yaml. You can deploy and run processes directly from the Camunda Hub interface.

  1. Log in to Camunda Hub at http://localhost:8070 with demo / demo.
  2. Create a workspace.
  3. In your workspace, create a new project.
  4. In your project, create a new BPMN diagram.
  5. Use the visual modeler to design your BPMN process.
  6. Click Deploy to deploy the diagram to the preconfigured Orchestration Cluster.
  7. After deployment, you can create process instances and monitor them in Operate.

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

note

Camunda Hub is not included in the lightweight configuration. To use Camunda Hub with the lightweight configuration:

  1. Run Camunda Hub separately with docker-compose-hub.yaml.
  2. Manually configure the cluster connection in Camunda Hub.
  3. Use NONE or BASIC authentication for the lightweight Orchestration Cluster.

For details, see configure Camunda Hub clusters.

Emails​

The Docker Compose setup includes Mailpit as a test SMTP server. Mailpit captures all emails sent by Camunda Hub, but does not forward them to actual recipients.

You can access emails in Mailpit at http://localhost:8075.

Next steps​