= Bonita Tomcat bundle
:description: You will find here the mandatory and optional steps needed to install and configure the Tomcat bundle to run the Bonita platform.

You will find here the mandatory and optional steps needed to install and configure the Tomcat bundle to run the Bonita platform.

The Tomcat bundle is a .zip archive that contains the Apache Tomcat Java EE application server prepackaged along with Bonita and xref:bonita-bpm-platform-setup.adoc#platform_setup_tool[Bonita platform setup tool].
The Tomcat bundle is a regular .zip archive based on Tomcat zip distribution.

[#tomcat-bundle-installation]
== Installation of the Tomcat bundle

=== Download and unzip the Tomcat bundle

[#download]

==== Download

For the Community edition:

* Go to the http://www.bonitasoft.com/downloads-v2[Bonitasoft website] and get the Bonita Community edition Tomcat bundle.

For a Subscription edition:

* Go to the https://customer.bonitasoft.com/download/request[Customer Service Center] and download the Bonita Subscription edition Tomcat bundle.

==== Unzip

The fully qualified folder path (including the Bonita-x.y.z folder) to the folder where you unzip the Tomcat bundle is referred to as `<BUNDLE_HOME>`. We recommend the following locations:

* Windows: `C:\Bonita`.
* Linux: in `/opt/Bonita`. Make sure that Linux user account used to execute Tomcat is the owner of the folders and files.

[WARNING]
====

Whatever location you choose, *do not* leave blank spaces in the path to the directory, nor in the folder name.
====

==== Content of the Tomcat bundle

The Tomcat bundle is based on a standard Tomcat installation with the following additions:

* `setup/tomcat-templates/setenv.bat`: script to configure JVM system properties for Windows.
* `setup/tomcat-templates/setenv.sh`: script to configure JVM system properties for Linux.
* `setup/tomcat-templates/bonita.xml`: Tomcat context configuration for Bonita web application. Define data sources used by Bonita Engine.
* `server/conf/catalina.properties`: modified to include lib/bonita folder to Tomcat classpath.
* `server/conf/context.xml`: modified to add JTA support using Narayana library.
* `server/conf/logging.properties`: modified to create a log file dedicated to Bonita.
* `server/conf/server.xml`: modified to add listener for Narayana and h2 (see below for modification needed if you want to switch to another RDBMS).
* `server/conf/jbossts-properties.xml`: configuration files for Narayana transaction manager.
* `server/lib/bonita`: extra libraries needed by Bonita. The following libraries are included: Narayana JTA Transaction Manager, h2, SLF4J.
* `server/webapps/bonita.war`: the Bonita web application.
* `setup/`: a tool to manage Bonita Platform configuration, stored in database instead of filesystem. Also ships a tool to centralize all the required Tomcat bundle configuration.
* `tools/request_key_utils: folder containing the script to generate license request keys (Subscription editions only).
* `tools/BonitaSubscription-x.y.z`-`LDAP-Synchronizer` : folder containing the tool to synchronize your organization in Bonita with your LDAP (Subscription editions only).
* `tools/cas-`_`cas.version`_`-module`: folder containing module files and description to enable CAS dependency to bonita EAR (Subscription editions only).
* `start-bonita.bat`: script to start the bundle on Windows.
* `start-bonita.sh`: script to start the bundle on Linux.
* `stop-bonita.bat`: script to stop the bundle on Windows.
* `stop-bonita.sh`: script to stop the bundle on Linux.

[NOTE]
====

Beginning with version 7.3.0, Bonita Platform configuration, including the license file, is stored in the same database as the Bonita Engine data, namely in the `CONFIGURATION` table.
The initialization of this configuration happens during `start-bonita.bat` (for Windows) or `start.bonita.sh` (for Linux) execution. +
Once initialized, to update this configuration, use the xref:bonita-bpm-platform-setup.adoc[_Platform setup tool_] embedded in Bonita bundles.
====

=== Get and install a license (Subscription editions only)

First, request a license.
If this is the first time you generate a license, you need to generate a request key.

==== Generate the request key

On the server where you installed Bonita Platform:

. Go to the `tools/request_key_utils` folder
. Run the `generateRequestKey.bat` script (for Windows) or the `generateRequestKey.sh` script (for Linux)

==== Request the new license

. Copy your request key and go to the Customer Service Center license request page.
. Fill in the details in the form, copy the request key in the _Request Key_ field, and submit.
 Note: keep the brackets () in the key; if the key is separated by a line break, remove it and put the key on a single line.

The license file will be sent to you by email.

[#license]

When you receive your license:
Copy the file to the `<BUNDLE_HOME>/setup/platform_conf/licenses` folder before starting the bundle.

=== Change the default credentials (optional, recommended for production)

As a security precaution, we *strongly recommend* that before you start your application server, you change the default username and password used for the platform administrator and for the default tenant administrator.

==== Platform administrator

The username and password are defined in a text file:

* Before the very first Tomcat start: xref:bonita-bpm-platform-setup.adoc[`<BUNDLE_HOME>/setup/platform_conf/initial/platform_engine/bonita-platform-community-custom.properties`]
* After the first Tomcat start: xref:bonita-bpm-platform-setup.adoc[`<BUNDLE_HOME>/setup/platform_conf/current/platform_engine/bonita-platform-community-custom.properties`]

The properties are listed below:

* `platformAdminUsername` defines the username (default `platformAdmin`)
* `platformAdminPassword` defines the password (default `platform`)

This password is used for platform-level administration tasks, such as creating a tenant.

==== Tenant administrator

Each tenant has an administrator, with a tenant-specific username and password. The tenant administrator is also known as the tenant technical user.

When the platform is created, default values for the tenant administrator username and password are defined in the file xref:bonita-bpm-platform-setup.adoc[`<BUNDLE_HOME>/setup/platform_conf/initial/tenant_template_engine/bonita-tenant-community-custom.properties`], by the following properties:

* `userName` defines the username (default `install`)
* `userPassword` defines the password (default `install`)

When you create a tenant, the tenant administrator is created with the default username and password, unless you specify new values.
Change these tenant-specific credentials for an existing tenant by updating the `userName` and `userPassword` properties in `<BUNDLE_HOME>/setup/platform_conf/current/tenants/<TENANT_ID>/tenant_engine/bonita-tenant-community-custom.properties`.

[WARNING]
====

For the *default tenant*, the tenant administrator username and password must also be changed in file:

* Before the very first Tomcat start: xref:bonita-bpm-platform-setup.adoc[`<BUNDLE_HOME>/setup/platform_conf/initial/platform_portal/platform-tenant-config.properties`]
* After the first Tomcat start: xref:bonita-bpm-platform-setup.adoc[`<BUNDLE_HOME>/setup/platform_conf/current/platform_portal/platform-tenant-config.properties`],

For further details and a better understanding, please read the section xref:tenant_admin_credentials.adoc[Tenant administrator credentials].
====

[#configuration]

=== Configure the Tomcat bundle

[NOTE]
====

If you just want to try Bonita Platform with the embedded H2 database (only for development and testing phases of your project), you can skip the next paragraph.
For production, you are recommended to use one of the supported databases, with the following steps.
====

. Make sure xref:database-configuration.adoc#database_creation[your databases are created] and xref:database-configuration.adoc#specific_database_configuration[customized to work with Bonita].
. Edit file `<BUNDLE_HOME>/setup/database.properties` and modify the properties to suit your databases (Bonita internal database & Business Data database). Beware of xref:bonita-bpm-platform-setup.adoc#backslash_support[backslash characters].
. Run `<BUNDLE_HOME>\setup\start-bonita.bat` (Windows system) or `<BUNDLE_HOME>/setup/start-bonita.sh` (Unix system) to run Bonita Tomcat bundle (see <<tomcat_start,Tomcat start script>>)

[NOTE]
====

The *start-bonita* script does the following:

. Runs the *`setup init`* command:
 .. initializes the Bonita internal database (the one you have defined in file `<BUNDLE_HOME>/setup/database.properties`): creates the tables that Bonita uses internally + stores the configuration in the database.
 .. installs the license files (Subscription editions only) in the database.
. Runs the *`setup configure`* command:
The Setup Configure command configures the Tomcat environment to access the right databases:
 .. updates the file setenv.sh (Unix system) or setenv.bat (Windows system) to set the database vendor values for *Bonita internal database* & *Business Data database*
 .. updates the file `<BUNDLE_HOME>/setup/tomcat-templates/bonita.xml` with the values you set in file `database.properties` *Bonita internal database* & *Business Data database*
 .. copies your database vendor-specific drivers from `<BUNDLE_HOME>/setup/lib` to `<BUNDLE_HOME>/setup/server/lib/bonita`
. Starts the Tomcat bundle

For advanced server configuration needs: check out xref:bonita-bpm-platform-setup.adoc#run_bundle_configure[Bundle configuration] to finely tune your Tomcat bundle, using templates used by Bonita.
====

[#start]

=== Starting and shutting down Tomcat

[#tomcat_start]

==== Tomcat start script

Tomcat can be started by executing the following script:

* Windows: `<BUNDLE_HOME>\start-bonita.bat`
* Linux: `<BUNDLE_HOME>/start-bonita.sh`

==== Tomcat stop script

Tomcat can be shut down by executing the following script:

* Windows: `<BUNDLE_HOME>\stop-bonita.bat`
* Linux: `<BUNDLE_HOME>/stop-bonita.sh`

*Troubleshooting:*
If you see `checkThreadLocalMapForLeaks` errors, they probably indicate that Tomcat is shutting down before all work threads are completed.
You can xref:performance-tuning.adoc[increase the work service termination timeout] to ensure that work is complete before shutdown.

== After installation

=== First steps after installation

Once you have your Tomcat bundle up and running, complete these xref:first-steps-after-setup.adoc[few extra steps] to get Bonita Platform fully operational.

=== Configuration update

To update Bonita configuration after the first run, take a look at the xref:bonita-bpm-platform-setup.adoc#update_platform_conf[platform setup tool]

[NOTE]
====


* The file `database.properties` is the entry point to configure the xref:bonita-bpm-platform-setup.adoc#run_bundle_configure[Tomcat environment] and the xref:bonita-bpm-platform-setup.adoc#configure_tool[Bonita Platform configuration].
* You can use command line arguments to specify database properties directly from the command line. Use `<BUNDLE_HOME>/setup/setup.sh --help` on Linux or `<BUNDLE_HOME>\setup\setup.bat --help` on Windows to have a list of available options.
====

=== License update

To update the licenses after the first run, take a look at the xref:bonita-bpm-platform-setup.adoc#update_platform_conf[platform setup tool]

== Troubleshooting

'''

*Issue*: When I run `start-bonita.sh` or `start-bonita.bat`, I get the error message `Invalid Java version (1.7) < 1.8. Please set JRE_HOME or JAVA_HOME variable to a JRE / JDK 1.8+`

*Cause*: Bonita 7.5+ requires Java 1.8 to run

*Solution*: Ensure your running environment has a JDK or JRE 1.8 installed and set either JRE_HOME or JAVA_HOME environment variable to point to it.

'''
