Skip to main content
Version: 8.6

Configuration

As a Spring Boot application, Tasklist supports any standard Spring configuration method.

By default, the configuration for Tasklist is stored in a YAML file application.yml. All Tasklist-related settings are prefixed with camunda.tasklist.

note

Configuration properties can be defined as environment variables using Spring Boot conventions. To define an environment variable, convert the configuration property to uppercase, remove any dashes, and replace any delimiters (.) with _.

For example, the property server.servlet.context-path is represented by the environment variable SERVER_SERVLET_CONTEXT_PATH.

The following components are configurable:

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 Helm installation documentation 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, with the exception that Web Modeler has a limitation of five users. To obtain a license, visit the Camunda Enterprise page.

Webserver​

Tasklist supports customizing the context-path using the default Spring configuration.

Example for application.yml: server.servlet.context-path: /tasklist

Example for environment variable: SERVER_SERVLET_CONTEXT_PATH=/tasklist

Default context-path is /.

Multi-tenancy​

Multi-tenancy in the context of Camunda 8 refers to the ability of Camunda 8 to serve multiple distinct tenants or clients within a single installation.

From version 8.3 onwards, Tasklist has been enhanced to support multi-tenancy for Self-Managed setups. More information about the feature can be found in the multi-tenancy documentation.

Configuration​

For those running a Self-Managed Camunda 8 environment, configuring multi-tenancy in Tasklist requires specific settings:

NameDescriptionDefault value
camunda.tasklist.multi-tenancy.enabledActivates the multi-tenancy feature within the Tasklist app. This setting can also be overridden using the environment variable CAMUNDA_TASKLIST_MULTITENANCY_ENABLED.false

Troubleshooting​

To ensure seamless integration and functionality, the multi-tenancy feature must also be enabled across all associated components if not configured in Helm so users can view any data from tenants for which they have authorizations configured in Identity.

Find more information (including links to individual component configuration) on the multi-tenancy concepts page.

Elasticsearch or OpenSearch​

Tasklist stores and reads data from Elasticsearch or OpenSearch.

As of the 8.4 release, Tasklist is now compatible with Amazon OpenSearch 2.5.x. Note that using Amazon OpenSearch requires setting up a new Camunda installation. A migration from previous versions or Elasticsearch environments is currently not supported.

Settings to connect​

Tasklist supports basic authentication for Elasticsearch. Set the appropriate username/password combination in the configuration to use it.

Settings to connect to a secured Elasticsearch or OpenSearch instance​

To connect to a secured (https) Elasticsearch instance you need normally only set the URL protocol part to https instead of http. A secured Elasticsearch instance needs also username and password. The other SSL settings should only be used in case of connection problems, for example disable host verification.

note

You may need to import the certificate into JVM runtime.

NameDescriptionDefault value
camunda.tasklist.elasticsearch.indexPrefixPrefix for index names.tasklist
camunda.tasklist.elasticsearch.clusterNameClustername of Elasticsearch.elasticsearch
camunda.tasklist.elasticsearch.urlURL of Elasticsearch REST API.http://localhost:9200
camunda.tasklist.elasticsearch.usernameUsername to access Elasticsearch REST API.-
camunda.tasklist.elasticsearch.passwordPassword to access Elasticsearch REST API.-
camunda.tasklist.elasticsearch.ssl.certificatePathPath to certificate used by Elasticsearch.-
camunda.tasklist.elasticsearch.ssl.selfSignedCertificate was self-signed.false
camunda.tasklist.elasticsearch.ssl.verifyHostnameShould the hostname be validated.false

For OpenSearch we also have similar configurations:

NameDescriptionDefault value
camunda.tasklist.opensearch.indexPrefixPrefix for index names.tasklist
camunda.tasklist.opensearch.clusterNameCluster name of OpenSearch.opensearch
camunda.tasklist.opensearch.urlURL of OpenSearch REST API.http://localhost:9200
camunda.tasklist.opensearch.usernameUsername to access OpenSearch REST API.-
camunda.tasklist.opensearch.passwordPassword to access OpenSearch REST API.-
camunda.tasklist.opensearch.awsEnabled

Use basic authentication or AWS credentials to log in.

  • Set to false to use basic authentication for OpenSearch, adhering to the global AWS OpenSearch configuration settings.

  • Set to true to log in with AWS credentials.

false
camunda.tasklist.opensearch.ssl.certificatePathPath to certificate used by OpenSearch-
camunda.tasklist.opensearch.ssl.selfSignedCertificate was self-signed.false
camunda.tasklist.opensearch.ssl.verifyHostnameShould the hostname be validated.false

By default, Tasklist always tries to connect to Elasticsearch. To define the database to use, the configuration below is mandatory (if this configuration is missed, Elasticsearch is used as the selected database):

NameDescriptionDefault value
camunda.tasklist.databaseDatabase that Tasklist is going to connect - valid values are elasticsearch or opensearch.elasticsearch

Settings for shards and replicas​

Tasklist creates the template with index settings named tasklist-<version>_template that Elasticsearch uses for all Tasklist indices. These settings can be changed.

The following configuration parameters define the settings:

NameDescriptionDefault value
camunda.tasklist.elasticsearch.numberOfShardsHow many shards Elasticsearch uses for all Tasklist indices.1
camunda.tasklist.elasticsearch.numberOfReplicasHow many replicas Elasticsearch uses for all Tasklist indices.0

These values are applied only on first startup of Tasklist or during version update. After the Tasklist ELS schema is created, settings may be adjusted directly in the ELS template, and the new settings are applied to indices created after adjustment.

Snippet from application.yml​

camunda.tasklist:
  elasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # Url
    url: https://localhost:9200
    ssl:
      selfSigned: true

Zeebe Broker connection​

Tasklist needs a connection to the Zeebe Broker to start the import.

Settings to connect​

NameDescriptionDefault value
camunda.tasklist.zeebe.gatewayAddressGateway address that points to Zeebe as hostname and port.localhost:26500
camunda.tasklist.zeebe.secureConnection should be secure via Transport Layer Security (TLS).false
camunda.tasklist.zeebe.certificatePathPath to certificate used by Zeebe. This is necessary when the certificate isn't registered in the operating system.-
camunda.tasklist.zeebe.restAddressPath to Zeebe REST address. This is necessary to consume the Zeebe API from Tasklist.http://localhost:8083

Additionally, visit Zeebe Secure Client Communication for more details.

Snippet from application.yml​

camunda.tasklist:
  zeebe:
    # Gateway host and port
    gatewayAddress: localhost:26500

Zeebe Elasticsearch or OpenSearch exporter​

note

Refer to supported environments to find out which versions of Elasticsearch or OpenSearch are supported in a Camunda 8 Self-Managed setup.

For Elasticsearch, Tasklist imports data from Elasticsearch indices created and filled in by Zeebe Elasticsearch Exporter.
For OpenSearch, Tasklist imports data from indices created and filled in by the Zeebe OpenSearch exporter.

Therefore, settings for this Elasticsearch or OpenSearch connection must be defined and must correspond to the settings on the Zeebe side.

Settings to connect and import​

See also settings to connect to a secured Elasticsearch or OpenSearch instance.

NameDescriptionDefault value
camunda.tasklist.zeebeElasticsearch.clusterNameCluster name of Elasticsearch.elasticsearch
camunda.tasklist.zeebeElasticsearch.urlURL of Elasticsearch REST API.http://localhost:9200
camunda.tasklist.zeebeElasticsearch.prefixIndex prefix as configured in Zeebe Elasticsearch exporter.zeebe-record
camunda.tasklist.zeebeElasticsearch.usernameUsername to access Elasticsearch REST API.-
camunda.tasklist.zeebeElasticsearch.passwordPassword to access Elasticsearch REST API.-
camunda.tasklist.zeebeElasticsearch.ssl.certificatePathPath to certificate used by Elasticsearch.-
camunda.tasklist.zeebeElasticsearch.ssl.selfSignedCertificate was self-signed.false
camunda.tasklist.zeebeElasticsearch.ssl.verifyHostnameShould the hostname be validated.false

Snippet from application.yml​

camunda.tasklist:
  zeebeElasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # Url
    url: https://localhost:9200
    # Index prefix, configured in Zeebe Elasticsearch exporter
    prefix: zeebe-record

Monitoring and health probes​

Tasklist includes the Spring Boot Actuator inside, which provides the number of monitoring possibilities (e.g. health check (http://localhost:8080/actuator/health) and metrics (http://localhost:8080/actuator/prometheus) endpoints).

Tasklist uses the following Actuator configuration by default:

# disable default health indicators:
# https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-health-indicators
management.health.defaults.enabled: false

# enable Kubernetes health groups:
# https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-features.html#production-ready-kubernetes-probes
management.endpoint.health.probes.enabled: true

# enable health check and metrics endpoints
management.endpoints.web.exposure.include: health, prometheus, loggers, usage-metrics, backups

With this configuration, the following endpoints are available for use out of the box:

<server>:8080/actuator/prometheus Prometheus metrics

<server>:8080/actuator/health/liveness Liveness probe

<server>:8080/actuator/health/readiness Readiness probe

Example snippets to use Tasklist probes in Kubernetes​

For details to set Kubernetes probes parameters, see Kubernetes configure probes.

Readiness probe as yaml config​

readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 30

Liveness probe as yaml config​

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 30

Logging​

Tasklist uses Log4j2 framework for logging. In the distribution archive and inside a Docker image /usr/local/tasklist/config/log4j2.xml, logging configuration files are included and can be further adjusted to your needs:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" monitorInterval="30">
  <Properties>
    <Property name="LOG_PATTERN">%clr{%d{yyyy-MM-dd HH:mm:ss.SSS}}{faint} %clr{%5p} %clr{${sys:PID}}{magenta} %clr{---}{faint} %clr{[%15.15t]}{faint} %clr{%-40.40c{1.}}{cyan} %clr{:}{faint} %m%n%xwEx</Property>
    <Property name="log.stackdriver.serviceName">${env:TASKLIST_LOG_STACKDRIVER_SERVICENAME:-tasklist}</Property>
    <Property name="log.stackdriver.serviceVersion">${env:TASKLIST_LOG_STACKDRIVER_SERVICEVERSION:-}</Property>
  </Properties>
  <Appenders>
    <Console name="Console" target="SYSTEM_OUT" follow="true">
      <PatternLayout pattern="${LOG_PATTERN}"/>
    </Console>
    <Console name="Stackdriver" target="SYSTEM_OUT" follow="true">
      <StackdriverLayout serviceName="${log.stackdriver.serviceName}"
        serviceVersion="${log.stackdriver.serviceVersion}" />
    </Console>
  </Appenders>
  <Loggers>
    <Logger name="io.camunda.tasklist" level="info" />
    <Root level="info">
      <AppenderRef ref="${env:TASKLIST_LOG_APPENDER:-Console}"/>
    </Root>
  </Loggers>
</Configuration>

By default, Console Appender is used.

JSON logging configuration​

You can choose to output logs in JSON format (Stackdriver compatible). To enable it, define the environment variable TASKLIST_LOG_APPENDER like the following:

TASKLIST_LOG_APPENDER=Stackdriver

Change logging level at runtime​

Tasklist supports the default scheme for changing logging levels as provided by Spring Boot.

The log level for Tasklist can be changed by following the Setting a Log Level section.

Set all Tasklist loggers to DEBUG​

curl 'http://localhost:8080/actuator/loggers/io.camunda.tasklist' -i -X POST \
-H 'Content-Type: application/json' \
-d '{"configuredLevel":"debug"}'

Clustering​

Distributed user sessions​

If more than one Camunda Tasklist instance is accessible by users for a failover scenario, for example, persistent sessions must be configured for all instances. This enables distributed sessions among all instances and users do not lose their session when being routed to another instance.

NameDescriptionDefault value
camunda.tasklist.persistent.sessions.enabledEnables the persistence of user sessions in Elasticsearch.false

Example of application.yml file​

The following snippet represents the default Tasklist configuration, which is shipped with the distribution. It can be found inside the config folder (/usr/local/tasklist/config/application.yml) and can be used to adjust Tasklist to your needs.

# Tasklist configuration file

camunda.tasklist:
  # Set Tasklist username and password.
  # If user with <username> does not exists it will be created.
  # Default: demo/demo
  #username:
  #password:
  #roles:
  #  - OWNER
  #  - OPERATOR

  # ELS instance to store Tasklist data
  elasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # url
    url: http://localhost:9200
  # Zeebe instance
  zeebe:
    # Gateway address
    gatewayAddress: localhost:26500
  # ELS instance to export Zeebe data to
  zeebeElasticsearch:
    # Cluster name
    clusterName: elasticsearch
    # url
    url: http://localhost:9200
    # Index prefix, configured in Zeebe Elasticsearch exporter
    prefix: zeebe-record

Cross-site request forgery protection​

Cross-site request forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they are currently authenticated. To mitigate this risk, Camunda provides CSRF protection that can be enabled in the Tasklist web application.

Enabling CSRF protection​

CSRF protection is enabled by default on Camunda Self-Managed. To explicitly define this, set the configuration variable camunda.tasklist.csrfPreventionEnabled to true. This is the recommended setting for production environments to enhance security.

camunda:
  tasklist:
    csrfPreventionEnabled: true

When CSRF protection is enabled, the Tasklist web application requires a valid X-CSRF-Token header to be present in all state-changing HTTP requests (POST, PUT, DELETE, etc.)

Disabling CSRF protection​

To disable CSRF protection, set the configuration property camunda.tasklist.csrfPreventionEnabled to false. This setting is not recommended for production environments as it may expose the application to CSRF attacks.

camunda:
  tasklist:
    csrfPreventionEnabled: false