Installation Guide

This document describes the installation process of the Camunda Optimize distribution, as well as various configuration possibilities available after initial installation.

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

Prerequisites

Before installing Optimize, make sure you have a JRE (Java Runtime Environment), or better, a JDK (Java Development Kit) installed if you plan to use the distribution. It is required to install Java version 8.

Download JDK 8

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, please 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 is up running. Then it starts Optimize, ensures it is running and opens automatically a tab in a browser to make it very convenient for you to try out Optimize.

Production Distribution without Elasticsearch

This distribution is intended to be used in production. To install it, first download the production archive, which contains all the required files to startup Camunda Optimize without Elasticsearch. After that configure the Elasticsearch connection to connect to your pre-installed Elasticsearch instance and configure the Camunda BPM Platform connection to connect Optimize to your running engine. You can then 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

Production Docker image without Elasticsearch

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 Elasticsearch connection to connect to your pre-installed Elasticsearch instance and configure the Camunda BPM Platform connection to connect Optimize to your running engine. For very simple use cases with only one Camunda Engine and one Elastichsearch 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 BPM as well as Elasticsearch instance you could run the following command:

docker run -d --name optimize --network host \
           registry.camunda.cloud/optimize-ee/optimize:3.0.0

Connect to remote Camunda BPM and Elasticsearch

If however your Camunda BPM 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:3.0.0

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 to follow the setup in section 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 BPM REST API as well as Elasticsearch:

• OPTIMIZE_CAMUNDABPM_REST_URL base URL that will be used for connections to the Camunda Engine REST API (default: http://localhost:8080/engine-rest)
• OPTIMIZE_CAMUNDABPM_WEBAPPS_URL endpoint where to find the camunda webapps for the given engine (default: http://localhost:8080/camunda)
• OPTIMIZE_ELASTICSEARCH_HOST the address/hostname under which the Elasticsearch node is available (default: localhost)
• OPTIMIZE_ELASTICSEARCH_HTTP_PORT port number used by Elasticsearch to accept HTTP connections (default: 9200)

A complete sample can be found here Connect to remote Camunda BPM and Elasticsearch.

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)
• OPTIMIZE_EVENT_INGESTION_ACCESS_TOKEN secret token to be provided on the Ingestion REST API when ingesting data.

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 ABSOLUTE_PATH_ON_HOST_TO_LICENSE_FILE 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 ABSOLUTE_PATH_ON_HOST_TO_LICENSE_FILE:/optimize/environment/OptimizeLicense.txt:ro \
           registry.camunda.cloud/optimize-ee/optimize:3.0.0

Configuration using a environment-config.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. Please refer to the Configuration section of the documentation for the available configuration parameters.

Similar to the license key file you then need to mount this configuration file into the Optimize Docker container to apply it. Replacing the ABSOLUTE_PATH_ON_HOST_TO_CONFIGURATION_FILE 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 ABSOLUTE_PATH_ON_HOST_TO_CONFIGURATION_FILE:/optimize/environment/environment-config.yaml:ro \
           registry.camunda.cloud/optimize-ee/optimize:3.0.0

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 Platform to login to Optimize. For details on how to configure the user access, please consult the user access management section.

Before you can fully utilize all features of Optimize, you need to wait until all data has been imported. A green circle in the footer indicates, when the import is finished.

Configuration

All distributions of Optimize come with a predefined set of configuration options that can be overwritten by the user, based on current environment requirements. To do that, have a look into the folder named environment. There are two files, one called environment-config.yaml with values that override the default Optimize properties and another called environment-logback.xml, which sets the logging configuration.

You can see all supported values and read about logging configuration here.

Optimize Web Container Configuration

The following YAML Paths correspond to settings available in the environment configuration.

• container.ports.http - A port number that is used by the embedded jetty server to process HTTP connections

Default value: `8090`

• container.host - You can configure a host either by host name or IP address, to identify a specific network interface on which to listen

Default value: `0.0.0.0`

Elasticsearch configuration

You can customize the Elasticsearch connection settings used by Optimize by changing the following properties:

• Define one or more Elasticsearch nodes Optimize can connect to:

  • es.connection.nodes.host - The address/hostname under which the Elasticsearch node is available.

  Default value: 'localhost'

• es.connection.nodes.httpPort - The port number used by the Elasticsearch node to accept HTTP connections.

  Default value: '9200'

• es.settings.index.prefix - Define a prefix to be prepended to all indexes and aliases created by Optimize, this allows to have multiple isolated Optimize instances running that use one Elasticsearch cluster. For more details see Shared Elasticsearch Cluster. Default value: 'optimize'

Camunda BPM configuration

To perform an import and provide the full set of features, Optimize requires connection to the REST API of the Camunda engine, which can be configured using the following properties.

• engines.\${engineAlias}.rest - A base URL that will be used for connections to the Camunda Engine REST API

Default value: `http://localhost:8080/engine-rest`

• engines.\${engineAlias}.name - The name of the engine that will be used to import data

Default value: `default`

Import of the data set

By default, Optimize comes without any data available. To start using all the features of the system, you have to perform a data import from the Camunda BPM Platform. This process is triggered automatically on start.

If you are interested in the details of the import, please refer to the dedicated import overview section.

Hardware Resources

According to the tests with different data sets described on import overview page we can recommend to carefully choose hardware resources that are allocated to the server with Optimize.

We recommend following minimum hardware for data sets:

Small Size Of Data (less than 1 million process instances)

• Camunda Optimize:
  • 2 CPU Threads
  • 512 MB RAM
• Elasticsearch:
  • 2 CPU Threads
  • 1 GB RAM

Medium Size Of Data (more than 1 million and up to 2 million process instances)

• Camunda Optimize:
  • 2 CPU Threads
  • 1 GB RAM
• Elasticsearch:
  • 2 CPU Threads
  • 2 GB RAM
  • local SSD storage recommended

Large Size Of Data (2 million process instances or more)

• Camunda Optimize:
  • 2 CPU Threads
  • 2 GB RAM
• Elasticsearch:
  • 4 CPU Threads
  • 6 GB RAM
  • local SSD storage

Please be aware, that Optimize is using data structures that are different from data stored by the Camunda BPM Engine. The final amount of space on the hard drive required by Optimize will depend on your replication settings, but as a rule of thumb you could expect Optimize to use 30% of the space that your relational database is using.

Recommended Additional Configurations

Adjust engine heap size

Sending huge process definition diagrams via Rest-API might cause the engine to crash, because of the limited heap size. Thus, it is recommended to increase the heap size of the engine to at least 2 gigabyte or preferably more, e.g., by adding the following java command line property when starting the engine:

-Xmx2048m

Also it is recommended to decrease the deployment cache size to 500, e.g. by:

<property name="cacheCapacity" value="500" />

Adjust Optimize heap size

By default Optimize is configured with 1GB JVM heap memory. Depending on your setup and actual data you might still encounter situations where you need more than this default for a seamless operation of Optimize. To increase the maximum heap size you can set the environment variable JAVA_SYSTEM_PROPERTIES and provide the desired JVM system properties, e.g. for 2GB of Heap:

JAVA_SYSTEM_PROPERTIES=-Xmx2048m

Maximum result limits for queries

It’s possible that engine queries consume a lot of memory. To mitigate this risk, you can limit the number of results a query can return. In case you do that, it’s highly recommended that you set the value of the queryMaxResultsLimit setting to 10000 so that Optimize import works without any problems. Also, this should still be low enough so you don’t run into any problems with the previously mentioned heap configurations.