For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.9

Configure secondary storage with Docker Compose

Use this page to configure secondary storage for the Orchestration Cluster in the Docker Compose quickstart.

Configure secondary storage for the Orchestration Cluster​

Both the lightweight and full configurations use file-based H2 secondary storage by default. The lightweight setup selects configuration/application-h2.yaml with ORCHESTRATION_CONFIG_FILE; the full setup mounts .orchestration/application.yaml.

The examples below use Spring environment variables in docker-compose.override.yaml. These variables override the secondary-storage settings in either mounted application file, so one override can be used with the lightweight or full configuration. The full configuration continues to run its bundled Elasticsearch service for Optimize and legacy exporters.

Use this workflow for each example:

  1. Create docker-compose.override.yaml in the extracted distribution directory.
  2. Copy the backend-specific example into that file.
  3. If the backend requires an external JDBC driver, place the driver JAR directly in ./driver-lib and keep the ./driver-lib:/driver-lib volume mount from the example.
  4. Start the lightweight or full stack with the command shown below the example.
note

Camunda configures the built-in exporter automatically from camunda.data.secondary-storage.*. You do not need to add a separate exporter class for the standard Docker Compose quickstart.

Use RDBMS secondary storage​

These examples switch the Orchestration Cluster from H2 to another RDBMS. They are suitable for local development and evaluation. PostgreSQL, MariaDB, and SQL Server drivers are bundled in the image. MySQL and Oracle require you to provide the JDBC driver.

Review the RDBMS support policy before you plan another deployment type.

services:
  orchestration:
    environment:
      CAMUNDA_DATA_SECONDARY_STORAGE_TYPE: rdbms
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_DATABASEVENDORID: postgresql
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URL: jdbc:postgresql://postgres-secondary:5432/camunda_secondary
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAME: camunda
      CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORD: camunda
    depends_on:
      - postgres-secondary
    networks:
      - secondary-storage

  postgres-secondary:
    image: postgres:16
    environment:
      POSTGRES_DB: camunda_secondary
      POSTGRES_USER: camunda
      POSTGRES_PASSWORD: camunda
    volumes:
      - postgres-secondary-data:/var/lib/postgresql/data
    networks:
      - secondary-storage

volumes:
  postgres-secondary-data:

networks:
  secondary-storage:
# Lightweight setup
docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d

# Full setup
docker compose -f docker-compose-full.yaml -f docker-compose.override.yaml up -d

Switch between RDBMS, Elasticsearch, and OpenSearch​

To switch from RDBMS to a document-store backend, override the backend type and connection settings. The full setup continues to use its bundled Elasticsearch service for Optimize even when the Orchestration Cluster uses a separate Elasticsearch or OpenSearch service.

note

In the full setup, .orchestration/application.yaml also pins the webapp database keys camunda.database.type, camunda.operate.database, and camunda.tasklist.database to rdbms. Update those keys in that file to match the backend you select, otherwise Operate and Tasklist keep their RDBMS wiring after you switch. The lightweight configuration/ files do not set these keys, so the environment overrides below are sufficient there.

services:
  orchestration:
    environment:
      CAMUNDA_DATA_SECONDARY_STORAGE_TYPE: elasticsearch
      CAMUNDA_DATA_SECONDARY_STORAGE_ELASTICSEARCH_URL: http://elasticsearch-secondary:9200
      CAMUNDA_DATA_SECONDARY_STORAGE_ELASTICSEARCH_USERNAME: ""
      CAMUNDA_DATA_SECONDARY_STORAGE_ELASTICSEARCH_PASSWORD: ""
    depends_on:
      - elasticsearch-secondary
    networks:
      - secondary-storage

  elasticsearch-secondary:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.19.11
    environment:
      discovery.type: single-node
      xpack.security.enabled: "false"
      ES_JAVA_OPTS: -Xms512m -Xmx512m
    volumes:
      - elasticsearch-secondary-data:/usr/share/elasticsearch/data
    networks:
      - secondary-storage

volumes:
  elasticsearch-secondary-data:

networks:
  secondary-storage:
# Lightweight setup
docker compose -f docker-compose.yaml -f docker-compose.override.yaml up -d

# Full setup
docker compose -f docker-compose-full.yaml -f docker-compose.override.yaml up -d

Secondary storage environment variables​

Use these variables when you adapt the examples to your own local setup:

VariableUse
CAMUNDA_DATA_SECONDARY_STORAGE_TYPESelects the backend family: rdbms, elasticsearch, or opensearch.
CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_URLJDBC connection string for the relational database used as secondary storage.
CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_USERNAMEDatabase username for RDBMS secondary storage.
CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_PASSWORDDatabase password for RDBMS secondary storage.
CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_DATABASEVENDORIDOptional vendor override. Use postgresql, mariadb, mysql, oracle, mssql, or h2 when you want to make the backend explicit.
CAMUNDA_DATA_SECONDARY_STORAGE_RDBMS_AUTO_DDLControls whether Camunda creates and updates the schema automatically. The default is true.
CAMUNDA_DATA_SECONDARY_STORAGE_ELASTICSEARCH_URLEndpoint for Elasticsearch when type=elasticsearch.
CAMUNDA_DATA_SECONDARY_STORAGE_OPENSEARCH_URLEndpoint for OpenSearch when type=opensearch.

For additional secondary storage settings, see Configure secondary storage and Configure RDBMS for manual installations.

Next steps​