dimanche 13 juin 2010

How to install Bonita on a Glassfish server with an Oracle database

This article is the english translation of Installer Bonita sur un serveur Glassfish avec une BDD Oracle

According to the official documentation, Bonita runtime and user experience can only be installed on JBoss or Tomcat servers. With little patience, those components can be deployed on Glassfish servers.

Introduction to Bonita

Bonita is an open-source workflow solution supported by the BPM company BonitaSoft.

The Bonita solution combines :

  • A standalone process design studio (the Bonita Studio)
  • A BPM engine (the Runtime)
  • A graphical user interface (the Bonita User Experience - BUE)


The goal of this tutorial is to install the runtime and the BUE on a Glassfish v2.1.1 server. The runtime will use a remote Oracle 10g database (XE). The Bonita Studio will be installed on the administrator's computer.

Process users will connect to the User Experience from a remote computer (WinXP / Firefox). So will the administrator.
The operating system installed on the application and database servers is CentOS 5.5.

In this tutorial, the application server's hostname is bonita.localdomain. The database server's hostname is database.localdomain

Note: this guide only contains information related to the appplication server's configuration. For instance, DBMS installation won't be covered in this article.


  • Bonita Studio has already been installed on the administrator's computer
  • Oracle DBMS has already been installed on the database server
  • Glassfish is installed on the application server
  • Ant is installed on the application server

Step 1 - Export the engine

Start Bonita Studio, then click on "Process > Export application".

Check the "Export UserXP" and "All UserXP" checkbox
Check the "Export runtime" checkbox
Check the "Extract selected war libraries {...] in a common folder [...]"
Don't select any process in the process list
Select a location (for instance: /home/pingtimeout/bonita_application.zip)

A file named bonita_application.zip is created in the specified folder.

Unzip this file (e.g. in /home/pingtimeout/bonita_application/). The newly created folder now contains these elements:

  • common-war-lib
  • conf
  • runtime
  • wars
  • INSTALL.txt

Bonita UserXP and Runtime are now ready to be installed.

Step 2 - Create and initialize the databases

Note : in this tutorial, the databases "core" and "history" are stored on the same Oracle instance. However, they could be separated on two different instances.

Create two db users named CORE and HISTORY.

In the bonita_application folder, edit the file runtime/conf/hibernate-core.properties. Change the following parameters:

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     CORE
hibernate.connection.password     CORE

Edit the file runtime/conf/hibernate-history.properties. Change the following parameters:

hibernate.dialect                 org.hibernate.dialect.Oracle10gDialect
hibernate.connection.driver_class oracle.jdbc.OracleDriver
hibernate.connection.url          jdbc:oracle:thin:@database.localdomain:1521:XE
hibernate.connection.username     HISTORY
hibernate.connection.password     HISTORY

Add the Oracle JDBC driver in runtime/lib/server/

Use ant to create and initialize the core db.
$ ant init-db
Choose the following configuration: hibernate-configuration:core

Use ant to create and initialize the history db.
$ ant init-db
Choose the following configuration: hibernate-configuration:history

The databases are now created and initialized.

Step 3 - Prepare a Glassfish domain

Note : $GLASSFISH_HOME is an environment variable that contains the absolute path to the bonita home directory (on my server : /opt/glassfish/)

Create a glassfish domain named "bonita"
$ asadmin create-domain --adminuser admin --portbase 24000 bonita

Enter the admin password and the master password for this domain to be created.

Copy all files from bonita_application/common-war-lib/ in $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/common-war-lib/* $GLASSFISH_HOME/domains/bonita/lib/

Copy all files from bonita_application/runtime/lib/server/ in $GLASSFISH_HOME/domains/bonita/lib/
$ cp bonita_application/runtime/lib/server/* $GLASSFISH_HOME/domains/bonita/lib/

Copy all files from bonita_application/runtime/conf/ in $GLASSFISH_HOME/domains/bonita/config/
$ cp bonita_application/runtime/conf/* $GLASSFISH_HOME/domains/bonita/config/

Start the domain
$ asadmin start-domain bonita

The "bonita" glassfish domain is now started.

Step 4 - Install Bonita on Glassfish

Finally, bonita.war may now be uploaded on the application server.

On your domain's administration console (e.g. http://bonita.localdomain:24048/), click on "Web Application" menu item
In the application list, click on "Deploy"

In the field "Packaged file to be uploaded to the server", select bonita_application/wars/bonita.war
Enter "bonita" as application name
Click on "Ok"

Bonita is now installed on your server.
To access the BUE, click on the "Launch" button in the deployed applications list.

Did you run into problems during the installation, or think this article can be improved ? Let's hear about it in the comments. :-)

Enjoy !

5 commentaires:

  1. Have you tried installing the new Bonita 5.4 on the new Glassfish 3.1 by any chance?

  2. Hi George !

    Until 30 minutes ago, no, I hadn't tried :)
    The new versions of Bonita and Glassfish come with lots of changes. This article is only suitable for Bonita 5.2 and Glassfish 2.

    However, it's still possible to install Bonita 5.4 in Glassfish 3.1. Here are some tips :
    - In bonita studio, click on "Process > Advanced Export"
    - Checked "yes" for the two questions and hit "Next"
    - Select your process and the User XP, and hit "Next"
    - Check "Export Runtime" and hit "Export"
    => You'll get a bonita_application folder

    It seems that Bonita doesn't need us to create the BONITA_CORE and BONITA_HISTORY databases. By default, those databases are bundled in the server using H2 Database.

    Now, it's time to install it in glassfish
    - Create a new domain using "asadmin create-domain". Don't use the useradmin option.
    - Copy the jar files from bonita_application/runtime/lib/server/ to glassfish/domains/bonita/lib/
    - Append the content of bonita_applications/conf/external/security/jaas-standard.cfg to glassfish/domains/bonita/config/login.conf
    - Copy the folder bonita_applications/conf/bonita/ in your glassfish directory
    - Add the following line to glassfish/domains/bonita/config/domain.xml
    <system-property name="BONITA_HOME" value="PATH_THE_BONITA_FOLDER_YOU_JUST_COPIED"></system-property>

    Note: you can do this in the administration console too.

    - Start the domain
    - Deploy Bonita
    - That's it

    Hope that helps !

  3. i need a video or step by step tutorial for Bonita 5.4 in Glassfish 3.1.

  4. I have tried Pierre Laporte instructions and it worked. Thanks!

    I deployed Arrival_of_a_New_Employee--4.1.war and have successfully
    installed Arrival_of_a_New_Employee--4.1.bar in the administration screen.

    However when I tried to run the case it comes out with an error "Error while getting the process configuration" - hen configured copyOnRead or copyOnWrite, a Store will only accept Serializable values.

    Does any have an idea how to fix this error?

  5. Hello, thanks so much for write this blog, here i create a tutorial for deploy bonita 5.4.1 on glassfish 3.1, i hope it could be useful: http://silviajquiroga.blogspot.com/2011/08/deploy-bonita-user-xp-541-on-glassfish.html