This guide gives an introduction to Camunda Platform Run, a pre-packaged, lightweight distribution of the Camunda Platform. Camunda Platform Run is easy to configure and does not require Java knowledge.

Prerequisites and audience

To use this guide, you should at least know what Camunda Platform is and what it does. Check out the Get Started guides if you have never used Camunda Platform before. The Installation guide is also worth looking at if you are completely new to Camunda Platform.

This guide will teach you about Camunda Platform Run and how to configure it. It can serve as a reference page for configuration and operation options. It will not give you a step-by-step guide on how to install Camunda Platform Run. Head over to the Installation guide for details on how to install and start Camunda Platform Run.

What is Camunda Platform Run?

Camunda Platform Run is a full distribution of the Camunda Platform. It includes:

• Camunda web applications
  • Cockpit
  • Tasklist
  • Admin
• REST API
• Swagger UI (web application for exploring the REST API)
• An example application

Starting with Camunda Platform Run

To start with Camunda Platform Run, download the distribution (enterprise) and unpacking it. You will find the following structure:

camunda-bpm-run
├── configuration/
│   ├── keystore/
│   │   └── put your SSL key store here if you want to use HTTPS
│   ├── resources/
│   │   └── put your BPMN files, forms and scripts here
│   ├── sql/
│   │   └── necessary SQL scripts to prepare your database system
│   ├── userlib/
│   │   └── put your database driver and other required JARs here
│   ├── default.yml
│   └── production.yml
├── internal/
├── start.bat
└── start.sh

Execute one of the two start scripts (start.bat for Windows, start.sh for Linux/Mac). After a few seconds, you will be able to access the Camunda webapps via http://localhost:8080/camunda/app/, the REST API via http://localhost:8080/engine-rest/ and Swagger UI via http://localhost:8080/swaggerui/.

Starting Camunda Platform Run using Docker

Camunda Platform Run is also available as a Docker image. Please see the Camunda Platform Run section of the Camunda Docker documentation here for more details.

Optional components

By default, Camunda Platform Run launches with the web apps, REST API, Swagger UI, and example modules. If you want to enable only a subset of them, execute the start script through a command-line interface with any of the --webapps, --rest, --swaggerui, or --example properties to enable the specific modules.

Example application

By default, Camunda Platform Run deploys and launches an example application on startup. When launched, this application creates deployments with multiple BPMN and DMN definitions as well as form resources and starts instances of the defined processes.

You can disable the deployment of the example application itself by enabling any combination of the other modules with the --webapps, --rest, and --swaggerui properties of the start script. That way, the example application will not be launched and its resources will not be present on the classpath of Camunda Run.

You can also disable the launch of the example application by setting the application property camunda.bpm.run.example.enabled to false or removing it from the application properties. That way, the example application and its resources will be present on the classpath of Camunda Run. However, the example application will not be started.

Disabling the example application with any of those mechanisms will NOT delete any deployments or process instances from Camunda Run once they are created. You have to delete this data manually through the web apps, the REST API, or by cleaning the database configured in the application properties.

Choose between default and production configuration

Camunda Platform Run ships with two different configuration files which are both located in the configuration folder.

• The default.yml configuration only contains necessary configuration like the H2 database, a demo user and CORS for REST calls from a client application.
• The production.yml configuration is intended to provide the recommended properties according to the Security Instructions. When using Camunda Platform Run in a production environment, make sure to base your custom configuration on this one and carefully read through the security instructions.

By default, Run launches with the default.yml configuration. To enable the production.yml configuration, execute the start script with the --production property. Using --production disables Swagger UI and the example application. They can be enabled by explicitly passing --swaggerui and --example to the start script. However, we do not recommended to use Swagger UI and the exmaple application in production.

Connect to a Database

Camunda Platform Run is pre-configured to use a file-based H2 database for testing. The database schema and all required tables are automatically created when the engine starts up for the first time. If you want to use a custom standalone database, follow these steps:

1. Make sure your database is among the supported database systems.
2. Create a database schema for the Camunda Platform yourself.
3. Install the database schema to create all required tables and default indices using our database schema installation guide.
4. Drop a JDBC driver jar for your database system in the configuration/userlib folder.
5. Add the JDBC URL and login credentials to the configuration file like described below.
6. Restart Camunda Platform Run

Deploy BPMN Models

In the unpacked distro, you will find a resources folder. All files (including BPMN, DMN, CMMN, form, and script files) will be deployed when you start Camunda Platform Run.

You can reference forms and scripts in the BPMN diagram with embedded:deployment:/my-form.html, camunda-forms:deployment:/myform.form, or deployment:/my-script.js. The deployment requires adding an extra / as a prefix to the filename.

Deployments via the REST API are still possible.

Automatic License Pickup

If you downloaded the enterprise version of Camunda Platform Run, you will need a license key to enable the enterprise features. Please see the dedicated License section of the docs, to learn more.

Configure Camunda Platform Run

Just like all the other distros, you can tailor Camunda Platform Run to your needs. To do this, you only have to edit one of the configuration files that you can find in the configuration folder.

Database

The distro comes with a file-based h2 database for testing. It is recommended to connect to a standalone database system for use in production.

Prefix	Property name	Description	Default value
spring.datasource	.url	The jdbc URL for the database.	-
	.driver-class-name	The class name of the JDBC driver for your database system. Remember to put the driver jar for your database system in configuration/userlib.	-
	.username	The username for the database connection.	-
	.password	The password for the database connection.	-

Authentication

To add authentication to requests against the REST API, you can enable basic authentication.

Prefix	Property name	Description	Default value
camunda.bpm.run.auth	.enabled	Switch to enable basic authentication for requests to the REST API.	false
	.authentication	Authentication method, currently only basic is supported.	basic

Cross-Origin Resource Sharing

If you want to allow cross-origin requests to the REST API, you need to enable CORS.

Prefix	Property name	Description	Default value
camunda.bpm.run.cors	.enabled	Switch to enable CORS.	false
	.allowed-origins	Origins that are allowed to make CORS requests. Multiple origins can be separated with commas. To support both HTTP authentication and CORS, allowed-origins must not be *. To allow Camunda Modeler to deploy with authentication, including file:// in the allowed origins.	* (all origins, including file://)

LDAP Identity Service

Camunda Platform can manage users and authorizations on its own, but if you want to use an existing LDAP authentication database you can enable the LDAP Identity Service Plugin which provides read-only access to the LDAP repository.

Find all available configuration properties in the LDAP Plugin Guide

Prefix	Property name	Description	Default value
camunda.bpm.run.ldap	.enabled	Switch to enable the LDAP identity service plugin.	false

Example application launch

Camunda Platform Run comes with a demo application that deploys resources and starts process instances. You can disable the start of that application so it does not create deployments and process instances. The resources of the application are however still accessible on the classpath of Camunda Run. Consult the example application section for further details.

Prefix	Property name	Description	Default value
camunda.bpm.run.example	.enabled	Switch to enable the example application.	false

HTTPS

Camunda Platform Run supports HTTPS over SSL. To enable it, you will need a valid SSL certificate signed by a trusted provider and stored in a key store file (either .jks or .p12). For testing, we included a self-signed certificate. You should not use this in production. To enable it, add the following properties to your configuration file.

server:
  ssl:
    key-store: classpath:keystore.p12
    key-store-password: camunda
    key-store-type: pkcs12
    key-alias: camunda
    key-password: camunda
  port: 8443

After starting Camunda Platform Run, you can access the webapps via https://localhost:8443/camunda/app/ and the REST API via https://localhost:8443/engine-rest/.

Prefix	Property name	Description	Default value
server.ssl	.key-store	Name of the key store file that holds the SSL certificate. This file must be placed in the configuration/keystore folder and has to be either a .jks or a .p12 file.	-
	.key-store-password	Password to access the key store.	-
	.key-store-type	Type of the key store. Can either be jks or p12	-
	.key-alias	Name that identifies the SSL certificate in the key store.	-
	.key-password	Password to access the SSL certificate in the key store.	-

Logging

Camunda Platform provides fine-grained and customizable logging. An overview of the available logging categories can be found in the Logging User Guide. To configure the logging behavior in Camunda Platform Run, customize your configuration file with the following properties.

For more information on logging configuration visit the Spring Boot Logging Guide.

Prefix	Property name	Description	Default value
logging	.level.root	Set a logging level for all available logging categories. Value can be one of the following: OFF. ERROR. WARN. INFO. DEBUG. ALL	-
	.level.{logger-name}	Set a logging level for a specific logging category. Find an overview over the available categories in the Logging User Guide. Value can be one of the following: OFF. ERROR. WARN. INFO. DEBUG. ALL	-
	.file.name	Specify a log file location. (e.g. logs/camunda-bpm-run-log.txt)	-