2.2. The Generic Deployable Bundle Installation
To install Red Hat JBoss BPM Suite on Red Hat JBoss Web Server (EWS), you need to use the generic deployable package of the product.
For installation on EWS, the generic deployable package contains additional transaction manager and security libraries that are not part of Red Hat JBoss EWS.
Note that to install the generic deployable package, you need the following ZIP files:
jboss-bpmsuite-VERSION-deployable-generic.zip
: contains thebusiness-central.war
,dashbuilder.war
andkie-server.war
web applications.jboss-bpmsuite-VERSION-engine.zip
: supported execution engine libraries for embeding the engine into your application and other libraries needed for generic deployment.
2.2.1. Downloading the Generic Deployable Package
To download the generic deployable Red Hat JBoss BPM Suite package for JBoss Web Server, do the following:
- Go to the Red Hat Customer Portal and log in.
- Click on Downloads.
- From the list of products click on Red Hat JBoss BPM Suite.
- From the Version drop-down menu, select version 6.1 (if not already selected).
- In the Software Downloads section that comes up, navigate to the Red Hat JBoss BPM Suite 6.1 Deployable for All Supported Containers row and then click Download.
- Also navigate to the Red Hat JBoss BPM Suite 6.1 Engine files row and click Download to download the JBoss BPM Suite Engine files.
2.2.2. Installing the Generic Deployable Package
To install the generic deployable package, you need to set up the following after you have installed the underlying platform (Red Hat JBoss WS):
- Set up the database driver and the transaction manager (Bitronix) (refer to Section 2.2.2.1, “Setting up Transaction Manager for Red Hat JBoss Web Server 2.1 (Tomcat 7)”).
- Set up the Business Central application: set up users and roles and set up persistence (refer to Section 2.2.2.2, “Setting up Business Central for Red Hat JBoss Web Server 2.1 (Tomcat 7)”).
- Set up the Dashbuilder application: set up users and roles and set up persistence (refer to Section 2.2.2.3, “Setting up Dashbuilder for Red Hat JBoss Web Server 2.0 (Tomcat 7)”).
2.2.2.1. Setting up Transaction Manager for Red Hat JBoss Web Server 2.1 (Tomcat 7)
- Extract the generic deployable zip package you downloaded from Red Hat Customer Portal to a temporary location. This zip package contains the following three web application archives:
business-central.war
,dashbuilder.war
andkie-server.war
in an exploded format. Rename these folders to remove the.war
extension. - Copy these folders directly under the
$TOMCAT_DIR/webapps
folder.You should end up with three folders in an exploded format:$TOMCAT_DIR/webapps/business-central
,$TOMCAT_DIR/webapps/dashbuilder
and$TOMCAT_DIR/webapps/kie-server
.Note
$TOMCAT_DIR stands for the home directory where your web server is located. Replace it with the actual path to your web server home directory, for example:/home/john/jboss-ews-2.1/tomcat7/
- Extract the contents of the JBoss BPM Suite Engine files archive to a temporary location from where you can copy the required libraries. This folder now contains all the core JBoss BPM Suite libraries under the extracted folder and a
lib
folder. 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 thelib
folder to$TOMCAT_DIR/lib/
directory:- btm-VERSION.jar
- btm-tomcat55-lifecycle-VERSION.jar
- jta-VERSION.jar
- slf4j-api-VERSION.jar
- slf4j-jdk14-VERSION.jar
In addition, download the following library and copy it into the$TOMCAT_DIR/lib/
folder as well:Install the Driver to Your Database
Copy the jar file with the relevant database driver to$TOMCAT_DIR/lib/
.Note
If using the embedded H2 database, the driver is available inbusiness-central/WEB-INF/lib/
.- 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 datasource name used in tomcat resource definition later - make a note of this value).Make sure to change the values in the following definitions to match your environment.
Example 2.1. H2 datasource 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 datasource 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 datasource 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 datasource 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 datasource 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
- 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" />
- Define the btm.root system property and location where bitronix config file is placed:In
$TOMCAT_DIR/bin/
, create a readablesetenv.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"
The propertyorg.jbpm.designer.perspective
is set toRuleFlow
to allow the default perspective for the designer to beRuleFlow
rather thanFull
. Grant the file execute permissions if applicable.Thejava.security.auth.login.config
property must be set in order for the ssh clone of the git repository to work.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 insetenv.bat
file as shown here in the following example:set "CATALINA_OPTS=-Xmx512m -XX:MaxPermSize=512m -Dbtm.root=C:\apache-tomcat -Dbitronix.tm.configuration=C:\apache-tomcat\conf\btm-config.properties"
2.2.2.2. Setting up Business Central for Red Hat JBoss Web Server 2.1 (Tomcat 7)
To set up Business Central, do the following:
- Set up a
Valve
so that the Business Central web application can load the users set up in Tomcat:- Define users and roles in
$TOMCAT_DIR/conf/tomcat-users.xml
. Note that Business Central requires users to have the roles specified asadmin
and/oranalyst
(for more information about user and role definitions, refer to the Tomcat 7 documentation).The program listing below shows an example of how these two roles would be added and how a user namedbpmsadmin
will be assigned these roles.Note
Make sure that the usernames don't conflict with any known roles. For example, you should not create a user with the usernameadmin
.<role rolename="admin"/> <role rolename="analyst" /> <user username="bpmsadmin" password="P@ssw0rd" roles="admin,analyst"/>
- Move (not copy)
kie-tomcat-integration-VERSION.jar
from$TOMCAT_DIR/webapps/business-central/WEB-INF/lib/
to$TOMCAT_DIR/lib/
. - Copy
jboss-jaxb-api-VERSION.jar
from$TOMCAT_DIR/webapps/business-central/WEB-INF/lib/
to$TOMCAT_DIR/lib/
. - In
$TOMCAT_DIR/conf/server.xml
, add the Tomcat Valve declaration in the relevant <host> element:<Valve className="org.kie.integration.tomcat.JACCValve" />
- If you are using a datasource other than the default provided by the underlying H2 database, you will need to setup 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 datasource with the JNDI name
jdbc/myDatasource
as defined in uniqueName=jdbc/jbpm in the bitronixresources.properties
file earlier (for the MySQL option).- In
business-central/META-INF/context.xml
, replace the datasource JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set inresources.properties
:<Resource name="jdbc/myDatasource" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>
- In
business-central/WEB-INF/web.xml
, replace the datasource JNDI name in the <res-ref-name> element with your datasource 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>
- 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 forpersistence.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 isorg.hibernate.dialect.DB2Dialect
, for DB2 on AS/400 isorg.hibernate.dialect.DB2400Dialect
, for Oracle isorg.hibernate.dialect.Oracle10gDialect
and for Microsoft SQL Server isorg.hibernate.dialect.SQLServerDialect
- Change
business-central/WEB-INF/classes/META-INF/persistence.xml
file so that JBoss BPM Suite process engine can use the new database.The code below demonstrates the original datasource information forpersistence.xml
:<jta-data-source>java:comp/env/jdbc/jbpm</jta-data-source>
Change this value to the datasource defined earlier:<jta-data-source>java:comp/env/jdbc/myDatasource</jta-data-source>
- You can now start the JBoss Web Server to login to Business Central.
- Run
startup.sh
in the $TOMCAT_HOME/bin
directory../startup.sh
- Navigate to http://localhost:8080/business-central in a web browser.
- Login with the username/password you defined earlier in
tomcat-users.xml
file.
2.2.2.3. Setting up Dashbuilder for Red Hat JBoss Web Server 2.0 (Tomcat 7)
Note
Before setting up Dashbuilder on Red Hat JBoss Web Server, you must ensure that you have correctly installed and started Business Central as described in Section 2.2.2.2, “Setting up Business Central for Red Hat JBoss Web Server 2.1 (Tomcat 7)”. Dashbuilder requires the history log database tables to exist, which are only provided by Business Central. If these tables are not present in the database before attempting the steps below, you may get initialization errors.
To set up Dashbuilder on Red Hat JBoss Web Server, do the following:
- Define users and roles in
$TOMCAT_DIR/conf/tomcat-users.xml
. Note that Dashbuilder requires users to have the role specified asadmin
and/oranalyst
. If you have already defined these users earlier for Business-Central, you don't need to define them again. - Enable single sign-on between Dashbuilder and Business Central by uncommenting the following lines in
$TOMCAT_DIR/conf/server.xml
file:<Valve className="org.apache.catalina.authenticator.SingleSignOn" />
- As with Business Central setup, if you are using a database other than the default and integrated H2 database, you will need to setup persistence.In this procedure, you configure a datasource with the JNDI name
jdbc/dashbuilderDS
as defined in uniqueName=jdbc/jbpm in the bitronixresources.properties
file:- In
dashbuilder/META-INF/context.xml
, replace the datasource JNDI name in the <Resource> element. The uniqueName attribute refers to the resource.ds1.uniqueName property set inresources.properties
:<Resource name="jdbc/dashbuilderDS" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource"/>
Note
Depending upon your database, you may need to define some other properties here as well. For example, in an Oracle environment, this entry may look like the following listing.<Resource name="jdbc/jbpm" uniqueName="jdbc/jbpm" auth="Container" removeAbandoned="true" factory="bitronix.tm.resource.ResourceObjectFactory" type="javax.sql.DataSource" username="username" password="password" driverClassName="oracle.jdbc.xa.client.OracleXADataSource" url="jdbc:oracle:thin:YOUR-URL:1521:YOUR-DB" maxActive="8" />
- In
dashbuilder/WEB-INF/web.xml
, add the datasource JNDI name in the <res-ref-name> element with your datasource name:<resource-ref> <description>Dashboard Builder Datasource</description> <res-ref-name>jdbc/dashbuilderDS</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref>
- In
dashbuilder/META-INF/context.xml
, define the transaction factory:<Transaction factory="bitronix.tm.BitronixUserTransactionObjectFactory"/>
- Update the datasource JNDI name in
dashbuilder/WEB-INF/etc/hibernate.cfg.xml
in the <session-factory> element:<property name="connection.datasource">java:/comp/env/jdbc/dashbuilderDS</property>
- Restart Java Web server for these changes to take effect. Once restarted, you can navigate to Dashbuilder from within Business Central or directly via:
http://localhost:8080/dashbuilder
.