Deploy Bonita Community on OpenShift

Do you want to run your Bonita Community Tomcat instance on Redhat’s Openshift Online, using MySQL?

This post will not go into the details of using OpenShift, but rather focus on making Bonita Community Ed. 6.2.4 work on it, along with MySQL. I will not go into details of a regular installation of Bonita either.

Note to Bonita Subscription users: It is currently impossible to run the Subscription Edition on OpenShift (and most likely other PaaS services), due to not being able to generate license requests. Being one of these users, I raised a ticket to Bonita support, but didn’t get much support for it nor any hope to see it in the future.

Pre-requisites

  • Have a free OpenShift account
  • Have deployed an OpenShift application with the MySQL 5.5 and Tomcat 7 (JBoss EWS 2.0) cartridges
  • Downloaded on your workstation the Bonita BPM deployment Bundle

Note: After your git clone, don’t forget to remove the pom.xml from your git root and the src folder in order to avoid triggering a maven build when git pushing your changes.

git rm -r src/ pom.xml

Configuring Bonita the OpenShift way

If you have already deployed Bonita on one of your own server, you will soon notice that you cannot install it the same way using OpenShift.

Don’t forget that for all these local files you’ll modify, you’ll have to git add, git commit, and git push them.

The .openshift folder

After doing your git clone, you will have a local openshift directory (that we’ll call $OPENSHIFT_LOCAL_HOME), along with whatever apps you have. Let’s assign a few variables for this post purposes. Don’t confuse them with variables that you could find on your OpenShift instance:

$OPENSHIFT_LOCAL_HOME=/Users/fblaise/openshift/
$OPENSHIFT_LOCAL_APP=/Users/fblaise/openshift/quarterback

The gem folders are located under $OPENSHIFT_LOCAL_APP/.openshift. In that folder, you will notice 4 folders, 3 being of interest for now.

markers

Make sure you have an empty file named “java7” in it. This will tell your application to use java 7. Without it, you’d be running with java 6.

action_hooks

This is where you will configure the environment variables needed to start your Bonita context.

Create a file named pre_start_jbossews-2.0, and put something along these lines inside:

#!/bin/sh

BONITA_HOME="-Dbonita.home=${OPENSHIFT_DATA_DIR}/bonita_home"
DB_OPTS="-Dsysprop.bonita.db.vendor=mysql"
BTM_OPTS="-Dbtm.root=${OPENSHIFT_REPO_DIR} -Dbitronix.tm.configuration=${OPENSHIFT_REPO_DIR}/.openshift/config/bitronix-config.properties"
export CATALINA_OPTS="${CATALINA_OPTS} ${BONITA_HOME} ${DB_OPTS} ${BTM_OPTS} -Dfile.encoding=UTF-8 -Xshare:auto -XX:+HeapDumpOnOutOfMemoryError"

config

This is the place where you will put your .properties file. This what you should have at the end:

ironman:config fblaise$ ls -l1
bitronix-config.properties
bitronix-resources.properties
catalina.policy
catalina.properties
context.xml
logging.properties
postgresql_module.xml
server.xml
settings.base.xml
settings.prod.xml
settings.rhcloud.xml
settings.stg.xml
tomcat-users.xml
web.xml

Bonita and Tomcat configuration

Local files configuration

Not all files need to be modified. Find below the ones that do.

catalina.properties

In your local config folder under $OPENSHIFT_LOCAL_APP/.openshift, edit the catalina.properties. Locate the line starting with “common.loader”, and append the following:
/var/lib/openshift/xxxxxxxxxxxxxxxxxxxx/app-root/data/lib/*.jar
Note that this string will be unique for each of you. the string of “x” above represents your user for your OpenShift instance. You should then get:

common.loader=${catalina.base}/lib,${catalina.base}/lib/*.jar,${catalina.home}/lib,${catalina.home}/lib/*.jar,/var/lib/openshift/xxxxxxxxxxxxxxxxxxxx/app-root/data/lib/*.jar

server.xml

Add the following right above the <GlobalNamingResources> tag:


  

I think there is also a H2 listener line you should also remove, since we’re using MySQL. Look in that space also.

context.xml

You will notice a resource that is already configured for MySQL, done when you add the MySQL cartridge. Here, we will add our Bonita datasource and bitronix transaction factory. It should look like this:

[cc lang=”xml”]


[/cc]

bitronix-resources.properties

There is no variable interpolation in this file, so you will have to get your IP address from your OpenShift instance. You will notice in the block below the variables holding the values you’re looking for

[cc lang=”xml”]
resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
resource.ds1.driverProperties.user=bonita
resource.ds1.driverProperties.password=bpm
## NOT INTERPOLATING !! resource.ds1.driverProperties.URL=jdbc:mysql://${OPENSHIFT_MYSQL_DB_HOST}:${OPENSHIFT_MYSQL_DB_PORT}/bonita?dontTrackOpenResources=true&amp;amp;amp;amp;amp;amp;useUnicode=true&amp;amp;amp;amp;amp;amp;characterEncoding=UTF-8
resource.ds1.driverProperties.URL=jdbc:mysql://127.4.139.2:3306/bonita?dontTrackOpenResources=true&amp;amp;amp;amp;amp;amp;useUnicode=true&amp;amp;amp;amp;amp;amp;characterEncoding=UTF-8
resource.ds1.testQuery=SELECT 1
[/cc]

Don’t forget to git commit.

war, bonita_home and libraries

webapps

Copy the bonita.war found in your Bonita download in $OPENSHIFT_LOCAL_APP/webapps. git add and commit.

Libraries

There are several ways to go about that one. I will just present the one I use.

– On your openshift instance

mkdir $OPENSHIFT_DATA_DIR/lib

– scp all the .jar files you will find in your Bonita Community download under Tomcat-6.0.37/lib (without the *h2* ones) to the above directory.
– Don’t forget to put in there your MySQL connector jar file as well.

bonita_home

Upload the bonita_home-6.2.4 (containing the client and server subfolders) to your OpenShift instance, straight into $OPENSHIFT_DATA_DIR.

bonita-platform.properties

Don’t forget to change from h2 to mysql

db.vendor=${sysprop.bonita.db.vendor:mysql}

Push and deploy

Everything should now be set.

Make sure you’ve git added and committed all your local files, that your bonita.war in the local webapps directory, that you’ve removed your pom.xml and

git push

Performing a git push will restart your application, albeit all your cartridges.

You can tail the logs straight from your terminal with

rhc tail 

You can check out on your web browser as well, see if the login screen shows. Login with your install user then.

Bonita_BPM_Portal_openshift

Of course, since the application will be out on the wild, don’t forget to change Bonita’s default passwords if not already done (i.e., install user, platformAdmin, etc…).

I may have forgotten some things, as I have written this article some time after doing it. Please let me know if things are missing or are wrong.

HOWTO: Bonita and LDAP authentication

This how-to is written in the hope that it will help souls in achieving basic LDAP login with Bonita User Experience, using EJB3. This how-to is written based on the thread at http://www.bonitasoft.org/forum/viewtopic.php?id=2397.

It is working for me, but it may not for you. Please post your questions on the Bonita forums, many eyes will look at your issue and try to help you.

Here is a dirty PDF for those who wants. However, if you do use this howto, always refer to the online version for updates and up-to-date content.
Bonita LDAP howto

It may not render well in this blog, so I’d advise in pasting the code in your favorite editor to see clearly.

My environment at this time is:

  • Centos 5.4 latest updates
  • Jboss 5.1 GA
  • BOS 5.0.1
  • Java JDK 1.6.0 update 18
  • Active Directory 2003

To give a reference, here is how my base directory look like. I will refer to it when editing some files.

Under /opt:

[sourcecode language=’plain’]
lrwxrwxrwx 1 root root 9 Feb 23 11:39 BOS -> BOS-5.0.1
drwxr-xr-x 5 root root 4096 Feb 15 19:33 BOS-5.0.1
lrwxrwxrwx 1 root root 11 Feb 23 13:58 java-jdk-6 -> jdk1.6.0_18
lrwxrwxrwx 1 root root 14 Feb 23 16:19 jboss -> jboss-5.1.0.GA
drwxr-xr-x 9 root root 4096 Mar 4 09:57 jboss-5.1.0.GA
drwxr-xr-x 10 root root 4096 Feb 23 13:57 jdk1.6.0_18
[/sourcecode]

We will use the org.jboss.security.auth.spi.LdapExtLoginModule, as it will allow us to bind to the ActiveDirectory server. If you can allow for anonymous LDAP requests, then you may also try the Sun LDAPLoginModule.

jBoss configuration and EAR generation

JAVA_OPTS

In the run.sh file of jboss /opt/jboss/bin/run.sh) , edit it to configure your JAVA_OPTS:

[sourcecode language=’plain’]JAVA_OPTS=”-Dorg.ow2.bonita.api-type=EJB3 -server -Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256m”
[/sourcecode]

Alongside specifying the EJB3 for Bonita, I am setting reasonable settings for jBoss java memory, and possible avoid Permgen out of memory errors.

Extra: For quick and unsecure monitoring using jconsole, also add the following.
[sourcecode language=’plain’]JAVA_OPTS=”$JAVA_OPTS -Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.port=10001 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false”
[/sourcecode]

bonita-environment.xml

… under the /opt/BOS/runtime/conf directory directly. It will be used when building the EAR file.

So, we can already specify the implementation of the AuthenticationService interface, which we will call SimpleLdapAuth.
Edit the file /opt/BOS/runtime/bonita-environment.xml. It should look like the following:

[sourcecode language=’xml’]

[/sourcecode]

Of course, your package path will vary.
A sample, simple, implementation of the interface follows later on.

Generating bonita.ear

We now need to go ahead and generate our bonita.ear file, which will then be used by jBoss.

[sourcecode language=’plain’]cd/opt/BOS/runtime[/sourcecode]

Now, build your ejb3.

[sourcecode language=’plain’]ant ear.ejb3[/sourcecode]

You should get something like this:

[sourcecode language=’plain’][root@bonita-test runtime]# ant ear.ejb3

Buildfile: build.xml

ear.genBonitaConfJar:

ear.ejb3:

ear:

[mkdir] Created dir: /opt/BOS-5.0.1/runtime/ear/tmp

[unjar] Expanding: /opt/BOS-5.0.1/runtime/lib/server/bonita-server-5.0.1.jar into /opt/BOS-5.0.1/runtime/ear/tmp

[copy] Copying 1 file to /opt/BOS-5.0.1/runtime/ear/tmp/META-INF

ear.copyJeeDD:

[copy] Copying 1 file to /opt/BOS-5.0.1/runtime/ear/tmp/META-INF

[jar] Building jar: /opt/BOS-5.0.1/runtime/ear/ejb3/bonita-ejbjar.jar

[delete] Deleting directory /opt/BOS-5.0.1/runtime/ear/tmp

[ear] Building ear: /opt/BOS-5.0.1/runtime/ear/ejb3/bonita.ear

[echo] EJB3 ear has been generated in ear/ejb3 directory.

[echo] You can use it in the easybeans container, jonas 5 and jboss 5 application server.

BUILD SUCCESSFUL

Total time: 4 seconds
[/sourcecode]

Now, copy the bonita.ear file into your jboss deploy directory.

[sourcecode language=’plain’]cp /opt/BOS-5.0.1/runtime/ear/ejb3/bonita.ear
/opt/jboss/server/default/deploy/[/sourcecode]

login-config.xml

Add the 2 stanzas to the end of your login-config.xml, before the end tag. It is valid for an AD server (ie: (sAMAccountName={0}) is typically AD).)

[sourcecode language=’xml’]

ldap://your_ldap_server:389

simple

DC=domain,DC=com

DOMAINldapbrowser

(sAMAccountName={0})

SUBTREE_SCOPE

false

true

DC=domain,DC=com

(sAMAccountName={0})

memberOf

true

cn

follow

useFirstPass

[/sourcecode]

Your jaas-standard.cfg will then not be used anymore. You can comment everything out.

Implementation of AuthentionService interface

Java Code

Here you need to develop a little piece of java. Here is an example that will get you through for starters.

[sourcecode language=’java’]package com.domain.bonita.auth;

/**
* @author chapeaurouge
* @date 04/03/2010
* @version 0.1
*/

import org.ow2.bonita.facade.exception.UserNotFoundException;
import org.ow2.bonita.services.AuthenticationService;

public class SimpleLdapAuth implements AuthenticationService {

private String persistenceServiceName;

public SimpleLdapAuth(String persistenceServiceName) {
super();
this.persistenceServiceName = persistenceServiceName;
}

/**
* Determines if the user should have amdin accesses to the bonita interface
* Let’s say that Domain Admins have that privilege
*/
public boolean isUserAdmin(String username) throws UserNotFoundException {
if (username.equals(“MyAdmin”)) {
return true;
} else {
return false;
}
}

/**
* @return always true. If the LDAP request failed before, it doesn’t matter (?)
* Necessary to implement interface
*/
public boolean checkUserCredentials(String username, String password) {
return true;
}
}[/sourcecode]

Compiling

Compile the java code into a .class. Make sure the bonita jars are in your classpath.
[sourcecode language=’plain’]javac -cp ~/BOS-5.0.1/runtime/lib/server/bonita* SimpleLdapAuth.java[/sourcecode]
You should then have your .class file. If you did it locally, you can then upload it to your server.

Deploying

A manual way would be to do the following.
Go to your /opt/jboss/server/default/lib, create the directory hierarchy for your package name. So with our example, you could type

[sourcecode language=’plain’]mkdir -p com/domain/bonita/auth[/sourcecode]

Then copy, your .class in it. Now, still in your jboss lib directory, create a .jar file, as:

[sourcecode language=’plain’]jar -cvf domainLdapAuth.jar com/domain/bonita/auth/SimpleLdapAuth.class[/sourcecode]

Your jar will now be deployed on the next server startup.

Getting more verbose output

Edit /opt/jboss/server/default/conf/jboss-log4j.xml, and uncomment the following block:

[sourcecode language=’xml’]

[/sourcecode]

Conclusion

This should be it. I may have forgotten some things, or overlooked some steps. Hopefully, this was of some help for some of you.
You can now (re)start your jBoss server for the changes to take effect. Don’t forget to tail -f server.log to see how it looks like.
Your feedback and comments are welcome.
Thanks to rlg and abirembaut for their help in the forums.