2.7. Installing Red Hat JBoss BRMS on Red Hat JBoss Web Server

The generic deployable package is provided for customers to install Red Hat JBoss BRMS 6.3 to an existing application server. The following procedure provides instructions for installation on an existing Red Hat JBoss Web Server 2.1.0 instance.

Important

In a fresh Red Hat JBoss BRMS installation, you can encounter exceptions in the log similar to the following:

WARNING: Unable to instantiate EJB Asynchronous Bean. Falling back to Executors' CachedThreadPool.

The exceptions are caused by the code that failed to look up an Enterprise Java Beans object registered under a JNDI name that does not exist in Apache Tomcat. Therefore, a default implementation is used instead.

These messages are only warnings and do not have any impact on the overall functionality of the system.

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.

After setting up Business Central, it is necessary to configure data sources for the Realtime Decision Server (kie-server) as well. Otherwise, Realtime Decision Server tries to find a data source under the JNDI jboss/datasources/ExampleDS, which is by default registered only in Red Hat JBoss EAP and not in Apache Tomcat.

Note

Realtime Decision Server requires a data source only if the jBPM extension is enabled. This extension is enabled by default.

Realtime Decision Server needs a dedicated database, which is why it is not possible to reuse the data source registered for Business Central. To add a dedicated data source for kie-server, do the following:

  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