Camunda BPM Installation Guide (Tomcat)

This document will guide you through the installation of camunda BPM and its components on an Apache Tomcat 7 Server.

1. Download the pre-packaged distribution from http://camunda.org/release/camunda-bpm/tomcat/.
2. Unpack the distro to a directory.
3. Adjust the datasource according to your needs (see below).
4. Startup the server by running camunda-welcome.bat or by using the $TOMCAT_HOME/bin/startup.{bat/sh} script.

Accessing the H2 console

You can easily access the H2 console to inspect your local H2 database (used in demo/evaluation scenarios):

1. Go to http://localhost:8080/h2/h2
2. Login with the following data:
   • jdbc:h2:./camunda-h2-dbs/process-engine
   • User: sa
   • Password: sa

This section will describe how you can install the camunda BPM platform on a vanilla Tomcat 7 server if you are not able to use the pre-packaged Tomcat distribution. Regardless, we recommend that you download a Tomcat 7 distribution to use the required modules.

Create the database schema for the camunda BPM platform

If you do not want to use the H2 database, you first have to create a database schema for the camunda BPM platform. The camunda BPM distribution ships with a set of SQL create scripts that can be executed by a database administrator.

The database creation scripts reside in the sql/create folder:

$TOMCAT_DISTRIBUTION/sql/create/*_engine_$PLATFORM_VERSION.sql $TOMCAT_DISTRIBUTION/sql/create/*_identity_$PLATFORM_VERSION.sql

There is an individual SQL script for each supported database. Select the appropriate script for your database type and run it with your database administration tool. (e.g. SqlDeveloper for Oracle).

Add BPM Bootstrap Server Listener

Add the entry org.camunda.bpm.container.impl.tomcat.TomcatBpmPlatformBootstrap as Listener before the GlobalResourcesLifecycleListener in your $TOMCAT_HOME/conf/server.xml. This class is responsible for starting and stopping the camunda BPM platform as Tomcat is started and stopped.

<Server port="8005" shutdown="SHUTDOWN">
  ...
  <Listener className="org.camunda.bpm.container.impl.tomcat.TomcatBpmPlatformBootstrap" />
  ...

Configuring JDBC Resource

To configure a JDBC Resource you have to edit the file $TOMCAT_HOME/conf/server.xml. This could look like the following example for an H2 database:

<Server>
  ...
  <GlobalNamingResources>
    ...
    <Resource name="jdbc/ProcessEngine"
              auth="Container"
              type="javax.sql.DataSource"
              factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
              uniqueResourceName="process-engine"
              driverClassName="org.h2.Driver"
              url="jdbc:h2:./camunda-h2-dbs/process-engine;MVCC=TRUE;TRACE_LEVEL_FILE=0"
              username="sa"
              password=""
              maxPoolSize="20"
              minPoolSize="5" />
  </GlobalNamingResources>
</Server>

Add necessary libraries to vanilla Tomcat 7

Copy all libraries from the $TOMCAT_DISTRIBUTION/lib/ folder to the Tomcat library folder $TOMCAT_HOME/lib:

Furthermore, you have to merge your corresponding JDBC driver into the folder $TOMCAT_HOME/lib.

Add bpm-platform.xml

You have to add the file bpm-platform.xml to the folder $TOMCAT_HOME/conf or, optionally, you can configure the location through some available mechanisms, see Configure location of the bpm-platform.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform xmlns="http://www.camunda.org/schema/1.0/BpmPlatform"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.camunda.org/schema/1.0/BpmPlatform http://www.camunda.org/schema/1.0/BpmPlatform ">

  <job-executor>
    <job-acquisition name="default" />
  </job-executor>

  <process-engine name="default">
    <job-acquisition>default</job-acquisition>
    <configuration>org.camunda.bpm.engine.impl.cfg.StandaloneProcessEngineConfiguration</configuration>
    <datasource>java:jdbc/ProcessEngine</datasource>

    <properties>
      <property name="history">full</property>
      <property name="databaseSchemaUpdate">true</property>
      <property name="authorizationEnabled">true</property>
      <property name="jobExecutorDeploymentAware">true</property>
    </properties>

  </process-engine>

</bpm-platform>

This section describes how to install optional Camunda dependencies onto a Tomcat server. None of these are required to work with the core platform. Before continuing, make sure that the Camunda BPM platform is already installed according to this step.

The following covers the installation of these extensions:

• Camunda Connect
• Camunda Spin
• Freemarker Integration
• Groovy Scripting

Install Camunda Connect

Add the following artifacts (if not existing) from the folder $TOMCAT_DISTRIBUTION/lib/ to the folder $TOMCAT_HOME/lib/:

• camunda-connect-connectors-all-$CONNECT_VERSION.jar
• camunda-connect-core-$CONNECT_VERSION.jar
• camunda-engine-plugin-connect-$CAMUNDA_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

In order to activate Camunda Connect functionality for a process engine, a process engine plugin has to be registered in $TOMCAT_HOME/conf/bpm-platform.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>

</bpm-platform>

Install Camunda Spin

Add the following artifacts (if not existing) from the folder $TOMCAT_DISTRIBUTION/lib/ to the folder $TOMCAT_HOME/lib/:

• camunda-spin-dataformat-all-$SPIN_VERSION.jar
• camunda-spin-core-$SPIN_VERSION.jar
• camunda-engine-plugin-spin-$CAMUNDA_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

In order to activate Camunda Spin functionality for a process engine, a process engine plugin has to be registered in $TOMCAT_HOME/conf/bpm-platform.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  ...
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>
  ...
</bpm-platform>

Install Groovy Scripting

Add the following artifacts (if not existing) from the folder $TOMCAT_DISTRIBUTION/lib/ to the folder $TOMCAT_HOME/lib/:

• groovy-all-$GROOVY_VERSION.jar

Install Freemarker Integration

Add the following artifacts (if not existing) from the folder $TOMCAT_DISTRIBUTION/lib/ to the folder $TOMCAT_HOME/lib/:

• camunda-template-engines-freemarker-$TEMPLATE_VERSION.jar
• freemarker-2.3.20.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

To install the REST API, a Tomcat installation with the org.camunda.bpm.camunda-engine module is required. See the above section on how to install the pre-built distro or install the platform on a vanilla Tomcat.

Note: The distro already ships the REST API exposing it on the context path /engine-rest.

The following steps are required to deploy the REST API on a Tomcat instance:

1. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION-tomcat.war.
2. Copy the war file to $TOMCAT_HOME/webapps. Optionally you may rename it or extract it to a folder to deploy it to a specific context like /engine-rest.
3. Startup Tomcat.
4. Access the REST API on the context you configured. For example, http://localhost:8080/engine-rest/engine should return the names of all engines of the platform, provided that you deployed the application in the context /engine-rest.

To install camunda Cockpit and Tasklist, a Tomcat installation with the org.camunda.bpm.camunda-engine module is required. See the above section on how to install the pre-built distro or install the platform on a vanilla Tomcat.

Note: The distro already ships the applications. They may be accessed via /camunda/app/cockpit and /camunda/app/tasklist, respectively.

The following steps are required to deploy the applications on a Tomcat instance:

1. Download the camunda web application that contains both applications from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-tomcat-$PLATFORM_VERSION.war.
2. Copy the war file to $TOMCAT_HOME/webapps/camunda.war. Optionally you may name it differently or extract it to a folder to deploy it to a different context path.
3. Startup Tomcat.
4. Access Cockpit and Tasklist via /camunda/app/cockpit and /camunda/app/tasklist or under the context path you configured.

In order to setup LDAP for the tomcat distribution, you have to perform the following steps:

Add the LDAP Library

Make sure the camunda-identity-ldap-$PLATFORM_VERSION.jar is present in the $TOMCAT_DISTRIBUTION/lib/ folder.

Adjust the Process Engine Configuration

Edit the file bpm-platform.xml located inside the folder $TOMCAT_HOME/conf and add the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform xmlns="http://www.camunda.org/schema/1.0/BpmPlatform"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.camunda.org/schema/1.0/BpmPlatform http://www.camunda.org/schema/1.0/BpmPlatform ">
  ...
  <process-engine name="default"> ...
    <properties>...</properties>
    <plugins>
      <plugin>
        <class>org.camunda.bpm.identity.impl.ldap.plugin.LdapIdentityProviderPlugin</class>
        <properties>

          <property name="serverUrl">ldap://localhost:4334/</property>
          <property name="managerDn">uid=jonny,ou=office-berlin,o=camunda,c=org</property>
          <property name="managerPassword">s3cr3t</property>

          <property name="baseDn">o=camunda,c=org</property>

          <property name="userSearchBase"></property>
          <property name="userSearchFilter">(objectclass=person)</property>

          <property name="userIdAttribute">uid</property>
          <property name="userFirstnameAttribute">cn</property>
          <property name="userLastnameAttribute">sn</property>
          <property name="userEmailAttribute">mail</property>
          <property name="userPasswordAttribute">userpassword</property>

          <property name="groupSearchBase"></property>
          <property name="groupSearchFilter">(objectclass=groupOfNames)</property>
          <property name="groupIdAttribute">ou</property>
          <property name="groupNameAttribute">cn</property>

          <property name="groupMemberAttribute">member</property>

        </properties>
      </plugin>
      <plugin>
        <class>org.camunda.bpm.engine.impl.plugin.AdministratorAuthorizationPlugin</class>
        <properties>
          <property name="administratorUserName">admin</property>
        </properties>
      </plugin>
    </plugins>
  </process-engine>
</bpm-platform>

The administratorUserName property should contain the user id of the LDAP user you want to grant administrator authorizations to. You can then use this user to log in to the web application and grant authorizations to additional users.

See our user guide for complete documentation on the LDAP Identity Provider Plugin and the Administrator Authorization Plugin.

Enable Hal Resource caching

If you use LDAP as Indentity Provider, you should consider activating caching of Users and Groups in the camunda webapplication. In order to activate this, add the following configuration to the web.xml file of camunda webapplication (camunda-webapp-tomcat-$PLATFORM_VERSION.war/WEB-INF/web.xml):

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">

  <!-- ... -->

  <listener>
    <listener-class>org.camunda.bpm.engine.rest.hal.cache.HalRelationCacheBootstrap</listener-class>
  </listener>

  <context-param>
    <param-name>org.camunda.bpm.engine.rest.hal.cache.config</param-name>
    <param-value>
      {
        "cacheImplementation": "org.camunda.bpm.engine.rest.hal.cache.DefaultHalResourceCache",
        "caches": {
          "org.camunda.bpm.engine.rest.hal.user.HalUser": {
            "capacity": 100,
            "secondsToLive": 900
          },
          "org.camunda.bpm.engine.rest.hal.group.HalGroup": {
            "capacity": 100,
            "secondsToLive": 900
          }
        }
      }
    </param-value>
  </context-param>

  <!-- ... -->

</web-app>

The following steps describe how to upgrade the Camunda artifacts on a Tomcat server in a shared process engine setting. For the entire migration procedure, refer to the migration guide. If not already done, make sure to download the Camunda BPM 7.2 Tomcat distribution.

The upgrade procedure takes the following steps:

1. Upgrade the Camunda BPM core libraries
2. Upgrade and configure optional Camunda BPM libraries (optional)
3. Configure process engines
4. Upgrade Camunda web applications

In each of the following steps, the identifiers $*_VERSION refer to the current version and the new versions of the artifacts.

1. Upgrade the Camunda BPM Core Libraries

Replace the following libraries in the folder $TOMCAT_HOME/lib/ with their new versions from the folder $TOMCAT_DISTRIBUTION/lib/:

• camunda-engine-$PLATFORM_VERSION.jar
• camunda-bpmn-model-$PLATFORM_VERSION.jar
• camunda-xml-model-$PLATFORM_VERSION.jar
• mybatis-$MYBATIS_VERSION.jar

If present, also replace the following optional artifact:

• camunda-identity-ldap-$PLATFORM_VERSION.jar

Add the following libraries from the folder $TOMCAT_DISTRIBUTION/lib/ to the folder $TOMCAT_HOME/lib/:

• camunda-cmmn-model-$PLATFORM_VERSION.jar

If present, remove the following artifacts:

• camunda-engine-cdi-$PLATFORM_VERSION.jar
• camunda-engine-rest-$PLATFORM_VERSION-classes.jar
• camunda-engine-spring-$PLATFORM_VERSION.jar

Note: The libraries camunda-engine-spring-$PLATFORM_VERSION.jar and camunda-engine-spring-$PLATFORM_VERSION.jar should be part of application deployments and therefore not in the global library folder. Make sure your process applications bundle these libraries when you remove them from the global folder.

2. Upgrade and Configure Optional Camunda BPM libraries

In addition, there are artifacts for Camunda Connect, Camunda Spin, the Freemarker template language and Groovy scripting that may optionally be added to the folder $TOMCAT_HOME/lib/. Since all these artifacts add new functionality, the following steps are not required for migration.

Camunda Connect

If Camunda Connect is intended to be used, add the following artifacts:

• camunda-connect-connectors-all-$CONNECT_VERSION.jar
• camunda-connect-core-$CONNECT_VERSION.jar
• camunda-engine-plugin-connect-$PLATFORM_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

In order to activate Camunda Connect functionality for a process engine, a process engine plugin has to be registered in $TOMCAT_HOME/conf/bpm-platform.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>

</bpm-platform>

Camunda Spin

If Camunda Spin is intended to be used, add the following artifacts:

• camunda-spin-dataformat-all-$SPIN_VERSION.jar
• camunda-spin-core-$SPIN_VERSION.jar
• camunda-engine-plugin-spin-$PLATFORM_VERSION.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

In order to activate Camunda Spin functionality for a process engine, a process engine plugin has to be registered in $TOMCAT_HOME/conf/bpm-platform.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  ...
  <process-engine name="default">
    ...
    <plugins>
      ... existing plugins ...
      <plugin>
        <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
      </plugin>
    </plugins>
    ...
  </process-engine>
  ...
</bpm-platform>

Groovy Scripting

If Groovy is to be used as a scripting language, add the following artifacts:

• groovy-all-$GROOVY_VERSION.jar

Freemarker Integration

If the Camunda integration for Freemarker is intended to be used, add the following artifacts:

• camunda-template-engines-freemarker-$TEMPLATE_VERSION.jar
• freemarker-2.3.20.jar
• camunda-commons-logging-$COMMONS_VERSION.jar
• camunda-commons-utils-$COMMONS_VERSION.jar
• slf4j-api-$SLF4J_VERSION.jar

3. Configure Process Engines

Script Variable Storing

As of 7.2, the default behavior of script variables has changed. Script variables are set in e.g. a BPMN Script Task that uses a language such as JavaScript or Groovy. In previous versions, the process engine automatically stored all script variables as process variables. Starting with 7.2, this behavior has changed and the process engine does not automatically store script variables any longer. You can re-enable the legacy behavior by setting the boolean property autoStoreScriptVariables to true for any process engine in the bpm-platform.xml:

<?xml version="1.0" encoding="UTF-8"?>
<bpm-platform ... ">
  ...
  <process-engine name="default">
    ...
    <properties>
      ... existing properties ...
      <property name="autoStoreScriptVariables">true</property>
    </properties>
    ...
  </process-engine>
  ...
</bpm-platform>

As an alternative, process application developers can migrate script code by replacing all implicit declarations of process variables in their scripts with an explicit call to execution.setVariable('varName', 'value').

4. Upgrade Camunda Web Applications

Upgrade Camunda REST API

The following steps are required to upgrade the camunda REST API on a Tomcat instance:

1. Undeploy an existing web application with a name like camunda-engine-rest
2. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION-tomcat.war.
3. Deploy the web application archive to your Tomcat instance.

Upgrade Camunda Cockpit, Tasklist, and Admin

The following steps are required to upgrade the camunda web applications Cockpit, Tasklist, and Admin on a Tomcat instance:

1. Undeploy an existing web application with a name like camunda-webapp
2. Download the Camunda web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-tomcat-$PLATFORM_VERSION.war.
3. Deploy the web application archive to your Tomcat instance.

The following steps describe how to upgrade the Camunda artifacts on a Tomcat server in a shared process engine setting. For the entire migration procedure, refer to the migration guide. If not already done, make sure to download the Camunda BPM 7.3 Tomcat distribution.

The upgrade procedure takes the following steps:

1. Upgrade the Camunda BPM core libraries
2. Upgrade the optional Camunda BPM libraries
3. Upgrade Camunda web applications

In each of the following steps, the identifiers $*_VERSION refer to the current version and the new versions of the artifacts.

1. Upgrade the Camunda BPM Core Libraries

Replace the following libraries in the folder $TOMCAT_HOME/lib/ with their new versions from the folder $TOMCAT_DISTRIBUTION/lib/:

• camunda-engine-$PLATFORM_VERSION.jar
• camunda-bpmn-model-$PLATFORM_VERSION.jar
• camunda-cmmn-model-$PLATFORM_VERSION.jar
• camunda-xml-model-$PLATFORM_VERSION.jar

2. Upgrade Optional Camunda BPM libraries

In addition to the core libraries, there may be optional artifacts in $TOMCAT_HOME/lib/ for LDAP integration, Camunda Connect, and Camunda Spin. If you use any of these extensions, the following upgrade steps apply:

LDAP integration

Copy the following libraries from $TOMCAT_DISTRIBUTION/lib to the folder $TOMCAT_HOME/lib/ if present:

• camunda-identity-ldap-$PLATFORM_VERSION.jar

Camunda Connect

Copy the following libraries from $TOMCAT_DISTRIBUTION/lib to the folder $TOMCAT_HOME/lib/ if present:

• camunda-connect-connectors-all-$CONNECT_VERSION.jar
• camunda-connect-core-$CONNECT_VERSION.jar
• camunda-engine-plugin-connect-$PLATFORM_VERSION.jar

Camunda Spin

Copy the following libraries from $TOMCAT_DISTRIBUTION/lib to the folder $TOMCAT_HOME/lib/ if present:

• camunda-spin-dataformat-all-$SPIN_VERSION.jar
• camunda-spin-core-$SPIN_VERSION.jar
• camunda-engine-plugin-spin-$PLATFORM_VERSION.jar

3. Upgrade Camunda Web Applications

Upgrade Camunda REST API

The following steps are required to upgrade the camunda REST API on a Tomcat instance:

1. Undeploy an existing web application with a name like camunda-engine-rest
2. Download the REST API web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION-tomcat.war.
3. Deploy the web application archive to your Tomcat instance.

Upgrade Camunda Cockpit, Tasklist, and Admin

The following steps are required to upgrade the camunda web applications Cockpit, Tasklist, and Admin on a Tomcat instance:

1. Undeploy an existing web application with a name like camunda-webapp
2. Download the Camunda web application archive from our Maven Nexus Server. Or switch to the private repository for the enterprise version (User and password from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-tomcat-$PLATFORM_VERSION.war.
3. Deploy the web application archive to your Tomcat instance.