Installation

Camunda 8 stack

Please refer to the Installation Guide for details on how to install Optimize as part of a Camunda 8 stack.

Camunda 7 Enterprise stack

Camunda 7 only

This document describes the installation process of the Camunda Optimize and connect it to a Camunda 7 stack, as well as various configuration possibilities available after initial installation.

Before proceeding with the installation, read the article about supported environments.

Local installation

If you wish to run Camunda Optimize natively on your hardware you can download one of the two offered distributions and run them. Especially the demo distribution might be useful to try out Camunda Optimize the first time, it also comes with a simple demo process to explore the functionality.

Prerequisites

If you intend to run Optimize on your local machine, ensure you have a supported JRE (Java Runtime Environment) installed; best refer to the Java Runtime section on which runtimes are supported.

Demo distribution with Elasticsearch

The Optimize Demo distribution comes with an Elasticsearch instance. The supplied Elasticsearch server is not customized or tuned by Camunda in any manner. It is intended to make the process of trying out Optimize as easy as possible. The only requirement in addition to the demo distribution itself is a running engine (ideally on localhost).

To install the demo distribution containing Elasticsearch, download the archive with the latest version from the download page and extract it to the desired folder. After that, start Optimize by running the script optimize-demo.sh on Linux and Mac:

./optimize-demo.sh

or optimize-demo.bat on Windows:

.\optimize-demo.bat

The script ensures that a local version of Elasticsearch is started and waits until it has become available. Then, it starts Optimize, ensures it is running, and automatically opens a tab in a browser to make it very convenient for you to try out Optimize.

In case you need to start an Elasticsearch instance only, without starting Optimize (e.g. to perform a reimport), you can use the elasticsearch-startup.sh script:

./elasticsearch-startup.sh

or elasticsearch-startup.bat on Windows:

.\elasticsearch-startup.bat

Production distribution without a database

This distribution is intended to be used in production. To install it, take the following steps:

1. Download the production archive, which contains all the required files to startup Camunda Optimize without a database.
2. Configure the database connection to connect to your pre-installed Elasticsearch/OpenSearch instance and configure the Camunda 7 connection to connect Optimize to your running engine.
3. Start your Optimize instance by running the script optimize-startup.sh on Linux and Mac:

./optimize-startup.sh

or optimize-startup.bat on Windows:

.\optimize-startup.bat

Dockerized installation

The Optimize Docker images can be used in production. They are hosted on our dedicated Docker registry and are available to enterprise customers who bought Optimize only. You can browse the available images in our Docker registry after logging in with your credentials.

Make sure to log in correctly:

$ docker login registry.camunda.cloud
Username: your_username
Password: ******
Login Succeeded

After that, configure the database connection to connect to your pre-installed Elasticsearch/OpenSearch instance and configure the Camunda connection to connect Optimize to your running engine. For very simple use cases with only one Camunda Engine and one database node, you can use environment variables instead of mounting configuration files into the Docker container:

Getting started with the Optimize Docker image

Full local setup

To start the Optimize Docker image and connect to an already locally running Camunda 7 as well as Elasticsearch instance you could run the following command:

docker run -d --name optimize --network host \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

If you wish to connect to an OpenSearch database instead, please make sure to additionally set the environment variable CAMUNDA_OPTIMIZE_DATABASE to opensearch.

docker run -d --name optimize --network host \
           -e CAMUNDA_OPTIMIZE_DATABASE=opensearch \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

Connect to remote Camunda 7 and database

If, however, your Camunda 7 as well as Elasticsearch instance reside on a different host, you may provide their destination via the corresponding environment variables:

docker run -d --name optimize -p 8090:8090 -p 8091:8091 \
           -e OPTIMIZE_CAMUNDABPM_REST_URL=http://yourCamBpm.org/engine-rest \
           -e OPTIMIZE_ELASTICSEARCH_HOST=yourElasticHost \
           -e OPTIMIZE_ELASTICSEARCH_HTTP_PORT=9200 \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

Alternatively, for OpenSearch:

docker run -d --name optimize -p 8090:8090 -p 8091:8091 \
           -e OPTIMIZE_CAMUNDABPM_REST_URL=http://yourCamBpm.org/engine-rest \
           -e CAMUNDA_OPTIMIZE_DATABASE=opensearch \
           -e CAMUNDA_OPTIMIZE_OPENSEARCH_HOST=yourOpenSearchHost \
           -e CAMUNDA_OPTIMIZE_OPENSEARCH_HTTP_PORT=9205 \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

Available environment variables

There is only a limited set of configuration keys exposed via environment variables. These mainly serve the purpose of testing and exploring Optimize. For production configurations, we recommend following the setup in documentation on configuration using a environment-config.yaml file.

The most important environment variables you may have to configure are related to the connection to the Camunda 7 REST API, as well as Elasticsearch/OpenSearch:

• OPTIMIZE_CAMUNDABPM_REST_URL: The base URL that will be used for connections to the Camunda Engine REST API (default: http://localhost:8080/engine-rest)
• OPTIMIZE_CAMUNDABPM_WEBAPPS_URL: The endpoint where to find the Camunda web apps for the given engine (default: http://localhost:8080/camunda)

For an ElasticSearch installation:

• OPTIMIZE_ELASTICSEARCH_HOST: The address/hostname under which the Elasticsearch node is available (default: localhost)
• OPTIMIZE_ELASTICSEARCH_HTTP_PORT: The port number used by Elasticsearch to accept HTTP connections (default: 9200)
• CAMUNDA_OPTIMIZE_ELASTICSEARCH_SECURITY_USERNAME: The username for authentication in environments where a secured Elasticsearch connection is configured.
• CAMUNDA_OPTIMIZE_ELASTICSEARCH_SECURITY_PASSWORD: The password for authentication in environments where a secured Elasticsearch connection is configured.

For an OpenSearch installation:

• CAMUNDA_OPTIMIZE_DATABASE: The database type to connect to, in this case opensearch (default: elasticsearch)
• CAMUNDA_OPTIMIZE_OPENSEARCH_HOST: The address/hostname under which the OpenSearch node is available (default: localhost)
• CAMUNDA_OPTIMIZE_OPENSEARCH_HTTP_PORT: The port number used by OpenSearch to accept HTTP connections (default: 9205)
• CAMUNDA_OPTIMIZE_OPENSEARCH_SECURITY_USERNAME: The username for authentication in environments where a secured OpenSearch connection is configured.
• CAMUNDA_OPTIMIZE_OPENSEARCH_SECURITY_PASSWORD: The password for authentication in environments where a secured OpenSearch connection is configured.

A complete sample can be found within Connect to remote Camunda 7 and database.

Furthermore, there are also environment variables specific to the event-based process feature you may make use of:

• OPTIMIZE_CAMUNDA_BPM_EVENT_IMPORT_ENABLED: Determines whether this instance of Optimize should convert historical data to event data usable for event-based processes (default: false)
• OPTIMIZE_EVENT_BASED_PROCESSES_USER_IDS: An array of user ids that are authorized to administer event-based processes (default: [])
• OPTIMIZE_EVENT_BASED_PROCESSES_IMPORT_ENABLED: Determines whether this Optimize instance performs event-based process instance import. (default: false)

Additionally, there are also runtime related environment variables such as:

• OPTIMIZE_JAVA_OPTS: Allows you to configure/overwrite Java Virtual Machine (JVM) parameters; defaults to -Xms1024m -Xmx1024m -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=256m.

In case you want to make use of the Optimize Public API, you can also set one of the following variables:

• SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI Complete URI to get public keys for JWT validation, e.g. https://weblogin.cloud.company.com/.well-known/jwks.json. For more details see public API authentication.
• OPTIMIZE_API_ACCESS_TOKEN secret static shared token to be provided to the secured REST API on access in the authorization header. Will be ignored if SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_JWK_SET_URI is also set. For more details see public API authentication.

You can also adjust logging levels using environment variables as described in the logging configuration.

License key file

If you want the Optimize Docker container to automatically recognize your license key file, you can use standard Docker means to make the file with the license key available inside the container. Replacing the {{< absolutePathOnHostToLicenseFile >}} with the absolute path to the license key file on your host can be done with the following command:

docker run -d --name optimize -p 8090:8090 -p 8091:8091 \
           -v {{< absolutePathOnHostToLicenseFile >}}:/optimize/config/OptimizeLicense.txt:ro \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

Configuration using a yaml file

In a production environment, the limited set of environment variables is usually not enough so that you want to prepare a custom environment-config.yaml file. Refer to the Configuration section of the documentation for the available configuration parameters.

You need to mount this configuration file into the Optimize Docker container to apply it. Replacing the {{< absolutePathOnHostToConfigurationFile >}} with the absolute path to the environment-config.yaml file on your host can be done using the following command:

docker run -d --name optimize -p 8090:8090 -p 8091:8091 \
           -v {{< absolutePathOnHostToConfigurationFile >}}:/optimize/config/environment-config.yaml:ro \
           registry.camunda.cloud/optimize-ee/optimize:{{< currentVersionAlias >}}

In managed Docker container environments like Kubernetes, you may set this up using ConfigMaps.

Usage

You can start using Optimize right away by opening the following URL in your browser: http://localhost:8090

Then, you can use the users from the Camunda 7 to log in to Optimize. For details on how to configure the user access, consult the user access management section.

Next steps

To get started configuring the Optimize web container, Elasticsearch/OpenSearch, Camunda 7, Camunda 8, and more, visit the getting started section of our configuration documentation.