Configuration
The different components of Web Modeler Self-Managed can be configured using environment variables. Each component's variables are described below.
- For a working example configuration showing how the components are correctly wired together, see the Docker Compose file for Web Modeler.
- If you are using the Camunda 8 Helm chart to set up Web Modeler, read more about the different configuration options in the chart's values docs.
Licensing
Camunda 8 Self-Managed onlyInstallations of Camunda 8 Self-Managed which require a license can provide their license key to the components as an environment variable:
| Environment variable | Description | Default value |
|---|---|---|
CAMUNDA_LICENSE_KEY | Your 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 Helm installation documentation for more details.
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, with the exception that Web Modeler has a limitation of five users. To obtain a license, visit the Camunda Enterprise page.
Configuration of the restapi component
Clusters
Clusters must be configured using the following options to access the cluster from within Web Modeler. If no clusters are configured, you will not be able to perform any actions that require a cluster (for example, deploy, start an instance, or Play a process).
The Camunda 8 Helm and Docker Compose distributions provide a local Zeebe cluster configured by default.
To add additional clusters, increment the 0 value for each variable (CAMUNDA_MODELER_CLUSTERS_1_NAME).
| Environment variable | Description | Example value |
|---|---|---|
CAMUNDA_MODELER_CLUSTERS_0_ID | A unique identifier to use for your cluster. | test-cluster-1 |
CAMUNDA_MODELER_CLUSTERS_0_NAME | The name of your cluster. | test cluster 1 |
CAMUNDA_MODELER_CLUSTERS_0_VERSION | The Camunda version used by this cluster. | 8.6.0 |
CAMUNDA_MODELER_CLUSTERS_0_AUTHENTICATION | The authentication to use with your cluster. | OAUTH, NONE |
CAMUNDA_MODELER_CLUSTERS_0_URL_ZEEBE_GRPC | The address where your cluster can be reached. | grpcs://zeebe-1.example.com:26500 |
CAMUNDA_MODELER_CLUSTERS_0_URL_ZEEBE_REST | The address where the Zeebe REST API can be reached. | https://zeebe-1.example.com:8080 |
CAMUNDA_MODELER_CLUSTERS_0_URL_OPERATE | The address where Operate can be reached. | https://operate-1.example.com |
CAMUNDA_MODELER_CLUSTERS_0_URL_TASKLIST | The address where Tasklist can be reached. | https://tasklist-1.example.com |
CAMUNDA_MODELER_CLUSTERS_0_OAUTH_URL | The address of your token issuer. | https://auth.example.com/token |
CAMUNDA_MODELER_CLUSTERS_0_OAUTH_SCOPE | A comma-separated list of the scopes to use with this cluster. | test-scope |
CAMUNDA_MODELER_CLUSTERS_0_OAUTH_AUDIENCE_ZEEBE | The permission name for Zeebe. | zeebe-api |
CAMUNDA_MODELER_CLUSTERS_0_OAUTH_AUDIENCE_OPERATE | The permission name for Operate. | operate-api |
CAMUNDA_MODELER_CLUSTERS_0_OAUTH_AUDIENCE_TASKLIST | The permission name for Tasklist. | tasklist-api |
Database
Web Modeler requires a PostgreSQL database as persistent data storage (other database systems are currently not supported).
| Environment variable | Description | Example value |
|---|---|---|
SPRING_DATASOURCE_URL | JDBC URL of the database | jdbc:postgresql://postgres.example.com:5432/modeler-db |
SPRING_DATASOURCE_USERNAME | Database user name | modeler-user |
SPRING_DATASOURCE_PASSWORD | Database user password | *** |
SPRING_DATASOURCE_DRIVER_CLASS_NAME | [optional] Java class name of the database driver | software.amazon.jdbc.Driver |
Refer to the Advanced Database Configuration Guide for additional details on how to configure Web Modeler's database connection.
SMTP / email
Web Modeler requires an SMTP server to send notification emails to users.
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
RESTAPI_MAIL_HOST | SMTP server host name | smtp.example.com | - |
RESTAPI_MAIL_PORT | SMTP server port | 587 | - |
RESTAPI_MAIL_USER | [optional] SMTP user name | modeler-user | - |
RESTAPI_MAIL_PASSWORD | [optional] SMTP user password | *** | - |
RESTAPI_MAIL_ENABLE_TLS | Enforce TLS encryption for SMTP connections (using STARTTLS). | true | true |
RESTAPI_MAIL_FROM_ADDRESS | Email address used as the sender of emails sent by Web Modeler. | noreply@example.com | - |
RESTAPI_MAIL_FROM_NAME | [optional] Name displayed as the sender of emails sent by Web Modeler. | Camunda | Camunda |
RESTAPI_SERVER_URL | URL at which users access Web Modeler in the browser (used to construct links in notification emails). | https://modeler.example.com | - |
WebSocket
The restapi component sends certain events (e.g. "file updated", "comment added") to the WebSocket server.
| Environment variable | Description | Example value |
|---|---|---|
RESTAPI_PUSHER_HOST | Internal host name of the WebSocket server. | modeler-websockets |
RESTAPI_PUSHER_PORT | Internal port number of the WebSocket server. | 8060 |
RESTAPI_PUSHER_APP_ID | must be the same as PUSHER_APP_ID | web-modeler |
RESTAPI_PUSHER_KEY | must be the same as PUSHER_APP_KEY | *** |
RESTAPI_PUSHER_SECRET | must be the same as PUSHER_APP_SECRET | *** |
Identity / Keycloak
Web Modeler integrates with Identity and Keycloak for authentication and authorization (using OAuth 2.0 + OpenID Connect) as well as user management.
| Environment variable | Description | Example value |
|---|---|---|
CAMUNDA_IDENTITY_BASEURL | Internal base URL of the Identity API (used to fetch user data). | http://identity:8080 |
RESTAPI_OAUTH2_TOKEN_ISSUER_BACKEND_URL | [optional] Internal URL used to request Keycloak's OpenID Provider Configuration; if not set, SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI is used. | http://keycloak:8080/auth/realms/camunda-platform |
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI | URL of the token issuer (used for JWT validation). | https://keycloak.example.com/auth/realms/camunda-platform |
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI | [optional] URL of the JWK Set endpoint (used for JWT validation). Only necessary if URL cannot be derived from the OIDC configuration endpoint. | https://keycloak.example.com/auth/realms/camunda-platform/protocol/openid-connect/certs |
SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWS_ALGORITHMS | [optional] List of trusted JWS algorithms used for JWT validation. Only necessary if the algorithms cannot be derived from the JWK Set response. | ES256 |
Refer to the advanced Identity configuration guide for additional details on how to connect a custom OpenID Connect (OIDC) authentication provider.
Zeebe Client
Web Modeler uses the Zeebe Java client to connect to Zeebe. To customize the client configuration, you can provide optional environment variables.
| Environment variable | Description | Example value | Default Value |
|---|---|---|---|
ZEEBE_CA_CERTIFICATE_PATH | [optional] Path to a root CA certificate to be used instead of the certificate in the default store. | /path/to/certificate | - |
ZEEBE_CLIENT_CONFIG_PATH | [optional] Path to the client's OAuth credential cache. | /path/to/credentials/cache.txt | $HOME/.camunda/credentials |
ZEEBE_CLIENT_REQUESTTIMEOUT | [optional] The request timeout used when communicating with a target Zeebe cluster. | 60000 | 10000 |
ZEEBE_AUTH_CONNECT_TIMEOUT | [optional] The connection timeout for requests to the OAuth server. | 30000 | 5000 |
ZEEBE_AUTH_READ_TIMEOUT | [optional] The data read timeout for requests to the OAuth server. | 30000 | 5000 |
For more details, see the Zeebe connection troubleshooting section.
Logging
| Environment variable | Description | Example value |
|---|---|---|
LOGGING_CONFIG | [optional] Path to custom logback configuration | file:/full/path/to/custom-logback-config.xml |
Refer to the advanced logging configuration guide for additional details on how to customize the restapi logging output.
SSL
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
SERVER_SSL_ENABLED | [optional] Whether to enable SSL support. | true | false |
SERVER_SSL_CERTIFICATE | [optional] Path to a PEM-encoded SSL certificate file. | file:/full/path/to/certificate.pem | - |
SERVER_SSL_CERTIFICATE_PRIVATE_KEY | [optional] Path to a PEM-encoded private key file for the SSL certificate. | file:/full/path/to/key.pem | - |
MANAGEMENT_SERVER_SSL_ENABLED | [optional] Whether to enable SSL support for the management server routes. | true | false |
MANAGEMENT_SERVER_SSL_CERTIFICATE | [optional] Path to a PEM-encoded SSL certificate file. | file:/full/path/to/certificate.pem | - |
MANAGEMENT_SERVER_SSL_CERTIFICATE_PRIVATE_KEY | [optional] Path to a PEM-encoded private key file for the SSL certificate. | file:/full/path/to/key.pem | - |
RESTAPI_PUSHER_SSL_ENABLED | [optional] Whether to enable communication via SSL to the websocket component. | true | false |
Refer to the advanced SSL configuration guide for additional details on how to set up secure connections (incoming & outgoing) to the Web Modeler components.
Configuration of the webapp component
General
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
SERVER_URL | URL at which users access Web Modeler in the browser. Note: To use a sub path for Web Modeler, just include the path in the URL. | https://modeler.example.com,https://example.com/modeler | - |
SERVER_HTTPS_ONLY | Enforce the usage of HTTPS when users access Web Modeler (by redirecting from http:// to https://). | true | false |
RESTAPI_HOST | Internal host name of the restapi application. | modeler-restapi | - |
RESTAPI_PORT | Internal port number on which the restapi serves the regular API endpoints. | 8081 | 8081 |
RESTAPI_MANAGEMENT_PORT | Internal port number on which the restapi serves the management API endpoints. | 8091 | 8091 |
Proxy
These settings are useful when the application needs to make outgoing network requests in environments that require traffic to pass through a proxy server.
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
http_proxy | Specifies the proxy server to be used for outgoing HTTP requests. | http://proxy.example.com:8080 | - |
https_proxy | Specifies the proxy server to be used for outgoing HTTPS requests. | https://secureproxy.example.com:443 | - |
no_proxy | A comma-separated list of domain names or IP addresses for which the proxy should be bypassed. | localhost,127.0.0.1,.example.com | - |
The proxy-related environment variables are lowercase because they follow a widely accepted convention used in many system environments and tools.
Feature Flags
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
PLAY_ENABLED | [optional] Enables the Play mode in the BPMN editor, allowing users to test processes in a playground environment. | true | true |
ZEEBE_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. | false | true |
ZEEBE_DMN_DEPLOYMENT_ENABLED | [optional] Enables the Deploy action in the DMN editor. When disabled, it prevents users from deploying decisions via the UI. | false | true |
MARKETPLACE_ENABLED | [optional] Enables the integration of the Camunda Marketplace. If enabled, users can browse the Marketplace and download resources directly inside Web Modeler. | false | true |
Identity / Keycloak
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
OAUTH2_CLIENT_ID | Client ID of the Web Modeler application configured in Identity; must be set to web-modeler. | web-modeler | - |
OAUTH2_CLIENT_FETCH_REQUEST_CREDENTIALS | [optional] Configuration whether credentials should be sent along with requests to the OIDC provider, see documentation. Use this if you are using a proxy that requires cookies. | include | - |
OAUTH2_JWKS_URL | Internal URL used to request Keycloak's JSON Web Key Set (for JWT verification). | http://keycloak:8080/auth/realms/camunda-platform/protocol/openid-connect/certs | - |
OAUTH2_TOKEN_AUDIENCE | Expected token audience (used for JWT validation); must be set to web-modeler. | web-modeler | - |
OAUTH2_TOKEN_ISSUER | URL of the token issuer (used for JWT validation). | https://keycloak.example.com/auth/realms/camunda-platform | - |
IDENTITY_BASE_URL | Internal base URL of the Identity API (used to fetch user data). | http://identity:8080 | - |
Refer to the advanced Identity configuration guide for additional details on how to connect a custom OpenID Connect (OIDC) authentication provider.
WebSocket
The webapp component sends certain events (e.g. "user opened diagram", "user left diagram") to the WebSocket server and can also react to such events (e.g. show a notification in the UI that a user left the diagram).
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
PUSHER_HOST | Internal host name of the WebSocket server. | modeler-websockets | - |
PUSHER_PORT | Internal port number of the WebSocket server. | 8060 | - |
PUSHER_APP_ID | must be the same as PUSHER_APP_ID | web-modeler | - |
PUSHER_KEY | must be the same as PUSHER_APP_KEY | *** | - |
PUSHER_SECRET | must be the same as PUSHER_APP_SECRET | *** | - |
CLIENT_PUSHER_HOST | External host name on which the Web Modeler client accesses the WebSocket server from the browser. | ws.example.com | - |
CLIENT_PUSHER_PORT | External port number on which the Web Modeler client accesses the WebSocket server from the browser. | 443 | - |
CLIENT_PUSHER_PATH | [optional] must be the same as PUSHER_APP_PATH | /modeler-ws | / |
CLIENT_PUSHER_KEY | must be the same as PUSHER_APP_KEY | *** | - |
CLIENT_PUSHER_FORCE_TLS | Enable TLS encryption for WebSocket connections initiated by the browser. | true | false |
Logging
| Environment variable | Description | Example value |
|---|---|---|
LOG_FILE_PATH | [optional] Path to log file output | /full/path/to/log/file.log |
LOG_LEVEL_CLIENT | [optional] Log level for the client | DEBUG |
LOG_LEVEL_WEBAPP | [optional] Log level for the Node.js server | DEBUG |
The LOG_LEVEL_* options can be found here.
Refer to the Advanced Logging Configuration Guide for additional details on how to customize the webapp logging output.
SSL
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
SSL_ENABLED | [optional] Whether to enable SSL support. | true | false |
SSL_CERT | [optional] Path to a PEM-encoded SSL certificate file. | /full/path/to/certificate.pem | - |
SSL_KEY | [optional] Path to a PEM-encoded private key file for the SSL certificate. | /full/path/to/key.pem | - |
SSL_PASSPHRASE | [optional] Passphrase for the private key file. | change-me | - |
MANAGEMENT_SSL_ENABLED | [optional] Whether to enable SSL support for management server routes. | true | false |
MANAGEMENT_SSL_CERT | [optional] Path to a PEM-encoded SSL certificate file. | /full/path/to/certificate.pem | - |
MANAGEMENT_SSL_KEY | [optional] Path to a PEM-encoded private key file for the SSL certificate. | /full/path/to/key.pem | - |
MANAGEMENT_SSL_PASSPHRASE | [optional] Passphrase for the private key file. | change-me | - |
RESTAPI_SSL_ENABLED | [optional] Whether to enable communication via SSL to the restapi component. | true | false |
RESTAPI_MANAGEMENT_SSL_ENABLED | [optional] Whether to enable communication via SSL to the restapi component's management routes. | true | false |
Refer to the advanced SSL configuration guide for additional details on how to set up secure connections (incoming & outgoing) to the Web Modeler components.
Configuration of the websocket component
The WebSocket server shipped with Web Modeler Self-Managed is based on the laravel-websockets open source package and implements the Pusher Channels Protocol.
| Environment variable | Description | Example value | Default value |
|---|---|---|---|
PUSHER_APP_ID | ID of the single application/tenant configured for Web Modeler. | web-modeler | - |
PUSHER_APP_KEY | A unique key used for authentication. Provide a random alphanumeric string of at least 20 characters. | *** | - |
PUSHER_APP_SECRET | A 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 variable | Description | Example value | Default Value |
|---|---|---|---|
LOG_CHANNEL | [optional] Log channel driver, see Laravel documentation | single | stack |
Refer to the Advanced Logging Configuration Guide for additional details on how to customize the websocket logging output.
SSL
| Environment variable | Description | Example value | Default 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 Web Modeler 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.