Custom Tomcat installation

This page explains how to install Bonita Runtime in an existing Tomcat server.

Remember that the recommended way of installing Bonita is through a self-contained application.
It saves you from doing all the following configuration, and will be the only way supported in the future.

This installation procedure only specifically targets the Java EE application servers that have been installed under a single root folder (typically, from a .zip file). Thus, for installations using native distribution packages (that more often than not split the binaries and the configuration files into separate folder hierarchies), it would be up to you to adapt the documented steps to your very own folder layout.

Installation

  1. Download the Tomcat bundle file from the Bonitasoft download page for the Community edition or from the Customer Service Center for Subscription editions.

  2. Unzip it into a temporary folder (BUNDLE_DIRECTORY).

  3. Follow the Tomcat bundle steps.

Tomcat installation

Install Bonita Runtime in the Tomcat server

Copy, from the bundle into your Tomcat server (TOMCAT_DIRECTORY):

  • BUNDLE_DIRECTORY/server/bin/setenv.sh or BUNDLE_DIRECTORY/server/bin/setenv.bat, depending if you are on Unix or Windows, to TOMCAT_DIRECTORY/bin

  • The entirety of the bundle BUNDLE_DIRECTORY/server/conf folder to TOMCAT_DIRECTORY/conf

  • The entirety of the bundle BUNDLE_DIRECTORY/server/lib/bonita folder to TOMCAT_DIRECTORY/lib/bonita

  • The BUNDLE_DIRECTORY/server/webapps/bonita to TOMCAT_DIRECTORY/webapps

  • The and BUNDLE_DIRECTORY/webapps/ROOT/favicon.ico to TOMCAT_DIRECTORY/webapps/ROOT/

  • The entirety of the BUNDLE_DIRECTORY/setup directory at the root of your tomcat server TOMCAT_DIRECTORY.

  • The entirety of the BUNDLE_DIRECTORY/tools/request_key_utils-. Includes script files to generate license request keys to TOMCAT_DIRECTORY/tools/request_key_utils-.

Some of the libraries copied from the bundle BUNDLE_DIRECTORY/server/lib/bonita may already exist (albeit in a different version) in your Tomcat server TOMCAT_DIRECTORY/lib folder. e.g.:

  • bundle: server/lib/bonita/tomcat-dbcp-x.y.z.jar

  • Tomcat server: lib/tomcat-dbcp-a.b.c.jar and lib/tomcat-dbcp.jar

For such libraries, you should only keep the ones copied from the bundle under TOMCAT_DIRECTORY/lib/bonita, or else the Bonita server may encounter NoSuchMethodError-type of issues.

Some configuration files from the bundle will overwrite some default tomcat configuration files. Proceed with care in a tomcat where other applications are already installed.

Data sources configuration

  1. Open the file TOMCAT_DIRECTORY/conf/Catalina/localhost/bonita.xml

  2. Remove or comment out the lines regarding the h2 database.

  3. Uncomment the lines matching your RDBMS.

  4. Update following attributes value:

    • username: your RDBMS user name.

    • password: your RDBMS password.

    • url: the URL, including the RDBMS server address, RDBMS server port and database (schema) name.

  5. There are 4 datasources declared. Make sure you made the change for them all, named RawBonitaDS, bonitaSequenceManagerDS, RawBusinessDataDS, NotManagedBizDataDS.

RDBMS vendor configuration

  1. Open the file TOMCAT_DIRECTORY/bin/setenv.sh (Unix system) or TOMCAT_DIRECTORY/bin/setenv.bat (Windows system)

  2. Change the value of sysprop.bonita.db.vendor according to your RDBMS vendor

  3. Change the value of sysprop.bonita.bdm.db.vendor according to your RDBMS vendor

Add JDBC driver

You need to add your JDBC driver in TOMCAT_DIRECTORY/lib. MySQL, PostgreSQL, Oracle and Microsoft SQL Server drivers can be found in the Tomcat bundle under BUNDLE_DIRECTORY/setup/lib directory.

License installation

If you are installing a Subscription edition, you need to request a license.

When you receive your license, copy the file to the TOMCAT_DIRECTORY/setup/platform_conf/licenses folder of your application server.

Database initialization

We assume here that the database has already been created and configured for Bonita. Once created and configured you need to initialize it using the setup tool provided in the bundle. This will create database schema and initial values.

  1. In TOMCAT_DIRECTORY/setup folder, edit the file database.properties with properties matching your RDBMS. Beware of backslash characters.

  2. In TOMCAT_DIRECTORY/setup folder, run setup.(sh|bat) init

Next steps

You are done with Bonita installation. You can now start your application server as usual.
You can also complete the setup of your system by validating the installation, setting passwords, and creating the technical user who will act as the Super Administrator.