KIE Server welcomes Narayana

KIE Server (with BPM capabilities) requires data base for persistence. That is well known fact, though to have properly managed persistence there is also need for transaction manager that will ensure consistency of the data jBPM persists.

Since version 7 KIE Server is the only provided out of the box execution server (there is no execution server in workbench) so it got some additional attention to make sure it does perform in the best possible way.

KIE Server supports following runtime environments:

• WildFly 10.x
• EAP 7.x
• WebSphere 9
• WebLogic 12.3
• Tomcat 8.x

Since all of the above are supported for jBPM usage they all must provide transaction manager capability. For JEE servers (WildFly, EAP, WebSphere, WebLogic) KIE server relies on what the application server provides. Though for Tomcat the story is slightly different...

Tomcat does not have transaction manager capabilities so to make use of jBPM/KIE Server on it, it required an external transaction manager to be configured. Until now it was recommended to use bitronix as jBPM test suite was running on it and it does provide integration with Tomcat (plus it covered db connection pooling and JNDI provider for data source look ups). But this has now changed ...

Starting from jBPM 7.1 KIE Server on Tomcat runs with Narayana, the state of the art transaction manager that nicely integrates with Tomcat and makes the configuration much easier than what was needed with bitronix - and is more native to Tomcat users.

Before I jump into details on how to configure it on Tomcat, I'd like to take the opportunity and give spacial thanks to:

Tom Jenkinson and Gytis Trikleris

for their tremendous help and excellent support while working on this change.

Installation notes - with BPM capabilities

Let's see what is actually needed to configure KIE Server on Tomcat with Narayana:

• (1) Copy following libraries into TOMCAT_HOME/lib
• javax.security.jacc:javax.security.jacc-api
• org.kie:kie-tomcat-integration
• org.slf4j:artifactId=slf4j-api
• org.slf4j:artifactId=slf4j-jdk14
• (2) Configure users and roles in tomcat-users.xml (or different user repository if applicable)
• (3) Configure JACC Valve for security integration Edit TOMCAT_HOME/conf/server.xml and add following in Host section after last Valve declaration 

         <Valve className="org.kie.integration.tomcat.JACCValve" />

• (4) Create setenv.sh|bat in TOMCAT_HOME/bin with following content

    CATALINA_OPTS="

    -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry 

    -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/jbpm 

    -Djbpm.tm.jndi.lookup=java:comp/env/TransactionManager 

    -Dorg.kie.server.persistence.tm=JBossTS 

    -Dhibernate.connection.release_mode=after_transaction 

    -Dorg.kie.server.id=tomcat-kieserver 

    -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server 

    -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller

    "

       Items marked in green are related to persistence and transaction.
       Items marked in blue are general KIE Server parameters needed when running in managed mode.

• (5) Copy JDBC driver jar into TOMCAT_HOME/lib depending on the data base of your choice
• (6) Configure data source for jBPM extension of KIE Server 

           Edit TOMCAT_HOME/conf/context.xml and add following within Context tags of the file:

     <Resource 

           name="sharedDataSource" 

           auth="Container" 

           type="org.h2.jdbcx.JdbcDataSource" 

           user="sa" 

           password="sa"

           url="jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;MVCC=TRUE" 

           description="H2 Data Source" 

           loginTimeout="0" 

           testOnBorrow="false"

           factory="org.h2.jdbcx.JdbcDataSourceFactory"/>

           This is only an example to use H2 as data base, for other data bases look at

           Tomcat's configurations docs.

           Once important note, please keep the name of the data source as sharedDataSource

• (7) Last but not least is to configure XA recovery 
Create xa recovery file next to the context.xml with data base configuration with following content: 

<?xml version="1.0" encoding="UTF-8"?> 

<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> 

<properties> 

  <entry key="DB_1_DatabaseUser">sa</entry> 

  <entry key="DB_1_DatabasePassword">sa</entry> 

  <entry key="DB_1_DatabaseDynamicClass"></entry> 

  <entry key="DB_1_DatabaseURL">java:comp/env/h2DataSource</entry> 

</properties> 

Append to CATALINA_OPTS in setenv.sh|bat file following: 

    -Dcom.arjuna.ats.jta.recovery.XAResourceRecovery1= \

    com.arjuna.ats.internal.jdbc.recovery.BasicXARecovery\;

    abs://$CATALINA_HOME/conf/xa-recovery-properties.xml\ \;1

BasicXARecovery supports following parameters: 
• path to the properties file 
• the number of connections defined in the properties file

Installation notes - without BPM capabilities

In case you want to use KIE Server without BPM capabilities - for instance for Rules or Planning - then you can completely skip steps from 4 (in step 4 use only the marked in blue items) and still run KIE Server on Tomcat.

With that, I'd like to say welcome to Narayana in KIE Server - well done!