# Welcome to Bonita Community edition Tomcat bundle

I. Installation: basic configuration + first start
An H2 database is embedded in the bundle for early project testing (it is not suitable for production environments).
You can install and start the bundle with H2 (A), or install and start directly on your database (B).

  A. Install with embedded H2 database (for testing purposes)
1. Run start-bonita.sh (Unix) or start-bonita.bat (Windows) to launch the Bonita Community Tomcat bundle
2. Verify that Bonita is up and running by accessing the login page at (http://localhost:8080/bonita)
You will still be able to switch to another database vendor later on.

  B. Install with connection to an external database
Pre-requisites
     1. Create your database
     2. Customize it so it's ready to work with Bonita (check the documentation site)

Installation
     1. Edit the file setup/database.properties: set the database values to point to your existing database
     2. Run start-bonita.sh (Unix) or start-bonita.bat (Windows) to launch the Bonita Community Tomcat bundle
     3. Verify that Bonita is up and running by accessing the login page at (http://localhost:8080/bonita)


II. Advanced bundle configuration (can be done before or after first start)
You must not configure Tomcat files directly anymore.
If you decide to do it anyway, your custom values will be overwritten by the templates used by Bonita.
If you need to finely tune the configuration, modify the following template files:
    - setup/tomcat-templates/bonita.xml
    - setup/tomcat-templates/setenv.sh
    - setup/tomcat-templates/setenv.bat
They are used as a basis for Tomcat configuration and will overwrite Tomcat provided files.
Bonita Community Tomcat bundle must be restarted so the new configuration is taken into account.


III. Database vendor switch after first start
This works if you need to switch from any DB vendor (including H2) to any other DB vendor.
     1. Edit the file setup/database.properties: change the database values to suit your needs
     2. Run start-bonita.sh (Unix) or start-bonita.bat (Windows) to launch the Bonita Community Tomcat bundle
Note that this switch is not a migration: the new database will be initialized and left empty for a fresh start.

IV. Bonita internal configuration update
You may need to change the configuration of Bonita platform, like the Technical user's credentials.
To do so:
     1. Stop Bonita Community Tomcat bundle
     2. In setup/ folder, run `setup(.sh|.bat) pull` to retrieve your current configuration from database
     3. Edit any configuration file in setup/platform_conf/current folder. 
        Example of frequently customized files are:
        - setup/platform_conf/current/platform_engine/bonita-platform-community-custom.properties
        - setup/platform_conf/current/tenant_engine/bonita-tenant-community-custom.properties
    4. Run `setup(.sh|.bat) push` to push the new configuration to the database
    5. Restart the Bonita Community Tomcat bundle so the new configuration is taken into account


V. FAQ
* When I run on H2, why do I get prompted at each start to confirm that I want to use H2?
=> H2 is not recommended for production purposes, but only in development/testing environments.
To make sure you run in such environments, you are asked to confirm.
