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

Property reference

Camunda Hub Self-Managed consists of two components: restapi and websocket. Each component is configured separately as described below.

  • The restapi component is a Spring Boot application. Its configuration is stored in a YAML file (application.yml) by default. All Camunda Hub-specific settings are prefixed with camunda.modeler.
  • The websocket (PHP/Laravel) component is configured via environment variables.
Configuration methods

The two components support configuration through environment variables. For the restapi component, environment variables can be used as an alternative to application.yml following Spring Boot conventions: convert the property to uppercase, remove any dashes, and replace any delimiters (.) with _.

For example, the property camunda.modeler.clusters[0].name is represented by the environment variable CAMUNDA_MODELER_CLUSTERS_0_NAME.

If you are using the Camunda 8 Helm chart, read more about the different configuration options in the chart's Helm chart values documentation. You can pass environment variables to each component via webModeler.restapi.env and webModeler.websocket.env in your values.yaml.

For a working example configuration showing how the components are correctly wired together, see the Docker Compose file for Web Modeler.

Licensing​

Camunda 8 Self-Managed only

Installations of Camunda 8 Self-Managed which require a license can provide their license key to the components as an environment variable:

Environment variableDescriptionDefault value
CAMUNDA_LICENSE_KEYYour Camunda 8 license key, if your installation requires a license.None

For Helm installations, license keys can be configured globally in your values.yaml file. See the License key for more details.

note

Camunda 8 components without a valid license may display Non-Production License in the navigation bar and issue warnings in the logs. These warnings have no impact on startup or functionality.

Web Modeler without a license: Web Modeler is limited to five concurrent users when running without a valid enterprise license. This applies to Self-Managed installations used for testing or development purposes. To support additional users or for production use, obtain a Camunda Self-Managed Enterprise Edition license by visiting the Camunda Enterprise page.

Configuration of the restapi component​

As a Spring Boot application, the restapi component supports any standard Spring configuration method.

The examples below show configuration in two formats:

  • Environment variables – suitable for Docker Compose or direct shell usage.
  • application.yml – the native Spring Boot configuration file format.
Passing JVM options

When running the restapi component in a container (Docker / Kubernetes), use the JAVA_TOOL_OPTIONS environment variable to pass JVM arguments, for example for trust store settings or proxy configuration.

General​

camunda.modeler.server:
  url: https://modeler.example.com # or https://example.com/modeler
  https-only: true # optional, default: true

server:
  servlet:
    context-path: /modeler # optional; required if server-url does not point to root path

Clusters​

To show your Orchestration Clusters in Camunda Hub, use the following configuration options available from Camunda 8.10. If you're migrating from an older version of Camunda Self-Managed, refer to the deprecated legacy configurations and the migration guide.

note

Only Web Modeler admins (users with the admin:* permission) can access the cluster pages in Camunda Hub.

PropertyDescriptionExample value
camunda.modeler.clusters[0].idAn identifier for the cluster.camunda-platform
camunda.modeler.clusters[0].nameA readable name for the cluster.Camunda Platform
camunda.modeler.clusters[0].versionThe cluster version.8.10.0
camunda.modeler.clusters[0].tagsA list of tags.['dev', 'test']
camunda.modeler.clusters[0].authenticationThe authentication method.BEARER_TOKEN
camunda.modeler.clusters[0].authorizations.enabledEnables or disables authorizations for the cluster. If enabled, users see a hint when they deploy from Camunda Hub.true
camunda.modeler.clusters[0].custom-propertiesA list of custom properties.See custom properties.
camunda.modeler.clusters[0].componentsA list of components for the clusters.See components.

Available authentication methods​

Clusters must be configured using the following options to access the cluster from within Camunda Hub:

MethodDescriptionWhen to use?
BEARER_TOKENCamunda Hub sends the authenticated user's token in the Authorization header with every request to the cluster.Cluster version >= 8.8
The cluster uses OIDC authentication with the same identity provider as Camunda Hub.
Note: You need to ensure that the cluster accepts Camunda Hub's token audience.

Cluster version < 8.8
The cluster uses Camunda Identity-based authentication and the external identity provider supports access tokens with multiple audiences (example provider: Keycloak).
Note: For the token to be accepted by the different cluster components, it must contain each component's audience.
BASICCamunda Hub sends a username and password with every request to the cluster. The credentials have to be provided by the user in the UI.Cluster version >= 8.8
The cluster uses Basic authentication.

Cluster version < 8.8
not supported

Console limitation
Console pages in Camunda Hub don't support clusters configured with Basic authentication. Console requests to the Orchestration Cluster are made automatically in the background, so there is no UI to collect credentials. Clusters using Basic authentication will not work correctly with Console functionality.
NONECamunda Hub does not send any authentication information.Cluster version >= 8.8
The cluster API is configured as unprotected and can be used without authentication.

Cluster version < 8.8
The authentication / token validation in the Zeebe Gateway is disabled.

Custom properties​

Use custom properties to include helpful links in the Clusters user interface:

PropertyDescription
camunda.modeler.clusters[0].custom-properties[0].descriptionA description of the custom property.
camunda.modeler.clusters[0].custom-properties[0].linksA list of links.
camunda.modeler.clusters[0].custom-properties[0].links[0].nameA name for the link.
camunda.modeler.clusters[0].custom-properties[0].links[0].urlThe link's URL.

Example configuration:

camunda:
  modeler:
    clusters:
      - id: camunda-platform
        # other fields...
        custom-properties:
          - description: This is the integration environment for the Camunda platform.
            links:
              - name: Camunda
                url: https://camunda.com/
              - name: Documentation
                url: https://docs.camunda.io/

Components​

Use components to set up components in the cluster:

PropertyDescription
camunda.modeler.clusters[0].components[0].nameThe component's name.
camunda.modeler.clusters[0].components[0].typeThe component's type.
camunda.modeler.clusters[0].components[0].versionThe component's version.
camunda.modeler.clusters[0].components[0].urls.webappThe API base URL for all components with a web app: Admin, Management Identity, Optimize, Tasklist, Operate.
camunda.modeler.clusters[0].components[0].urls.restThe REST API base URL for Connectors and the Orchestration Cluster.
camunda.modeler.clusters[0].components[0].urls.grpcThe address of the Zeebe gRPC API.
camunda.modeler.clusters[0].components[0].urls.readinessThe address of the health check endpoint.

Available component types and requirements:

Configuration valueComponentRequirements
connectorsConnectorsREST URL
identityManagement Identity-
webModelerWebAppCamunda Hub-
operateOperate-
optimizeOptimize-
orchestrationOrchestration ClusterCluster version >= 8.8, gRPC URL, and REST URL
orchestrationIdentityAdmin-
tasklistTasklist-
zeebeZeebe BrokerCluster version < 8.8, gRPC URL, and REST URL
zeebeGatewayZeebe GatewayCluster version < 8.8

Example configuration:

camunda:
  modeler:
    clusters:
      - id: camunda-platform
        # other fields...
        components:
          - name: "Orchestration Cluster"
            type: "orchestration"
            version: "8.10-SNAPSHOT"
            urls:
              grpc: "grpcs://camunda.example.com:26500"
              rest: "https://camunda.example.com"
              readiness: "https://camunda.example.com:9600/core/actuator/health/readiness"
          - name: "Orchestration Admin"
            type: "orchestrationIdentity"
            version: "8.10-SNAPSHOT"
            urls:
              webapp: "https://camunda.example.com"
              readiness: "https://camunda.example.com:9600/core/actuator/health/readiness"

Database​

Camunda Hub currently supports PostgreSQL, Oracle, Microsoft SQL Server (MSSQL), MySQL, MariaDB, and H2 as persistent data storage.

Oracle and MySQL driver

The Oracle and MySQL drivers are not provided by default and must be downloaded and supplied for the application to load. Refer to the Oracle and MySQL database configuration section for details.

spring:
  datasource:
    url: jdbc:postgresql://postgres.example.com:5432/modeler-db
    username: modeler-user
    password: "***"
    # driver-class-name: software.amazon.jdbc.Driver  # optional
    hikari:
      schema: custom_schema # optional; only supported for PostgreSQL

Refer to the Advanced Database Configuration Guide for additional details on how to configure Camunda Hub's database connection.

SMTP / email​

Camunda Hub requires an SMTP server to send notification emails to users.

camunda.modeler.mail:
  from-address: noreply@example.com
  from-name: Camunda # optional, default: Camunda

spring:
  mail:
    host: smtp.example.com
    port: 587
    user: modeler-user # optional
    password: "***" # optional
    properties:
      mail.smtp.auth: true # set to true if user and password are provided
      mail.smtp.starttls.enable: true # default: true; set to false to disable STARTTLS encryption
      mail.smtp.starttls.required: true # default: true; set to false to avoid enforcing STARTTLS

WebSocket​

Camunda Hub uses a WebSocket server to send events (e.g. "file updated", "comment added", "user opened diagram") between the backend and the client application in the browser. This enables features like real-time notifications and immediate UI updates.

camunda.modeler:
  pusher:
    host: modeler-websockets
    port: 8060 # default: 8060
    app-id: web-modeler
    key: "***"
    secret: "***"
    client:
      host: ws.example.com
      port: 443 # default: 80
      path: /modeler-ws # optional, default: /
      force-tls: true # default: false

Identity / Keycloak​

Camunda Hub uses Keycloak as the default authentication provider (using OAuth 2.0 + OpenID Connect) and integrates with Management Identity for user management and authorization (see Manage access and permissions).

camunda:
  identity:
    base-url: http://identity:8080
    issuer-backend-url: http://keycloak:18080/auth/realms/camunda-platform # optional

  modeler:
    security:
      jwt:
        issuer:
          backend-url: http://keycloak:18080/auth/realms/camunda-platform # optional
        audience:
          internal-api: web-modeler-api # default: web-modeler-api
          public-api: web-modeler-public-api # default: web-modeler-public-api
    oauth2:
      client-id: web-modeler
      client:
        fetch-request-credentials: include # optional
        scope: openid email profile # optional
      token.username-claim: name # optional, default: name

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://keycloak.example.com/auth/realms/camunda-platform
          jwk-set-uri: https://keycloak.example.com/auth/realms/camunda-platform/protocol/openid-connect/certs # optional
          jws-algorithms: ES256 # optional
Helm behavior

The restapi component default for CAMUNDA_MODELER_OAUTH2_TOKEN_USERNAMECLAIM is name. In Helm-based setups, OIDC configuration commonly uses preferred_username, so usernames may appear as email-style identifiers unless you explicitly set CAMUNDA_MODELER_OAUTH2_TOKEN_USERNAMECLAIM=name for the Camunda Hub restapi environment.

Refer to the advanced Identity configuration guide for additional details on how to connect a custom OpenID Connect (OIDC) authentication provider.

Camunda client​

Camunda Hub uses the Camunda Java client to connect to Zeebe. To customize the client configuration, you can provide optional properties.

camunda:
  ca-certificate-path: /path/to/certificate # optional
  client:
    config-path: /path/to/credentials/cache.txt # optional; when unset, OAuth credentials are cached in memory only
    request-timeout: 60000 # optional, default: 10000
  auth:
    connect-timeout: 30000 # optional, default: 5000
    read-timeout: 30000 # optional, default: 5000

For more details, see the Zeebe connection troubleshooting section.

Logging​

camunda.modeler.client.logging.level: DEBUG # optional, default: WARN

logging:
  config: file:/full/path/to/custom-log4j2-spring.xml # optional

Refer to the advanced logging configuration guide for additional details on how to customize the restapi logging output.

info

SSL​

server:
  ssl:
    enabled: true # optional, default: false
    certificate: file:/full/path/to/certificate.pem
    certificate-private-key: file:/full/path/to/key.pem

management:
  server:
    ssl:
      enabled: true # optional, default: false
      certificate: file:/full/path/to/certificate.pem
      certificate-private-key: file:/full/path/to/key.pem

camunda.modeler:
  pusher:
    ssl-enabled: true # optional, default: false; enables SSL to the websocket component

Refer to the advanced SSL configuration guide for additional details on how to set up secure connections (incoming & outgoing) to the Camunda Hub components.

Monitoring and health probes​

The restapi component is a Spring Boot application that includes the Spring Boot Actuator, providing health check and metrics endpoints out of the box. These endpoints are served on a separate management port (default: 8091).

By default, Camunda Hub uses the following actuator configuration:

management:
  server:
    port: 8091

  endpoints:
    access:
      default: none
    web:
      exposure:
        include: health, info, prometheus, loggers
      base-path: /
      path-mapping:
        health: health
        prometheus: metrics

  endpoint:
    prometheus:
      access: read-only
    health:
      access: read-only
      probes:
        enabled: true
      # make readiness endpoint additionally available on main server port, so that it gets publicly exposed
      group:
        readiness:
          additional-path: "server:/health"
    info:
      access: read-only
    loggers:
      access: unrestricted
  info:
    git:
      enabled: false

  health:
    defaults:
      enabled: false

  metrics:
    distribution:
      percentiles:
        http.server.requests:
          - 0.5
          - 0.9
          - 0.99

Available endpoints​

EndpointDescription
<server>:8091/metricsPrometheus metrics
<server>:8091/health/readinessReadiness probe
<server>:8091/health/livenessLiveness probe

For more details, including Kubernetes probe configuration examples and websocket health endpoints, see the Monitoring page.

Git Sync​

Camunda Hub supports syncing files via Git Sync. Provide the base URL for your provider if you are using a self-hosted GitLab, GitHub, or Azure DevOps Server instance.

camunda.modeler:
  gitsync:
    max-files: 50 # default
    max-in-memory-size: 4MB # default
    github:
      base-url: https://api.github.com # default
    gitlab:
      base-url: https://gitlab.com/api/v4 # default
    azure:
      base-url: https://dev.azure.com # default
      api-version: "7.1" # default
      authority-base-path: https://login.microsoftonline.com # default
      scope: https://app.vssps.visualstudio.com/.default # default
    bitbucket:
      base-url: https://api.bitbucket.org/2.0/repositories # default

Feature flags​

PropertyDescriptionExample valueDefault value
camunda.modeler.feature.play-enabled[optional]
Enables the Play mode in the BPMN editor, allowing users to test processes in a playground environment.		truetrue
camunda.modeler.feature.bpmn-deployment-enabled[optional]
Enables the Deploy and Run actions in the BPMN editor.
When disabled, it prevents users from deploying and starting instances of processes via the UI.		falsetrue
camunda.modeler.feature.dmn-deployment-enabled[optional]
Enables the Deploy action in the DMN editor.
When disabled, it prevents users from deploying decisions via the UI.		falsetrue
camunda.modeler.feature.dynamic-cluster-management-enabled[optional]
Enables or disables dynamic cluster management.		truefalse
camunda.marketplace.enabled[optional]
Enables the integration of the Camunda Marketplace. If enabled, users can browse the Marketplace and download resources directly inside Camunda Hub.		falsetrue

Example configuration:

camunda:
  modeler.feature:
    play-enabled: true
    bpmn-deployment-enabled: true
    dmn-deployment-enabled: true
    dynamic-cluster-management-enabled: false

  marketplace:
    enabled: true

Dynamic cluster management​

Use dynamic cluster management to automatically create records for your clusters within Camunda Hub.

By default, clusters shown in Camunda Hub are strictly managed by your configuration. Cluster records are created, updated, and deleted when you change your cluster configuration values.

Dynamic cluster management changes this behavior to a hybrid model that makes use of both your cluster configuration—if provided—and the following cluster management API endpoints that are only exposed when dynamic cluster management is enabled:

NamePath
Create cluster (discovery)POST /api/v1/clusters
Delete clusterDELETE /api/v1/clusters/{clusterId}

In this mode, you:

  1. Configure your Orchestration Clusters to send license information directly to the create cluster endpoint. If you didn't define the clusters in your configuration, new cluster records with minimal information and no management functionality in the user interface will be created by a request to this endpoint.
  2. Delete stale cluster records from Camunda Hub with the delete cluster endpoint.

While not required, you can still define new clusters in your configuration. Newly defined clusters are automatically registered in Camunda Hub with all available settings and management functionality in the Camunda Hub interface.

If you remove a cluster configuration, you need to manually delete the cluster record with the delete cluster endpoint. With dynamic cluster management, you can't update cluster records. Instead, delete the record and either:

  • Allow the cluster to ping Camunda Hub with new information.
  • Update your configuration, and let the cluster record be recreated.
note

If you use dynamic cluster management, do not manually call the create cluster endpoint—only configure your clusters to do so. This endpoint doesn't currently support creating clusters with all configurable settings.

Unstable configuration options​

These are unstable options that are not officially supported and may be removed without deprecation in future releases. They are intended for testing and feedback purposes only.

camunda.modeler.resource-import.allow-private-ip-address: true # default: false; enabling this option weakens server-side request forgery (SSRF) protections and can significantly increase security exposure.

Configuration of the websocket component​

The WebSocket server shipped with Camunda Hub Self-Managed is based on the laravel-websockets open source package and implements the Pusher Channels Protocol.

The websocket component is configured via environment variables. When using the Camunda Helm chart, you can pass these variables via webModeler.websocket.env in your values.yaml. See the Helm chart values docs for all available configuration options.

Environment variableDescriptionExample valueDefault value
PUSHER_APP_IDID of the single application/tenant configured for Camunda Hub.web-modeler-
PUSHER_APP_KEYA unique key used for authentication. Provide a random alphanumeric string of at least 20 characters.***-
PUSHER_APP_SECRETA unique secret used for authentication. Provide a random alphanumeric string of at least 20 characters.***-
PUSHER_APP_PATH[optional]
Base path of the WebSocket endpoint. Can be used to expose the endpoint on a sub path instead of the domain root (e.g. https://example.com/modeler-ws).		/modeler-ws/

Logging​

Environment variableDescriptionExample valueDefault value
LOG_CHANNEL[optional]
Log channel driver, see Laravel documentation		singlestack

Refer to the Advanced Logging Configuration Guide for additional details on how to customize the websocket logging output.

SSL​

Environment variableDescriptionExample valueDefault value
PUSHER_SSL_CERT[optional]
Path to a PEM-encoded SSL certificate file.		/full/path/to/certificate.pem-
PUSHER_SSL_KEY[optional]
Path to a PEM-encoded private key file for the SSL certificate.		/full/path/to/key.pem-
PUSHER_SSL_PASSPHRASE[optional]
Passphrase for the private key file.		change-me-

Refer to the advanced SSL configuration guide for additional details on how to set up secure connections (incoming & outgoing) to the Camunda Hub components.

Notes on host names and port numbers​

  • Internal refers to host names and port numbers that are only used inside a Docker Compose network or Kubernetes cluster for backend-to-backend communication.
  • External refers to host names and port numbers that are exposed to the outside and can be reached from a web browser.