Are you ready to dive into (wildfly) swarm?

KIE Server is a lightweight execution server that comes with various capabilities where out of the box are following:

• BRM - rules execution (Drools)
• BPM - business process execution, task management, background jobs (jBPM)
• BPM-UI - visualize your bpm components on runtime such as process definition and instance (since 6.4)
• BRP - business resource planning (Optaplanner) (since 6.4)

It's by default packaged as JEE application (web archive) and deployed to various containers, such as:

• JBoss EAP
• Wildfly
• Tomcat
• WebLogic
• WebSphere

While all this is already quite nice coverage, we don't stay idle and do work on bringing more to you. Let's see what's coming next...

All the hype about micro service is bringing in tons of new stuff that allows alternative approach for packaging and deployment of our systems or services if you like. Taking into consideration what capabilities KIE Server comes with it would be a crime to not take advantage of it to start building micro services with it. Instead of rewriting all the stuff in different way.

It's time to introduce Wildfly Swarm (to those that haven't heard about it yet) ...

Swarm offers an innovative approach to packaging and running JavaEE applications by packaging them with just enough of the platform to "java -jar" your application

So what Wildfly Swarm means in context of KIE Server?

Actually it means a lot:

• first of all it allows us to build executable jars that will bring in KIE Server capabilities to simple java -jar way of working with all it's power!
• next you can have a "executable kjar" just by starting it with argument that identifies kjar to be available for execution (Group Artifact Version)
• you can still run in managed mode - connected to controller and managed from within controller but without a need to provision your application server

With this in mind let's take a look at how to use it with Wildfly Swarm.

• Clone this repository kie-server-swarm into your local environment.
• Build the project with maven (mvn clean package)
• Make sure you run it with latest Maven otherwise you might run into build errors - I tested it with 3.3.9 so it works certainly with it
• Once it's successfully build you'll find following file inside the target folder
• kie-server-swarm-1.0-swarm.jar
• Now you're ready to rock with KIE Server on Wildfly Swarm

but before we start our KIE Server on Swarm, let's look at what options we have for the project we just built. This project, same as KIE Server, is modularized and allows us to pick only the things we are interested with. While KIE Server allows to disable extensions on runtime (via system properties) sometimes it does not make sense to bring in lots of dependencies if they are not going to be used.

So you can build the project with following profiles:

• BRM - includes BRM capability of the KIE Server that allows rules execution only
• no server components besides REST is configured
• build it with - mvn clean package -PBRM
• BPM - includes both BRM and BPM capabilities of the KIE Server - this is the default profile
• configures Swarm to have transactions and data sources enabled
• build it with - mvn clean package -PBPM or mvn clean package

So why it's important to have it done as profiles? It's because the size of resulting file (executable jar) will be smaller. Moreover it reduces number of things Swarm is going to configure and boot when we start our system. So keep this in mind as it might become handy one day or another :)

Let's get our hands dirty with running KIE Server on Wildfly Swarm

First thing, let's just start empty server that will let us manage it manually - creating containers, running rules and processes via REST api

Make sure you're in the project folder (where you executed maven build) and then simply run this command:

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -Dswarm.port.offset=300 -jar target/kie-server-swarm-1.0-swarm.jar

Wait for a while to boot Wildfly Swarm and KIE Server on it. Once it's completed you should be able to access it at http://localhost:8380/server

NOTE: since KIE Server requires authentication, whenever you attempt to access its REST endpoints you need to logon - by default you should be able to logon with kieserver/kieserver1!
you can customize users and roles by editing following files:

kie-server-swarm/src/main/config/security/application-users.properties

kie-server-swarm/src/main/config/security/application-roles.properties

Now let's examine a bit what all these parameters mean:

•  -Dorg.kie.server.id=swarm-kie-server - specifies the unique identifier of the kie server - it is important when running in managed mode but good to use it always to make it a habit
• -Dorg.kie.server.location=http://localhost:8380/server - specifies the actual location where our KIE Server is going to be available - this must be a direct URL to actual instance even it if's behind load balancer - again important when running in managed mode
• -Dswarm.port.offset=300  - sets global port offset to avoid port conflicts when running many instances of wildfly on same machine

Next, let's run our first executable KJAR... to do so we just extend the command from first run and add arguments to the execution

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -jar target/kie-server-swarm-1.0-swarm.jar org.jbpm:HR:1.0

as you can see the only difference is:
org.jbpm:HR:1.0

which is GAV of a KJAR that is going to be deployed upon start of KIE Server on Swarm. So with just single command line we have fully functional server with BPM capabilities and HR project deployed to it.

Last but not least, let's run it in fully managed way - with controller.
Before you start wildfly Swarm with KIE Server, make sure you start controller (KIE workbench) so you'll see how nicely it registers automatically upon start.

Once controller (workbench) is running issue following command:

java -Dorg.kie.server.id=swarm-kie-server -Dorg.kie.server.location=http://localhost:8380/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller -jar target/kie-server-swarm-1.0-swarm.jar

Again, a singe parameter difference between the first command we used to start empty KIE Server on Swarm - in this case it's controller url:

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

Make sure that this URL matches your controller being deployed - it can differer in terms of

• host (localhost in this case)
• port (8080 in this case)
• context root (kie-wb in this case)

Now you're ready to rock with Wildfly Swarm and KIE Server to build your own micro services backed by business knowledge.

Enjoy your dive into Swarm and as usual comments are more than welcome.

Installing KIE Server and Workbench on same server

A common requirement for installation on development machine is to run both KIE Workbench and KIE Server on same server to simplify execution environment and avoid any port offset configuration.

This article will explain all installation steps needed to make this happen on two most frequently used containers:

• Wildfly 8.2.0.Final
• Apache Tomcat 8

Download binaries

So let's get our hands dirty and play around with some installation steps. First make sure you download correct versions of workbench and KIE Server for the container you target.

Wildfly

kie-wb-distribution-wars-6.3.0.Final-wildfly8.war

kie-server-6.3.0.Final-ee7.war

Tomcat

kie-wb-distribution-wars-6.3.0.Final-tomcat7.war

kie-server-6.3.0.Final-webc.war

Wildfly

Deploy applications

Copy downloaded files into WILDFLY_HOME/standalone/deployments, while copying rename them to simplify the context paths that will be used on application server:

• rename kie-wb-distribution-wars-6.3.0.Final-wildfly8.war to kie-wb.war
• rename kie-server-6.3.0.Final-ee7.war to kie-server.war

Configure your server

With Wildfly there is not much to setup as both transaction manager and persistence (including data source) is already preconfigured.

Configure users

• create user in application realm 
• name: kieserver 
• password: kieserver1!
• roles: kie-server
• create user in application realm to logon to workbench
• name: workbench 
• password: workbench!
• roles: admin, kie-server

Configure system properties

Following list of properties needs to be given to work smoothly for both workbench and KIE Server:

• -Dorg.kie.server.id=wildfly-kieserver 
• -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server 
• -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller

Launching the server

best way is to add system properties into startup command when launching Wildfly server. Go to WILDFLY_HOME/bin and issue following command:

./standalone.sh --server-config=standalone-full.xml -Dorg.kie.server.id=wildfly-kieserver -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller

Tomcat

Deploy applications

Copy downloaded files into TOMCAT_HOME/webapps, while copying rename them to simplify the context paths that will be used on application server:

• rename kie-wb-distribution-wars-6.3.0.Final-tomcat7.war to kie-wb.war
• rename kie-server-6.3.0.Final-webc.war to kie-server.war

Configure your server

1. Copy following libraries into TOMCAT_HOME/lib
1. btm-2.1.4
2. btm-tomcat55-lifecycle-2.1.4
3. h2-1.3.161
4. jacc-1.0
5. jta-1.1
6. kie-tomcat-integration-6.3.0.Final
7. slf4j-api-1.7.2
8. slf4j-api-1.7.2
2. Create Bitronix configuration files to enable JTA transaction manager

• Create file 'btm-config.properties' under TOMCAT_HOME/conf with following content

bitronix.tm.serverId=tomcat-btm-node0

bitronix.tm.journal.disk.logPart1Filename=${btm.root}/work/btm1.tlog

bitronix.tm.journal.disk.logPart2Filename=${btm.root}/work/btm2.tlog

bitronix.tm.resource.configuration=${btm.root}/conf/resources.properties

• Create file 'resources.properties' under TOMCAT_HOME/conf with following content

resource.ds1.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource

resource.ds1.uniqueName=jdbc/jbpm

resource.ds1.minPoolSize=10

resource.ds1.maxPoolSize=20

resource.ds1.driverProperties.driverClassName=org.h2.Driver

resource.ds1.driverProperties.url=jdbc:h2:mem:jbpm

resource.ds1.driverProperties.user=sa

resource.ds1.driverProperties.password=

resource.ds1.allowLocalTransactions=true

Configure users

Create following users in tomcat-users.xml under TOMCAT_HOME/conf

• create user
• name: kieserver 
• password: kieserver1!
• roles: kie-server
• create user to logon to workbench
• name: workbench 
• password: workbench!
• roles: admin, kid-server

 
<tomcat-users>
  <role rolename="admin"/>
  <role rolename="analyst"/> 
  <role rolename="user"/>
  <role rolename="kie-server"/>

  <user username="workbench" password="workbench1!" roles="admin,kie-server"/>
  <user username="kieserver" password="kieserver1!" roles="kie-server"/>  
</tomcat-users>

Configure system properties

Configure following system properties in file setenv.sh under TOMCAT_HOME/bin

-Dbtm.root=$CATALINA_HOME 

-Dorg.jbpm.cdi.bm=java:comp/env/BeanManager 

-Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties 

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

-Djava.security.auth.login.config=$CATALINA_HOME/webapps/kie-wb/WEB-INF/classes/login.config 

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

-Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform 

-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

NOTE: Simple copy this into setenv.sh files to properly setup KIE Server and Workbench on Tomcat:

CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Dbtm.root=$CATALINA_HOME -Dorg.jbpm.cdi.bm=java:comp/env/BeanManager -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Djava.security.auth.login.config=$CATALINA_HOME/webapps/kie-wb/WEB-INF/classes/login.config -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/jbpm -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform -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"

Launching the server

Go to TOMCAT_HOME/bin and issue following command:

./startup.sh

Going beyond default setup

Disabling KIE Server extensions

And that's all to do to setup both KIE Server and Workbench on single server instance (either Wildfly or Tomcat). This article focused on fully featured KIE server installation meaning both BRM (rules) and BPM (processes, tasks) capabilities. Although KIE Server can be configured to serve only subset of the capabilities - e.g. only BRM or only BPM.

To do so one can configure KIE Server with system properties to disable extensions (BRM or BPM)

Wildfly:

add following system property to startup command:

• disable BRM: -Dorg.drools.server.ext.disabled=true
• disable BPM: -Dorg.jbpm.server.ext.disabled=true

So the startup command would look like this:

./standalone.sh --server-config=standalone-full.xml -Dorg.kie.server.id=wildfly-kieserver -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller -Dorg.jbpm.server.ext.disabled=true

Tomcat

add following system property to setenv.sh script (must be still part of CATALINA_OPTS configuration):

• disable BRM: -Dorg.drools.server.ext.disabled=true
• disable BPM: -Dorg.jbpm.server.ext.disabled=true

Complete content of setenv.sh is as follows:

CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Dbtm.root=$CATALINA_HOME -Dorg.jbpm.cdi.bm=java:comp/env/BeanManager -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Djava.security.auth.login.config=$CATALINA_HOME/webapps/kie-wb/WEB-INF/classes/login.config -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/jbpm -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform -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 -Dorg.jbpm.server.ext.disabled=true"

Changing data base and persistence settings

Since by default persistence uses just in memory data base (H2) it is good enough for first tryouts or demos but not for real usage. So to be able to change persistence settings following needs to be done:

KIE Workbench on Wildfly

Modify data source configuration in Wildfly - either via manual editing of standalone-full.xml file or using tools such as Wildfly CLI. See Wildfly documentation on how to define data sources.

• Next modify persistence.xml that resides inside workbench war file. Extract the kie-wb.war file into directory with same name and in same location (WILDFLY_HOME/standalone/deployments). 
• Then navigate to kie-wb.war/WEB-INF/classes/META-INF
• Edit persistence.xml file and change following elements
• jta-data-source to point to the newly created data source (JNDI name) for your data base
• hibernate.dialect to hibernate supported dialect name for you data base

KIE Server on Wildfly

there is no need to do any changes to the application (the war file) as the persistence can be reconfigured via system properties. Set following system properties at the end of server startup command

• -Dorg.kie.server.persistence.ds=java:jboss/datasources/jbpmDS
• -Dorg.kie.server.persistence.dialect=org.hibernate.dialect.MySQL5Dialect

Full command to start server will be:

./standalone.sh --server-config=standalone-full.xml -Dorg.kie.server.id=wildfly-kieserver -Dorg.kie.server.location=http://localhost:8080/kie-server/services/rest/server -Dorg.kie.server.controller=http://localhost:8080/kie-wb/rest/controller -Dorg.kie.server.persistence.ds=java:jboss/datasources/jbpmDS 

-Dorg.kie.server.persistence.dialect=org.hibernate.dialect.MySQL5Dialect

KIE Workbench on Tomcat

To modify data source configuration in Tomcat you need to alter resources.properties (inside TOMCAT_HOME/conf) file that defines data base connection. For MySQL it could look like this:

resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource

resource.ds1.uniqueName=jdbc/jbpmDS

resource.ds1.minPoolSize=0

resource.ds1.maxPoolSize=10

resource.ds1.driverProperties.user=guest

resource.ds1.driverProperties.password=guest

resource.ds1.driverProperties.URL=jdbc:mysql://localhost:3306/jbpm

resource.ds1.allowLocalTransactions=true

Make sure you're copy mysql JDBC driver into TOMCAT_HOME/lib otherwise it won't provide proper connection handling.

• Next modify persistence.xml that resides inside workbench war file. Extract the kie-wb.war file into directory with same name and in same location (TOMCAT_HOME/webapps). 
• Then navigate to kie-wb.war/WEB-INF/classes/META-INF
• Edit persistence.xml file and change following elements
• jta-data-source to point to the newly created data source (JNDI name) for your data base
• hibernate.dialect to hibernate supported dialect name for you data base

KIE Server on Tomcat

there is no need to do any changes to the application (the war file) as the persistence can be reconfigured via system properties. Set or modify (as data source is already defined there) following system properties in setenv.sh script inside TOMCAT_HOME/bin

• -Dorg.kie.server.persistence.ds=java:comp/env/jdbc//jbpmDS
• -Dorg.kie.server.persistence.dialect=org.hibernate.dialect.MySQL5Dialect

Complete content of the setenv.sh script is as follows:

CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Dbtm.root=$CATALINA_HOME -Dorg.jbpm.cdi.bm=java:comp/env/BeanManager -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Djava.security.auth.login.config=$CATALINA_HOME/webapps/kie-wb/WEB-INF/classes/login.config -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/jbpmDS -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform 

-Dorg.kie.server.persistence.dialect=org.hibernate.dialect.MySQL5Dialect

-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"

Note that KIE Server persistence is required only for BPM capability so if you disable it you can skip any KIE server related persistence changes.

And that would be it. Hopefully this article will help with installation of KIE Workbench and Server on single application server. 

Have fun and comments more than welcome.