Edit on Github

Install the Full Distribution on a JBoss EAP/Wildfly Application Server manually

This document describes the installation of Camunda Platform and its components on a vanilla Wildfly Application Server / JBoss EAP 7.

Reading this Guide

This guide uses a number of variables to denote common path names and constants: $WILDFLY_HOME points to the JBoss EAP/Wildfly application server main directory. $PLATFORM_VERSION denotes the version of the Camunda Platform you want to install or already have installed, e.g. 7.0.0.

Required Setup for Wildfly / JBoss EAP 7

This section explains how to perform the required setup steps for Wildfly Application Server.

First, you need to download the Camunda WildFly distribution.

Copy Modules

Copy the modules from the modules/ folder of the Camunda distribution, or extract the camunda-wildfly-modules archive, to the $WILDFLY_HOME/modules/ of your Wildfly application server.

Replace H2 Database

The WildFly distribution ships a different version of the H2 database than the one that is shipped with Wildfly itself. The version shipped with Camunda is the version that the process engine is tested on and it is strongly recommended to use Camunda’s version. To do so, make sure to delete the folder

$WILDFLY_HOME/modules/system/layers/base/com/h2database

Adjust the Configuration

Next, a number of changes need to be performed in the application server’s configuration file. In most cases this is $WILDFLY_HOME/standalone/configuration/standalone.xml.

Add the Camunda subsystem as extension:

<server xmlns="urn:jboss:domain:2.1">
  <extensions>
    ...
    <extension module="org.camunda.bpm.wildfly.camunda-wildfly-subsystem"/>

Configure the thread pool for the Camunda Platform Job Executor:

Since Camunda Platform 7.5, the configuration of the thread pool is done in the Camunda subsystem, not in the JBoss Threads subsystem anymore like it was done before 7.5. The thread pool creation and shutdown is now controlled through the Camunda subsystem. You are able to configure it through the following new configuration elements in the job-executor element of the subsystem XML configuration.

Mandatory configuration elements are:

  • <core-threads>3</core-threads>
  • <max-threads>5</max-threads>
  • <queue-length>10</queue-length>

Optional configuration elements are:

  • <keepalive-time>10</keepalive-time> (in seconds)
  • <allow-core-timeout>true</allow-core-timeout>

Shown values are the default ones.

The below example also configures the default process engine.

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  <process-engines>
    <process-engine name="default" default="true">
      <datasource>java:jboss/datasources/ProcessEngine</datasource>
      <history-level>full</history-level>
      <properties>
        <property name="jobExecutorAcquisitionName">default</property>
        <property name="isAutoSchemaUpdate">true</property>
        <property name="authorizationEnabled">true</property>
        <property name="jobExecutorDeploymentAware">true</property>
      </properties>
    </process-engine>
  </process-engines>
  <job-executor>
    <core-threads>3</core-threads>
    <max-threads>5</max-threads>
    <queue-length>10</queue-length>
    <job-acquisitions>
      <job-acquisition name="default">
        <properties>
          <property name="lockTimeInMillis">300000</property>
          <property name="waitTimeInMillis">5000</property>
          <property name="maxJobsPerAcquisition">3</property>
        </properties>
      </job-acquisition>
    </job-acquisitions>
  </job-executor>
</subsystem>

Create the Database Schema

By default, the database schema is automatically created in an H2 database when the engine starts up for the first time. If you do not want to use the H2 database, you have to

  • Create a database schema for the Camunda Platform yourself.
  • Install the database schema to create all required tables and default indices using our database schema installation guide.

When you create the tables manually, then you can also configure the engine to not create tables at startup by setting the isAutoSchemaUpdate property to false (or, in case you are using Oracle, to noop). In WildFly, this is done in the standalone.xml, located in the $WildFly_DISTRIBUTION\server\WildFly-$VERSION\standalone\configuration\ folder.

Create a Datasource

You need to create a datasource named java:jboss/datasources/ProcessEngine. The following datasource shows an example of using the built in H2 database for this, using a file within the ./ folder, typically bin.

<datasource jta="true" enabled="true" use-java-context="true" use-ccm="true"
            jndi-name="java:jboss/datasources/ProcessEngine"
            pool-name="ProcessEngine">
  <connection-url>jdbc:h2:./camunda-h2-dbs/process-engine;DB_CLOSE_DELAY=-1;MVCC=TRUE;DB_CLOSE_ON_EXIT=FALSE</connection-url>
  <driver>h2</driver>
  <security>
    <user-name>sa</user-name>
    <password>sa</password>
  </security>
</datasource>

Using H2 as a database is ideal for development purposes but is not recommended for usage in a productive environment. These links point you to resources for other databases:

Optional Components

This section describes how to install optional dependencies. None of these are required to work with the core platform. Before continuing, make sure that the Camunda Platform is already installed according to this step for WildFly / JBoss EAP 7.

Cockpit, Tasklist and Admin

The following steps are required to deploy the web application:

  1. Download the Camunda web application that contains both applications from our Maven Nexus Server. Alternatively, switch to the private repository for the enterprise version (credentials from license required). Choose the correct version named $PLATFORM_VERSION/camunda-webapp-jboss-$PLATFORM_VERSION.war.
  2. Optionally, you may change the context path to which the application will be deployed (default is /camunda). Edit the file WEB-INF/jboss-web.xml in the war file and update the context-root element accordingly.
  3. Copy the war file to $WILDFLY_HOME/standalone/deployments.
  4. Startup Wildfly.
  5. Access Cockpit, Tasklist and Admin via /camunda/app/cockpit, /camunda/app/tasklist and /camunda/app/admin, or under the context path you configured.

REST API

The following steps are required to deploy the REST API:

  1. Download the REST API web application archive from our Maven Nexus Server. Alternatively, switch to the private repository for the enterprise version (credentials from license required). Choose the correct version named $PLATFORM_VERSION/camunda-engine-rest-$PLATFORM_VERSION.war.
  2. Optionally, you may change the context path to which the REST API will be deployed (default is /engine-rest). Edit the file WEB-INF/jboss-web.xml in the war file and update the context-root element accordingly.
  3. Copy the war file to $WILDFLY_HOME/standalone/deployments.
  4. Startup Wildfly.
  5. Access the REST API on the context path 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.

Camunda Connect Plugin

Add the following modules (if not existing) from the folder $WILDFLY_DISTRIBUTION/modules/ to the folder $WILDFLY_HOME/modules/:

  • org/camunda/bpm/camunda-engine-plugin-connect
  • org/camunda/commons/camunda-commons-utils

To activate Camunda Connect functionality for a process engine, a process engine plugin has to be registered in $WILDFLY_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.connect.plugin.impl.ConnectProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

Camunda Spin

The Camunda Spin plugin can be use to extend the engine functionality to de-/serialize object variables from and to JSON and XML. For more information, see the Spin Reference.

Setup Spin

Add the following modules (if not existing) from the folder $WILDFLY_DISTRIBUTION/modules/ to the folder $WILDFLY_HOME/modules/:

  • org/camunda/spin/camunda-spin-core
  • org/camunda/spin/camunda-spin-dataformat-json-jackson
  • org/camunda/spin/camunda-spin-dataformat-xml-dom
  • org/camunda/bpm/camunda-engine-plugin-spin
  • org/camunda/commons/camunda-commons-utils
  • com/fasterxml/jackson/core/jackson-core
  • com/fasterxml/jackson/core/jackson-databind
  • com/fasterxml/jackson/core/jackson-annotations
  • com/jayway/jsonpath/json-path

In order to activate Camunda Spin functionality for a process engine, a process engine plugin has to be registered in $WILDFLY_HOME/standalone/configuration/standalone.xml as follows:

<subsystem xmlns="urn:org.camunda.bpm.jboss:1.1">
  ...
  <process-engines>
    <process-engine name="default" default="true">
      ...
      <plugins>
        ... existing plugins ...
        <plugin>
          <class>org.camunda.spin.plugin.impl.SpinProcessEnginePlugin</class>
        </plugin>
      </plugins>
      ...
    </process-engine>
  </process-engines>
  ...
</subsystem>

Problems with Jackson Annotations

The usage of Jackson annotations on WildFly together with the Camunda Spin JSON serialization can lead to problems. WildFly implicitly adds the JAX-RS subsystem to each new deployment, if JAX-RS annotations are present (see the WildFly documentation for more information). This JAX-RS subsystem includes the Jackson library, the version of which does not match with the version used by the Camunda SPIN Plugin. As a result, Jackson annotations will be ignored. Note that this problem does not necessarily have to emerge upon direct usage of Spin. The Spin plugin also comes into play when JSON variables are set or read by the Camunda Process Engine.

See one of the following ways to fix this:

  1. Change the Jackson main slot to the version which is used by the Camunda Spin Plugin.

    • Make sure that Resteasy can work with this Jackson version, as we cannot give any guarantees on this.

  2. Exclude implicitly added JAX-RS dependencies.

    • Add a jboss-deployment-structure.xml file to you application in the WEB-INF folder.
    • Exclude the JAX-RS subsystem and add the Jackson dependencies, with the version which is used by the Camunda Spin Plugin.
    • This solution is also shown in the Jackson Annotation Example for WildFly in the Camunda example repository.

See this Forum Post for other approaches and information.

Problem With Deployments Using the REST API

Camunda Spin is not available in scripts if a process definition is deployed via REST API. Because Wildfly handles dependencies using its module system and camunda engine module has no module dependency on the spin module.

Groovy Scripting

Add the following modules (if not existing) from the folder $WILDFLY_DISTRIBUTION/modules/ to the folder $WILDFLY_HOME/modules/:

  • org/codehaus/groovy/groovy-all

Freemarker Integration

Add the following modules (if not existing) from the folder $WILDFLY_DISTRIBUTION/modules/ to the folder $WILDFLY_HOME/modules/:

  • org/camunda/template-engines/camunda-template-engines-freemarker
  • org/freemarker/freemarker
  • org/camunda/commons/camunda-commons-logging
  • org/camunda/commons/camunda-commons-utils

GraalVM JavaScript Integration

Add the following modules (if not existing) from the folder $WILDFLY_DISTRIBUTION/modules/ to the folder $WILDFLY_HOME/modules/:

  • org/graalvm/js/js
  • org/graalvm/js/js-scriptengine
  • org/graalvm/regex/regex
  • org/graalvm/sdk/graal-sdk
  • org/graalvm/truffle/truffle-api
  • com/ibm/icu/icu4j

On this Page: