This document will guide you through the installation of camunda BPM and its components on an Apache Tomcat 7 Server.
$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
.
camunda-welcome.bat
or by using the $TOMCAT_HOME/bin/startup.{bat/sh}
script.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.
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 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" />
...
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>
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
.
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>
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:
$PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION-tomcat.war
.$TOMCAT_HOME/webapps
.
Optionally you may rename it or extract it to a folder to deploy it to a specific context like /engine-rest
./engine-rest
.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.
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.
$PLATFORM_VERSION/camunda-cycle-sql-scripts-$PLATFORM_VERSION.war
.
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
.
To exchange the preconfigured H2 database with your own, e.g. Oracle, you have to do the following:
$TOMCAT_HOME/lib
.$TOMCAT_HOME/webapps/cycle/META-INF/context.xml
and edit the properties of the jdbc/CycleDS
datasource definition.You can download the camunda Cycle web application from our server.
Choose the correct version named $PLATFORM_VERSION/camunda-cycle-tomcat-$PLATFORM_VERSION.war
.
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_HOME/lib
.
$TOMCAT_HOME/webapps
.
Optionally you may rename it or extract it to a folder to deploy it to a specific context like /cycle
.Note: This step is optional and can be skipped if you do not require Cycle to send a welcome email to newly created users.
$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>
Connector passwords are encrypted before they are stored in the Cycle database using the PBEWithMD5AndDES algorithm implementation.
$USER_HOME/cycle.password
containing a self chosen plain ASCII password.
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:
$PLATFORM_VERSION/camunda-webapp-tomcat-$PLATFORM_VERSION.war
.$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./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:
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.