Full Open Source setup of Bonita Open Solution - Part 2: Server

This tutorial continues the explanation about how to set up Bonita Open Solution on a full Open Source stack, from installation of Bonita Studio through running a process on the production server. Part 1 began with the installation of Bonita Studio, and this post is about installing a basic production server. You will use:

• Ubuntu Desktop and Server 12.04 LTS,
• OpenJDK 6 ,
• PostgreSQL 9.1,
• Tomcat 6, and of course,
• the Open Source version of Bonita Open Solution (BOS) 5.10, all in 64 bits.

This tutorial is aimed for beginners, but you will need to have Ubuntu installed and have basic knowledge about using terminals.

Server

Installation of the Ubuntu Server

I used VirtualBox to install Ubuntu Server, with a bridged network configuration so it has its own IP address over the network. (Of course, feel free to install Ubuntu Server on some actual hardware.) Set "bonita" as the first user and "bpm" as the password. (Note that this is appropriate for the tutorial, but for production, you should of course use more secured credentials.) As said in the introduction, this will not cover the entire installation of Ubuntu Server. However, it is useful to show that during the installation, you can select some packages to be pre-installed. As you can see in the second screenshot below, you should select "OpenSSH server", "LAMP Server", "PostgreSQL database" and "Tomcat Java Server".

When the installation is finished, I suggest you update all packages:

If you let dhcp manage the IP address for you, retrieve the address of the server. It will be very useful to use SSH in a terminal, and then have control of the server from the desktop PC where you've already installed Bonita Studio:

The system will ask for your password. Once you have your IP address, you can start a terminal on your desktop PC. Using SSH, you can remote control the server from the desktop PC, so you can do all steps of the tutorial with copy / paste, etc.

Of course, change the IP address to that of your server. Then, provide the password ("bpm" for this tutorial) and confirm the creation of the key. You should get something like this:

PostgreSQL

If you selected PostgreSQL to be installed by Ubuntu Server, PostgreSQL 9.1 is installed and its default configuration is mostly good. You just need to install the PostgreSQL JDBC driver, to define the password of "postgre" PostgreSQL user, and define a user for BOS, so you can connect to the server and use databases.

You'll get the Postgres prompt, like this:

Set a password for the "postgres" database role using the command:

Enter your password and confirm it. For the tutorial, use "bpm". Then, create the bonita user.

Now, create the two Bonita databases, "bonita_journal" and "bonita_history", and grant privileges to the "bonita" user.

To quit the PostgreSQL shell:

And press enter. You should be again on the remote system prompt. If your PostgreSQL server is not on the same system as the Tomcat server, or if you use a remote GUI like pgAdmin III to control PostgreSQL, you'll need to modify two files of PostgreSQL configuration, so it can listen on the network: "pg_hba.conf" and "postgresql.conf".

At the end of the file, add these lines:

# Allow any user from host 192.168.12.10 to connect to all
# databases if the user's password is correctly supplied.
#
# TYPE DATABASE USER ADDRESS METHOD host all all 192.168.0.0/24 md5

To save and quit, "ctrl+x", "y", and enter. Then,

Find the line starting with "#listen_addresses = 'localhost'" and change it to:

listen_addresses = '*'

To save and quit, "ctrl+x", "y", and enter. Once this is done, the server must be restarted.

If you want to have a GUI to control PostgreSQL on your desktop, you can install the package "pgadmin3". You can use Synaptic, Software Center, aptitude or apt-get. The fastest at this point is to create a new tab in the already open terminal: "File / Open Tab" or "ctrl+shift+t".

You can now start pgAdmin III from the menu. Click on the plug button to create a new connection to a server, fill in the information requested and you are ready. If you go to "bonita_history" or "bonita_journal", you should have 77 tables for both.

PostgreSQL is ready!

BOS Deploy

First step: download, unzip and copy the BOS bundle files to the "bonita" user home directory, in this case: "/home/bonita/"

"~/bos_deploy", or "/home/bonita/bos_deploy" is your folder. Of course, you can put this directory elsewhere. Keep path for future reference on this tutorial, BOS forum, documentation and training. You now need to install the JDBC driver. The installer will install JDBC3 and JDBC4 files, and provide a few very useful links. The interesting link is "/usr/share/java/postgresql-jdbc4.jar", which will always be related to the latest JBC4 version. Link it in "/bonita_execution_engine/engine/libs/". This way, if PostgreSQL JDBC driver is updated by the system, you don't have to update the link.

Before running the initDatabase.sh script to create BOS databases tables, edit two files: "bonita-history.properties" and "bonita-journal.properties". They are in "/conf/bonita/server/default/conf".

For both file, check that all lines in the header are commented out. Then, find the PostgreSQL section, uncomment those lines and fill databases login and password.

To quit and save, "ctrl+x" then "y" and "enter". Take care to not change the name of the file.

To quit and save, "ctrl+x" then "y" and "enter". Take care to not change the name of the file. Below are the copy of the different sections. Both header are the same, and the PostgreSQL section is slightly different.

##################################
# Default database configuration #
##################################
# IMPORTANT: do not use those settings for production!
# By default Bonita uses a H2 database that will store all data in one file.
# Access to the database is done through a datasource configured in Tomcat configuration file: conf/context.xml

# H2 Hibernate dialect
#hibernate.dialect org.hibernate.dialect.H2Dialect

# Using an interceptor can change the database behaviour. By default, an interceptor is defined to order the result of queries by adding null values at the end.
#bonita.hibernate.interceptor org.ow2.bonita.env.interceptor.H2DescNullFirstInterceptor

# Table are automatically create in database
#hibernate.hbm2ddl.auto update

# Location of the datasource (define in Tomcat configuration file: conf/context.xml)
# hibernate.connection.datasource java:/comp/env/bonita/default/journal

# Default database connection over H2 (not using datasources)
#hibernate.connection.driver_class org.h2.Driver
#hibernate.connection.url jdbc:h2:file:${BONITA_HOME}/server/default/work/databases/bonita_journal.db;FILE_LOCK=NO;MVCC=TRUE;DB_CLOSE_ON_EXIT=TR$
#hibernate.connection.username bonita
#hibernate.connection.password bpm
#hibernate.default_schema journal

##
# POSTGRESQL

hibernate.dialect org.hibernate.dialect.PostgreSQLDialect
hibernate.connection.driver_class org.postgresql.Driver
hibernate.connection.url jdbc:postgresql://localhost:5432/bonita_history
hibernate.connection.username bonita
hibernate.connection.password bpm

##
# POSTGRESQL

hibernate.dialect org.hibernate.dialect.PostgreSQLDialect
hibernate.connection.driver_class org.postgresql.Driver

hibernate.connection.url jdbc:postgresql://localhost:5432/bonita_journal
hibernate.connection.username bonita
hibernate.connection.password bpm

Now that the configuration is done, you can run the initDatabase.sh script.

The script asks three questions:

• Which domain do you want to use (press enter without nothing to use default)? -> press enter (default)
• Where is your BONITA_HOME folder? -> /conf/bonita

/home/bonita/bos_deploy/conf/bonita

• Which hibernate configuration to use to generate database (press enter without nothing to use default)? Default is 'hibernate-configuration:core hibernate-configuration:history' to init both databases: -> press enter (default)

The script will create the tables in "journal" and "history" databases. If you check the structure, you should see 77 tables in both databases.

BOS Configuration

In order to finish the configuration of BOS bundle, copy the "bonita" directory and "jaas-standard.cfg" in to "/opt" and set the rights for Tomcat. First, edit "jaas-standard.cfg":

Remove the lines

BonitaAuth-default {
org.ow2.bonita.identity.auth.BonitaIdentityLoginModule required domain="default";
org.ow2.bonita.identity.auth.LocalStorageLoginModule required domain="default";
};

BonitaStore-default {
org.ow2.bonita.identity.auth.LocalStorageLoginModule required domain="default";
};

To save and quit, "ctrl+x", then "y" and "enter". Now, copy all the files in "/opt" and set the rights:

When you configure Tomcat, define the context for the Bonita web application. So now that you have created the databases tables, you can prepare "bonita-journal.properties" and "bonita-history.properties" for production. The aim is to comment again the PostgreSQL configuration, and instead, insert the lines of the future datasource configuration.

To quit and save, “ctrl+x” then “y” and “enter”. Take care to not change the name of the file.

To quit and save, “ctrl+x” then “y” and “enter”. Take care to not change the name of the file. Below is a copy of the different sections.

##
# POSTGRESQL

hibernate.dialect org.hibernate.dialect.PostgreSQLDialect
#hibernate.connection.driver_class org.postgresql.Driver
#hibernate.connection.url jdbc:postgresql://localhost:5432/bonita_history
#hibernate.connection.username bonita
#hibernate.connection.password bpm
hibernate.connection.datasource java:/comp/env/bonita/default/history

##
# POSTGRESQL

hibernate.dialect org.hibernate.dialect.PostgreSQLDialect
#hibernate.connection.driver_class org.postgresql.Driver
#hibernate.connection.url jdbc:postgresql://localhost:5432/bonita_journal
#hibernate.connection.username bonita
#hibernate.connection.password bpm
hibernate.connection.datasource java:/comp/env/bonita/default/journal

Tomcat

If you selected Tomcat to be installed by Ubuntu Server, Tomcat6 is installed and its default configuration is mostly good. Next, link the PostgreSQL JDBC driver to Tomcat lib.

To set datasources, create a bonita.xml file with the context so the web application can access to the PostgreSLQ databases "bonita_journal" and "bonita_hystory".

Then, paste the content below in the terminal with the middle button, or with "ctrl+shift+c":

auth='Container'
type='javax.sql.DataSource'
username='bonita'
password='bpm'
driverClassName='org.postgresql.Driver'
url='jdbc:postgresql://localhost:5432/bonita_journal'
maxActive='20'
maxIdle='10'
maxWait='-1' />

auth='Container'
type='javax.sql.DataSource'
username='bonita'
password='bpm'
driverClassName='org.postgresql.Driver'
url='jdbc:postgresql://localhost:5432/bonita_history'
maxActive='20'
maxIdle='10'
maxWait='-1' />

To save and quit nano: press "ctrl+x", then "y" to save, and "enter" to validate the name of the file ("bonita.xml"). If you undeploy a Bonita web application, this file will be deleted by Tomcat. So, save it in the the "bonita" user directory.

To configure Bonita, system variables need to be defined. To do that, edit "/etc/default/tomcat6". This way, every time Tomcat6 restarts, it will use the correct information.

In the line:

JAVA_OPTS="-Djava.awt.headless=true -Xmx128m -XX:+UseConcMarkSweepGC"

Remove "-Xmx128m". You should have something like:

At the end of the file, paste the information below:

BONITA_HOME="-DBONITA_HOME=/opt/bos_conf/bonita"
BONITA_API_TYPE="-Dorg.ow2.bonita.api-type=Standard"
SECURITY_OPTS="-Djava.security.auth.login.config=/opt/bos_conf/jaas-standard.cfg"
CATALINA_OPTS="$CATALINA_OPTS $BONITA_HOME $BONITA_API_TYPE $SECURITY_OPTS -Dfile.encoding=UTF-8-Xshare:auto -Xms1024m -Xmx1024m -XX:MaxPermSize=512m -XX:+HeapDumpOnOutOfMemoryError"
export CATALINA_OPTS

Take care to set the path you used if it is different from the tutorial.

To save and quit, "ctrl+x", then "y" and "enter". Then restart Tomcat:

Tomcat is ready!

Production test

Test if everything is running well with a bonita.war file provided in the deploy bundle. In Ubuntu, webapps must be placed in "/var/lib/tomcat6/".

sudo cp ~/bos_deploy/bonita_user_experience/with_execution_engine_without_client/bonita.war /var/lib/tomcat6/webapps/
sudo chown tomcat6:tomcat6 bonita.war
sudo service tomcat6 restart

When Tomcat is restarted, open your favourite web browser, and go to "http://localhost:8080/bonita/" or "http://yourIPaddress:8080/bonita/". Example, in this tutorial: "http://192.168.0.209:8080/bonita/". You can log using "admin" and "bpm". If you already have a .bar file to test, go ahead and use it. If you don't, then start BOS Studio, select "Buy a mini", and in the menu, select "File / Export". It will create the "Buy_a_MINI--3.2.bar" file. In the User Experience, click on "Administration" on the top right, then "Processes" and "Install". On the popup, "Choose file" and then, click on "Install", then "Close". When the upload is finished (you can see a message display on the top right of the processes list) the process should be displayed in the deployed process list.

To start a process instance, go back to the "User view". In the left column, under "Start a case", click on "Buy a MINI". The form should appear, if you can play with the process, everything is working. If you check the content of the database, it should have changed to reflect the activity of the process.

You are done, and your production server for Bonita Open Solution 5.10 is ready.

Troubleshooting

Are you having problems installing and running BOS 5.10? You can get support from the community on the forum: http://www.bonitasoft.org/forum/. You will find the log in:

• Tomcat6, in "/var/log/tomcat6"
• PostgreSQL, in "/var/log/postgresql"
• Bonita Engine, in

Don’t forget to provide their content on your forum post if necessary.

References

Ubuntu community documentation about Java

PostgreSQL JDBC driver

PostgreSQL documentation

Tomcat 6 documentation

A special big thanks to the BonitaSoft Service team for their support and help with this tutorial.