Procedure: Installing Generic Deployable Package

1. Go to the Red Hat Customer Portal and log in.
2. Click DOWNLOADS at the top of the page.
3. In the Product Downloads page that opens, choose Red Hat JBoss BRMS.
4. From the Version drop-down menu, select version 6.3.

5. Select Red Hat JBoss BRMS 6.3.0 Deployable for All Supported Containers package and click Download.

   Also select and download the Red Hat JBoss BRMS Core Engine files (jboss-brms-VERSION-engine.zip).

6. Extract business-central.war and kie-server.war from the generic deployable archive and copy to tomcat7/webapps/ folder.
7. Remove the .war extensions from the business-central.war and kie-server.war folders.
8. Move the kie-tomcat-integration-VERSION.jar file from the Red Hat JBoss BRMS Core Engine distribution to tomcat7/lib.

9. Define users and roles in tomcat7/conf/tomcat-users.xml as shown below.

   Important

   Make sure that the selected user name does not conflict with any known title of a role or a group. See Section 2.8, “Defining Roles” for a list of defined roles.

   For example, if there is a role called admin, you should not create a user with the user name admin.

   <role rolename="admin"/>
   <role rolename="analyst"/>
   <user username="user" password="password" roles="admin,analyst"/>

10. Install the transaction manager.

    Warning

    Please note that the following section describes the setup of a transaction manager, Bitronix, that is not officially supported by Red Hat.

    Copy the following transaction manager JAR libraries from the lib folder to $TOMCAT_DIR/lib/ directory. These JARs are available in jboss-brms-VERSION-deployable-generic.zip and jboss-brms-VERSION-engine.zip.

    • btm-VERSION.jar
    • btm-tomcat55-lifecycle-VERSION.jar
    • h2-VERSION.jar
    • jta-VERSION.jar
    • slf4j-api-VERSION.jar
    • slf4j-jdk14-VERSION.jar

    Additionally, download the following library and copy it into the $TOMCAT_DIR/lib/ folder: javax.security.jacc-api.jar.

    Add Valve configuration into TOMCAT_HOME/conf/server.xml inside the <host> element as last Valve definition:

    <Valve className="org.kie.integration.tomcat.JACCValve" />

11. Create the transaction manager configuration files in $TOMCAT_DIR/conf/:

    • btm-config.properties

      bitronix.tm.serverId=tomcat-btm-node0
      bitronix.tm.journal.disk.logPart1Filename=${btm.root}/work/btm1.tlog
      bitronix.tm.journal.disk.logPart2Filename=${btm.root}/work/btm2.tlog
      bitronix.tm.resource.configuration=${btm.root}/conf/resources.properties

    • resources.properties (the resource.ds1.uniqueName defines the data source name used in Tomcat resource definition later — make a note of this value).

      Example 2.1. H2 Data Source Definition

      resource.ds1.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=10
      resource.ds1.maxPoolSize=20
      resource.ds1.driverProperties.driverClassName=org.h2.Driver
      resource.ds1.driverProperties.url=jdbc:h2:file:~/jbpm
      resource.ds1.driverProperties.user=sa
      resource.ds1.driverProperties.password=
      resource.ds1.allowLocalTransactions=true

      Example 2.2. MySQL 5.5 Data Source Definition

      resource.ds1.className=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:mysql://localhost:3306/sampledb
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.3. DB2 Type 4 Data Source Definition

      resource.ds1.className=com.ibm.db2.jcc.DB2Driver
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:db2://localhost:50000/sampledb
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.4. Oracle Data Source Definition

      resource.ds1.className=oracle.jdbc.xa.client.OracleXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:oracle:thin:@//localhost:1521/bpms
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

      Example 2.5. Microsoft SQL Server Data Source Definition

      resource.ds1.className=com.microsoft.sqlserver.jdbc.SQLServerDriver
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.URL=jdbc:sqlserver://localhost:1433;databaseName=bpms;
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true

12. If you are using a data source other than the default provided by the underlying H2 database, you will need to set up persistence. If you are using the default H2 database, then you can ignore the rest of the steps in this procedure.

    In this procedure, you configure a data source with the JNDI name jdbc/myDatasource as defined in uniqueName=jdbc/jbpm in the Bitronix resources.properties file earlier (for the MySQL option).

    1. In business-central/META-INF/context.xml, replace the data source JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set in resources.properties:

       <Resource name="jdbc/myDatasource" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>

    2. In business-central/WEB-INF/web.xml, replace the data source JNDI name in the <res-ref-name> element with your data source name:

       <resource-ref>
         <description>Console DS</description>
         <res-ref-name>jdbc/myDatasource</res-ref-name>
         <res-type>javax.sql.DataSource</res-type>
         <res-auth>Container</res-auth>
       </resource-ref>

    3. Change business-central/WEB-INF/classes/META-INF/persistence.xml.

       In this file, change the name of the Hibernate dialect used for your database, if using a different database other than H2. The code below demonstrates the original database information for persistence.xml:

       <property name="hibernate.dialect" value="org.hibernate.dialect.H2Dialect"/>

       This information can be updated in the following manner (as demonstrated with MySQL database below):

       <property name="hibernate.dialect" value="org.hibernate.dialect.MySQLDialect"/>

       Note

       The dialect for DB2 is org.hibernate.dialect.DB2Dialect, for DB2 on AS/400 is org.hibernate.dialect.DB2400Dialect, for Oracle is org.hibernate.dialect.Oracle10gDialect, and for Microsoft SQL Server is org.hibernate.dialect.SQLServerDialect.

    4. Change business-central/WEB-INF/classes/META-INF/persistence.xml file so that Red Hat JBoss BPM Suite process engine can use the new database.

       The code below demonstrates the original data source information for persistence.xml:

       <jta-data-source>java:comp/env/jdbc/jbpm</jta-data-source>

       Change this value to the data source defined earlier:

       <jta-data-source>java:comp/env/jdbc/myDatasource</jta-data-source>

13. Set up the transaction manager listener in $TOMCAT_DIR/conf/server.xml to start and stop Bitronix on container startup and shutdown.

    Add the following element as the last <Listener> element into the <Server> element:

    <Listener className="bitronix.tm.integration.tomcat55.BTMLifecycleListener" />

14. Define the btm.root system property and location where Bitronix configuration file is placed in:

    In the $TOMCAT_DIR/bin/, create a readable setenv.sh file with the following content:

    CATALINA_OPTS="-Xmx512M -XX:MaxPermSize=512m -Djava.security.auth.login.config=$CATALINA_HOME/webapps/business-central/WEB-INF/classes/login.config -Dbtm.root=$CATALINA_HOME -Dbitronix.tm.configuration=$CATALINA_HOME/conf/btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Dorg.jboss.logging.provider=jdk"

    The property org.jbpm.designer.perspective is set to RuleFlow to allow the default perspective for the designer to be RuleFlow rather than Full. Grant the file execute permissions if applicable.

    Note

    The -XX:MaxPermSize=512m JVM property is valid only for JDK 6 and 7. It is not valid for JDK 8+.

    Important

    On Microsoft Windows systems, replace the $CATALINA_HOME value in the content of the file with the equivalent environment variable name, or use the absolute path and add the values in setenv.bat file as shown here in the following example:

    set "CATALINA_OPTS=-Xmx512m -XX:MaxPermSize=512m -Djava.security.auth.login.config=C:\apache-tomcat\webapps\business-central\WEB-INF\classes\login.config -Dbtm.root=C:\apache-tomcat -Dbitronix.tm.configuration=C:\apache-tomcat\conf\btm-config.properties -Dorg.jbpm.designer.perspective=RuleFlow -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry"

15. Install the driver to your database — copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/.

    Driver to Embedded H2 Database

    If using the embedded H2 database, the driver is available in business-central/WEB-INF/lib/.

16. Start JBoss Web Server by running startup.sh in the tomcat7/bin directory.

    ./startup.sh

    Wait a few minutes and check the server log ($TOMCAT_DIR/tomcat7/logs) for any errors. If there are no errors, proceed to the next step.

17. Navigate to http://localhost:8080/business-central in a web browser.
18. Login with the user name/password defined in the tomcat-users.xml file.

1. Copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/. If you are using an H2 database, this step has already been done during the Business Central installation.

2. Add the data source into the resources.properties file. Note that the actual values may differ, based on the underlying database.

   resource.ds2.className=bitronix.tm.resource.jdbc.lrc.LrcXADataSource
   resource.ds2.uniqueName=jdbc/kieserver
   resource.ds2.minPoolSize=10
   resource.ds2.maxPoolSize=20
   resource.ds2.driverProperties.driverClassName=org.h2.Driver
   resource.ds2.driverProperties.url=jdbc:h2:file:~/bpm630tomcat7kieserver
   resource.ds2.driverProperties.user=sa
   resource.ds2.driverProperties.password=
   resource.ds2.allowLocalTransactions=true

3. Register a new resource in the kie-server/META-INF/context.xml:

   <Resource name="jdbc/kieserver"
             uniqueName="jdbc/kieserver"
             auth="Container"
             removeAbandoned="true"
             factory="bitronix.tm.resource.ResourceObjectFactory"
             type="javax.sql.DataSource" />

4. Update the $TOMCAT_DIR/bin/setenv.sh file. Add the following data source-related properties for kie-server:

   -Dorg.kie.server.persistence.ds=java:comp/env/jdbc/kieserver
   -Dorg.kie.server.persistence.tm=org.hibernate.service.jta.platform.internal.BitronixJtaPlatform