camunda BPM Installation Guide (Tomcat)

Overview

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

Reading the Guide
Throughout this guide we will use a number of variables to denote common path names and constants:
$TOMCAT_HOME points to the main directory of the tomcat server.
$PLATFORM_VERSION denotes the version of the camunda BPM platform you want to install or already have installed, e.g. 7.0.0.
$TOMCAT_DISTRIBUTION represents the downloaded pre-packaged camunda BPM distribution for Tomcat, e.g. camunda-bpm-tomcat-$PLATFORM_VERSION.zip or camunda-bpm-tomcat-$PLATFORM_VERSION.tar.gz.

Install the pre-built distro

  1. Download the pre-packaged distribution from http://www.camunda.org/download/camunda-bpm/tomcat/VERSION/zip/. Replace VERSION with the current camunda BPM version.
  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.

Install the platform on a vanilla Tomcat

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>

Install the REST API web application

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.

Install camunda Cycle

The distro already ships camunda Cycle. It may be accessed on the context path /cycle. Here you can see how to configure the distro.

Note

We do not recommend to install camunda Cycle together with the other platform components (webapps, engine, REST API) on the same runtime environment. Such a combined installation is not supported.

Create the database schema for camunda Cycle

Unless you are using the pre-packaged distribution and do not want to exchange the packaged H2 database, you first have to create a database schema for camunda Cycle. 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:

camunda-bpm-tomcat-$PLATFORM_VERSION.zip/sql/create/*_cycle_$PLATFORM_VERSION.sql

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

We recommend to create a separate database or database schema for camunda Cycle.

If you have not got the distro at hand, you can also download a file that packages these scripts from our server. Choose the correct version named $PLATFORM_VERSION/camunda-cycle-sql-scripts-$PLATFORM_VERSION.war.

Configuring the pre-packaged distribution

The distribution comes with a preconfigured H2 database used by Cycle.

The H2 JDBC driver is located at camunda-bpm-tomcat-$PLATFORM_VERSION.zip/server/apache-tomcat-VERSION/lib/h2-VERSION.jar.

Exchange the database

To exchange the preconfigured H2 database with your own, e.g. Oracle, you have to do the following:

  1. Copy your JDBC database driver JAR file to $TOMCAT_HOME/lib.
  2. Open $TOMCAT_HOME/webapps/cycle/META-INF/context.xml and edit the properties of the jdbc/CycleDS datasource definition.

Install camunda Cycle on vanilla Tomcat 7

You can download the camunda Cycle web application from our server. Choose the correct version named $PLATFORM_VERSION/camunda-cycle-tomcat-$PLATFORM_VERSION.war.

Create a datasource

The Cycle datasource is configured in the Cycle web application in the file META-INF/context.xml. It should be named jdbc/CycleDS.

In order to use a custom datasource name, you have to edit the file WEB-INF/classes/META-INF/cycle-persistence.xml in the Cycle web application file.

In order to use the org.apache.tomcat.jdbc.pool.DataSourceFactory, you need to add the driver of the database you use to the $TOMCAT_HOME/lib folder. For example, if you plan to use the H2 database, you would have to add the h2-VERSION.jar.

Tomcat 6.x
On Tomcat 6, you will also have to add the tomcat-jdbc.jar, which ships with Tomcat 7 and the pre-packaged camunda BPM distribution, to $TOMCAT_HOME/lib.

Install the web application

  1. Copy the Cycle 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 /cycle.
  2. Startup Tomcat.
  3. Access camunda Cycle on the context you configured. If Cycle is installed correctly, a screen should appear that allows you to create an initial user. The initial user has administrator privileges and can be used to create more users once you have logged in.

Configuring Cycle

Configuring email

Note: This step is optional and can be skipped if you do not require Cycle to send a welcome email to newly created users.

You need to install the java mail library when NOT using the prepackaged distribution. Download version 1.4.x manually from http://mvnrepository.com/artifact/javax.mail/mail and copy it into your $TOMCAT_HOME/lib folder.

In order to use the Cycle email service, you have to configure a mail session in the META-INF/context.xml file in the Cycle web application.

By default, Cycle looks up a mail session using the JNDI Name mail/Session. The name of the mail session to look up can be changed by editing the following file in the Cycle web application:

WEB-INF/classes/spring/configuration.xml

The file defines a Spring Bean named cycleConfiguration. On this spring bean, set the JNDI name of the Mail Session to a custom name:

<bean id="cycleConfiguration" class="org.camunda.bpm.cycle.configuration.CycleConfiguration">
  <!-- ... -->
  <!-- Cycle email service configuration -->
  <property name="emailFrom" value="cycle@localhost" />
  <property name="mailSessionName" value="my/mail/Session" />
  <!-- ... -->
</bean>

Configuring Connector Password Encryption

Connector passwords are encrypted before they are stored in the Cycle database using the PBEWithMD5AndDES algorithm implementation.

Encryption key
Cycle uses a default key to encrypt passwords (contained in the source code and hence not really secure). If you want to improve security you can exchange the encryption password by creating a file $USER_HOME/cycle.password containing a self chosen plain ASCII password.

Install camunda Cockpit and Tasklist

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.

Configuring LDAP for camunda Cockpit and Tasklist

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

1. Add LDAP Library

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

2. Adjust 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.