Chapter 2. Installation Options

Red Hat JBoss BPM Suite comes in two versions:

  • Executable JAR installer for installation on Red Hat JBoss Enterprise Application Platform (EAP) 6.4.
  • ZIP file install which itself comes in two versions:

    • jboss-bpmsuite-6.4-deployable-eap6.x.zip: version adapted for deployment on Red Hat JBoss Enterprise Application Platform (EAP 6.4).
    • jboss-bpmsuite-6.4-deployable-generic.zip: the deployable version with additional libraries adapted for deployment on Red Hat JBoss Web Server (EWS), Apache Tomcat 6, and Apache Tomcat 7.

Depending on your environment, you may choose the installation option best suited for your project needs.

Note

Red Hat JBoss BPM Suite is designed to work with UTF-8 encoding. If a different encoding system is used by the underlying JVM, unexpected errors might occur. To ensure UTF-8 is used by the JVM, use the following system property: "-Dfile.encoding=UTF-8".

Important

From Red Hat JBoss BPM Suite 6.1 onwards, you must have Red Hat JBoss EAP 6.4 or better already installed before attempting to install Red Hat JBoss BPM Suite.

Important

This document describes deploying and configuring Business Central and Intelligent Process Server on the same server. Use this configuration for development environments. In production environments, deploy Business Central and Intelligent Process Server on different servers.

2.1. Red Hat JBoss BPM Suite Installer Installation

This section describes the steps required to install Red Hat JBoss BPM Suite using the JAR file installer installation method. The JAR file is an executable file that installs Red Hat JBoss BPM Suite on an existing Red Hat JBoss EAP 6 installation. However, the JAR installer does not support Red Hat JBoss EAP 7.0. For Red Hat JBoss EAP 7.0, only Deployable Zip installation option is supported.

Warning

Note that the provided Red Hat JBoss BPM Suite JAR file installer does not support the Red Hat JBoss EAP distribution installed by yum or RPM Package Manager. In this case, download the Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 6 file and follow the steps described in Section 2.2, “Installing Red Hat JBoss BPM Suite on Red Hat JBoss Enterprise Application Platform”.

Installation on IBM JDK

Due to IBM JDK not being able to use keystores generated on other JDKs, it is not possible to install Red Hat JBoss BPM Suite into an existing Red Hat JBoss EAP running on IBM JDK with a keystore generated on another JDK.

2.1.1. Installing Red Hat JBoss BPM Suite Using Installer

The installer for Red Hat JBoss BPM Suite is an executable Java JAR file. You can use it to install Red Hat JBoss BPM Suite on an existing Red Hat JBoss EAP 6.4 installation.

Note

For security reasons, you should run the installer as a non-root user.

Prerequisite

Before attempting to install Red Hat JBoss BPM Suite, ensure you have already installed Red Hat JBoss EAP 6, version 6.4.7 or higher, and create a back up. Ensure that your user has sufficient rights to complete the installation.

Make sure you have the JAR binary present in $PATH before running the installer. On Red Hat Enterprise Linux, it is present in the package java-$JAVA_VERSION-openjdk-devel.

  1. Navigate to the folder where you downloaded the installer file in a command prompt and execute the following command.

    java -jar jboss-bpmsuite-VERSION-installer.jar
    Note

    When running the installer on Windows, you may be prompted to provide administrator credentials during the installation. To prevent this, add the izpack.mode=privileged option to the installation command:

    java -Dizpack.mode=privileged -jar jboss-bpmsuite-VERSION-installer.jar

    Furthermore, when running the installer with a 32-bit Java Virtual Machine, you can encounter memory limitations. To solve the issue, run:

    java -XX:MaxHeapSize=4g -jar jboss-bpmsuite-VERSION-installer.jar

    The graphical installer will execute and display a splash screen and a license agreement page.

  2. Accept the license to proceed.
  3. In the next screen, provide the parent location of an existing Red Hat JBoss EAP where you want to install Red Hat JBoss BPM Suite.
  4. In the next two screens, create two users: the first one for the management console of the Red Hat JBoss EAP (ManagementRealm) and the second one for managing Red Hat JBoss BPM Suite itself (ApplicationRealm).

    Creation of the first user for the management console of Red Hat JBoss EAP is optional and you may skip it if it is not required.

    Make a note of these user names and passwords as you will need them to access the Red Hat JBoss EAP server (if you do decide to create it) and the Red Hat JBoss BPM Suite application respectively.

    Unless advanced configuration is performed, the Red Hat JBoss BPM Suite user password will be used as the default password for both client and server JMS SSL keystores, as well as password vault keystores.

    Important

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

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

    Note

    The passwords that you create must have at least 8 characters and must contain at least one number and one non-alphanumeric character (not including the character &).

    Note

    The application role assigned to the second user that you create is the admin role. You can assign additional roles to this user at this stage.

  5. Next, set up the security environment of your new Red Hat JBoss BPM Suite installation. Decide to enable or disable the Java Security Manager in this step by clicking on the check box. The Java Security Manager makes your system more secure but may downgrade performance. You need to make a decision based on your environment.
  6. Choose whether you want to setup pure IPv6 configuration on the server that the installation is taking place. This will enable you to setup runtime IPv6 specific configurations later.
  7. Configure runtime environment.

    This step provides the option of using a default configuration or specifying an advanced configuration.

    1. Default Configuration

      Choose Perform default configuration for the runtime environment in the next step and click Next to review the installation details. If you are happy with the details, click Next to start the actual installation or click Previous to go back and make changes.

    2. Advanced Configuration

      Choose to enable advanced configuration options. Select Perform advanced configuration and choose the advanced configuration options you want to enable for your environment using the check boxes.

    1. Configure Password Vault

      Vault passwords are used to obfuscate passwords in the various server descriptors using a Java secret key generated during the installation process, or manually using the keytool. This prevents passwords from being stored as plain text in the descriptors. The Iteration count and Salt are both parameters to the encryption process.

      In the case of Red Hat JBoss BPM Suite, a vault is always installed, even if the user does not choose to install one with their own parameters. When this occurs, default values will be used.

      For more information about vault passwords, see the Red Hat JBoss EAP Security Guide.

    2. SSL Security

      The SSL Security screen enables you to add the <ssl> and <truststore> elements to the ManagementRealm security realm using the provided keystore.

      • The <ssl> element causes the server to present the certificate within the keystore as its identity, which enables the user to apply their official certificate.
      • The <truststore> element enables Client-Cert authentication. This means that, if a remote client attempts to connect to any resource managed by the ManagementRealm, the client can present a certificate, and if an entry in the truststore matches, will be authenticated without needing to provide a user name/password.

      The end result is an encrypted connection that is secure between the client and the server for the ManagementRealm.

    3. LDAP Connection

      This step in the installer enables the user to define an LDAP server, which in turn defines users which should be allowed to authenticate with the ManagementRealm. This replaces the default configuration.

      The LDAP Connection screen enables users to define how to connect to the LDAP server.

      • Distinguished Name (DN): the user that can connect to the LDAP server. Typically the DN will uniquely define a special user for this purpose.
      LDAP Security (Management Console)

      The Management Console LDAP Configuration screen enables you to set up a security realm. This defines the <security-realm> element to be added to the descriptors, and utilizes the connection defined previously.

      • Base DN: Will typically define a 'base search' or 'root context' to begin searching for users.
      • Filter Type: Tells Red Hat JBoss EAP how to find the LDAP attribute that defines a user; it is can be a simple attribute, but can also be a complex LDAP filter.
      • Username filter: The LDAP attribute which holds the user name values. A user name entered in this field is used for search queries as a value of the uid attribute. If a user chooses LDAP Syntax Query as a filter type, this query must be specified in this field.
      • Recursive directory search: If enabled, Red Hat JBoss EAP will traverse the LDAP tree recursively, starting at Base DN. Otherwise, the search will be limited to Base DN.
      LDAP Security (Business Central)

      Most of the following fields are similar to the Base DN. Contexts are used to search for roles, which enables it to perform authorization in addition to authentication. Otherwise, the context fields are analogous to the Base DN from the previous, and attribute fields are analogous to user name attribute. The filters enable fine grained control over which values of the given attribute will be accepted.

      In Red Hat JBoss BPM Suite, the jbpm.usergroup.callback.properties and jbpm.user.info.properties files used by LDAPUserGroupInfo and LDAPUserInfo components of Task Service, are also filled by values entered on the Business Central LDAP Configuration page.

      Input values from Business Central LDAP Configuration page are used to configure a new security domain, which make use of LdapExtended login module. This security domain is set as default for Business Central web application. For more information about security domains and login modules, see the Red Hat JBoss EAP Security Guide.

    4. Security Domain and JSSE Configuration

      The Security Domain screen enables you to configure all of the elements of the <security-domain> security subsystem for managing security information, including JSSE configuration. For more detailed information about configuring security domains, see the Red Hat JBoss EAP Security Guide.

    5. Configure JMS SSL Keystores

      The Configuring JMS SSL Keystores screen enables the encryption of JMS messages sent to Business Central. The client keystores are distributed to systems that need to communicate with the server to facilitate encrypted communications. You can use your pre-existing keystores or generate new ones.

    6. Configure Clustering

      Selecting this option installs Red Hat JBoss BPM Suite ready for clustered operation. For more information, see Section 5.5, “Clustering on Red Hat JBoss EAP”.

    7. Business Central Datasource Setup

      After cluster configuration, the next screen enables you to configure the Business Central data source.

    8. Dashbuilder Datasource Setup

      The Dashbuilder Datasource Setup screen enables you to configure the Dashbuilder data source.

    9. Configure Optaplanner Execution Server

      Optaplanner is enabled by default. To disable Optaplanner, select Configure Optaplanner Execution Server then select Disable Optaplanner Execution Server on the Configure Optaplanner screen.

    10. Configure KIE Server Management

      Check Enable KIE server management if you want Business Central to manage the Intelligent Process Server and use the same data source for both execution servers.

      Managing the Intelligent Process Server using the Business Central requires a password vault to be configured. If you did not configure one, a vault with default values is created. See Configuring Password Vault for further information. The password to the keystore is the same as for the user bpmsAdmin.

  8. The installer will go through the steps to install Red Hat JBoss BPM Suite and will perform post installation configuration steps when you click Next. The installer can also start the Red Hat JBoss BPM Suite server in the mode of your choosing (standalone or domain, more information in Section 5.1, “Starting Server”) and connect to it to validate the installation. Click Next to get to the last screen where you can generate the installation script and properties file. Click Done to quit the installer.

You have successfully installed Red Hat JBoss BPM Suite using the installer.

2.1.2. Installing Red Hat JBoss BPM Suite Using Installer in CLI Mode

The installer for Red Hat JBoss BPM Suite can also be executed through the command-line interface (CLI). The procedure below demonstrates the steps that you are likely to encounter using this option to install Red Hat JBoss BPM Suite.

Prerequisite

Before attempting to install Red Hat JBoss BPM Suite, ensure you have already installed Red Hat JBoss EAP 6, version 6.4.7 or higher, and create a back up. Ensure that your user has sufficient rights to complete the installation.

Make sure you have the JAR binary present in $PATH before running the installer. On Red Hat Enterprise Linux, it is present in the package java-$JAVA_VERSION-openjdk-devel.

  1. Navigate to the folder where you downloaded the installer file in a command prompt and execute the following command.

    java -jar jboss-bpmsuite-VERSION-installer.jar -console
  2. The command-line interactive process will start and display the End-User license agreement. You will be prompted to select an option at the end of this license:

    press 1 to continue, 2 to quit, 3 to redisplay.
  3. Enter 1 to begin the installation and type in the parent directory of an existing Red Hat JBoss EAP installation.

    The location below must specify the JBOSS_HOME of an existing EAP installation.
    
    [/home/user/BPMSuite-VERSION/jboss-eap-6.4]

    The installer will verify the location of the Red Hat JBoss EAP installation at the provided location. Enter 1 to confirm and continue.

  4. Optional: create a user for the management console of Red Hat JBoss EAP (ManagementRealm):

    Create an administrative user
    This user will be added to the host container's management realm for administrative purposes. It can be used to access the management console, the management CLI or other applications secured in this realm.

    Enter 0 to skip creating a new administrative user or 1 to create one. If you do decide to create one, then follow these steps:

    1. Enter a user name:

      Admin username: [admin]
    2. Create and confirm a password for the user of the EAP management console:

      The password must have at least 8 characters, and contain at least one number and one non-alphanumeric symbol (not including the character &).
      
      Admin password: []
      
      Confirm admin password: [******************************]

    After this user has been created successfully, continue to the next step.

  5. Create a Red Hat JBoss BPM Suite administrator user.

    Create a Business Process Management Suite Admin User
    Create a BPM Suite admin user. The user will be added to the ApplicationRealm, and can be used to access the Business Central Console. The User will be assigned the 'admin' application roles. The BPM Suite username cannot be any of the following: 'admin', 'analyst', 'user', 'manager' or 'developer'.
    
    BPM Suite username: [bpmsAdmin]
    Important

    Make sure that the selected user name does not conflict with any known title of a role or a group.

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

  6. Enter a user name for this user and then create and confirm a password.

    The password must have at least 8 characters, and contain at least one number and one non-alphanumeric symbol (not including the character &).
    
    BPM Suite password: []
    
    Confirm BPM Suite password: [****************]
  7. After the passwords have been entered and confirmed, you will be given an optional step to define other roles for this user (besides the admin role). Enter these roles in a comma-separated list or just press Enter to skip this part.

    (Optional) You can add this user to additional roles that will be used for task management.  These roles are custom named and used again when building your processes with human tasks.  Add your custom named roles in a comma separated list below.
    
    Additional user roles: []
  8. Configure the Java Security Manager by either pressing 1 to select it or 0 to deselect it.

    Configure the Java Security Manager
    A Java security manager offers JVM level security beyond what is provided by the application container. It enforces access rules at the JVM runtime based on one or more security policies.
    
    This installer will place two security policies in the installation directory with the filenames 'security.policy' and 'kie.policy' regardless of choice. Those policies will be enabled at runtime if the option below is selected.
    
    Please note that a security manager imposes a significant performance overhead when enabled. It is suggested the included policies be applied in production if user requirements call for a stronger measure than what is already provided by the application container's authentication and authorization mechanism.
    
    Please see the JBoss Business Process Management Suite administrative documentation for further details and consideration.
    [ ] Enable the Java security manager
    Input 1 to select, 0 to deselect:
  9. After the Java Security Manager choice, choose an option from the prompt below:

    press 1 to continue, 2 to quit, 3 to redisplay.
  10. Specify whether or not you are using IPv6.

    IPv6 configuration
    
    If this computer is using a pure IPv6 configuration, please check the box below. A pure IPv6 setup requires additional configuration at runtime to ensure the proper bindings of the management and http interfaces.
    [ ] Enable pure IPv6 configuration
    Input 1 to select, 0 to deselect:

    After selecting or deselecting IPv6 configuration, select one of the following options:

    press 1 to continue, 2 to quit, 3 to redisplay.
  11. Configure the runtime environment by either choosing the default configuration or advanced options.

    Configure runtime environment
    Red Hat JBoss Business Process Management Suite can be further customized at this time.
    0  [x] Perform default configuration
    1  [ ] Perform advanced configuration

    If you select 1, Perform advanced configuration, complete the following configurations:

    1.   [ ] Install password vault
      Input 1 to select, 0 to deselect:
    2.   [ ] Enable SSL security
      Input 1 to select, 0 to deselect:
    3.   [ ] Secure EAP Management Console with LDAP
      Input 1 to select, 0 to deselect:
    4.   [ ] Secure Business Central and Dashbuilder with LDAP
      Input 1 to select, 0 to deselect:
    5.   [ ] Add a security-domain
      Input 1 to select, 0 to deselect:
    6.   [ ] Generate JMS Client Keystores
      Input 1 to select, 0 to deselect:
    7.   [ ] Install clustered configuration
      Input 1 to select, 0 to deselect:
    8.   [ ] Install Business-Central Datasource
      Input 1 to select, 0 to deselect:
    9.   [ ] Install Dashbuilder Datasource
      Input 1 to select, 0 to deselect:
    10.   [ ] Configure Optaplanner Execution Server
      Input 1 to select, 0 to deselect:
    11.   [ ] Configure KIE Server management
      Input 1 to select, 0 to deselect:
  12. Next, choose an option from the prompt below:

    press 1 to continue, 2 to quit, 3 to redisplay.
  13. The .jar file begins the unpacking and configuration.
  14. After a successful installation, the command line will ask you if you would like to generate an automatic installation script and properties file.

    Installation has completed successfully.
    Application installed on /home/user/BPMSuite-VERSION/jboss-eap-6.4
    Would you like to generate an automatic intallation script and properties file?
    (y/n) [n]:
  15. If you select y, provide a path for the automatic installation script:

    Select path for the automatic installation script: [/home/user/BPMSuite-VERSION/jboss-eap-6.4/AUTO_SCRIPT_FILENAME]

    This generated script will enable the user to run the installer in the following way for future installations:

    java -jar jboss-bpmsuite-VERSION-installer.jar AUTO_SCRIPT_FILENAME
    Note

    Running the installer in this way will result in an installation identical to the installation from which the auto script was generated. Note that sensitive values, such as passwords, will need to be provided from an external file or provided at auto installation time. The optional argument below enables the user to provide these values automatically:

    -variablefile VARIABLE_FILENAME

    Sensitive values can also be provided using the following argument:

    -variables key1=value1,key2=value2
  16. The command-line will provide the following message upon a successful auto script creation and/or console installation:

    XML written successfully.
    [ Console installation done ]
    [BPMS_Installer]$
  17. Start Red Hat JBoss EAP as described in Section 5.1, “Starting Server”.
  18. Navigate to http://localhost:8080/business-central in a web browser.
  19. Log in with the correct user name/password as given to the Red Hat JBoss BPM Suite user in the Create and confirm a password for the Red Hat JBoss BPM Suite user step.

2.1.3. Troubleshooting Red Hat JBoss BPM Suite Installer

The Red Hat JBoss BPM Suite installation failed. How do I reinstall Red Hat JBoss BPM Suite?

If the installer detects Red Hat JBoss BPM Suite applications, the installation will not continue. In case of a failed installation:

  1. Change into EAP_HOME/standalone/deployments.
  2. Delete all Red Hat JBoss BPM Suite deployments, that is:

    • business-central.war
    • dashbuilder.war
    • kie-server.war
  3. Start the installer again.

2.2. Installing Red Hat JBoss BPM Suite on Red Hat JBoss Enterprise Application Platform

To install Red Hat JBoss BPM Suite 6.4 deployable on Red Hat JBoss EAP 6.4 or later, perform the following tasks:

  1. Download the Red Hat JBoss Enterprise Application Platform 6.4.0 or Red Hat JBoss Enterprise Application Platform 7.0 ZIP file from the Customer Portal.
  2. Extract the ZIP file. This location is your EAP_HOME.
  3. Patch the Red Hat JBoss EAP to the supported version for your Red Hat JBoss BPM Suite version.

  4. Download the Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 6 ZIP file.
  5. Extract the file and copy jboss-eap-6.4/bin/* into EAP_HOME/bin/*. When asked, merge the directories.

    1. If you want to run Red Hat JBoss BPM Suite in the standalone mode:

      • Copy jboss-eap-6.4/standalone/configuration/* into EAP_HOME/standalone/configuration/.
      • Copy jboss-eap-6.4/standalone/deployments/* into EAP_HOME/standalone/deployments/.

        Note

        If you already have deployments on your Red Hat JBoss EAP, ensure that your current deployments do not have colliding names with Red Hat JBoss BPM Suite deployments.

    2. If you want to run Red Hat JBoss BPM Suite in the domain mode:

      • Copy jboss-eap-6.4/domain/configuration/* into EAP_HOME/domain/configuration/.

        Warning

        Make sure this step is performed by the same user account that was used to install Red Hat JBoss EAP. This account must not be a superuser account.

  6. Add an application user:

    ./EAP_HOME/bin/add-user.sh -a --user bpmsAdmin --password password@1 --role kie-server,admin,rest-all,analyst

Starting Red Hat JBoss BPM Suite in Standalone Mode

  1. Change into EAP_HOME/bin.
  2. Execute:

    In a Unix environment:

    ./standalone.sh

    In a Windows environment:

    standalone.bat

You can now log into Business Central in your web browser: localhost:8080/business-central.

Configuring Domain Mode

If you installed Red Hat JBoss BPM Suite as described in Section 2.2, “Installing Red Hat JBoss BPM Suite on Red Hat JBoss Enterprise Application Platform”, deploy Red Hat JBoss BPM Suite web applications manually.

The business-central.war, dashbuilder.war, and kie-server.war applications are supplied in the Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 6 ZIP file as directories. To deploy the applications into domain mode:

  1. Package the application directories into archives:

    1. Extract the following files from the Red Hat JBoss BPM Suite 6.4.0 Deployable for EAP 6 ZIP file:

      • jboss-eap-6.4/standalone/deployments/business-central.war
      • jboss-eap-6.4/standalone/deployments/kie-server.war
      • jboss-eap-6.4/standalone/deployments/dashbuilder.war
    2. Create a ZIP file with the content of the business-central.war, kie-server.war, and kie-server.war directories, for example:

      1. Change into the directory:

         cd business-central.war
      2. Execute zip -r business-central.war . to create a ZIP file of the content of the business-central.war directory.
      3. Repeat this procedure for all the web applications you want to deploy.

        This ensures that business-central.war, kie-server.war, and dashbuilder.war are archives, not directories.

  2. Deploy the archives:

    1. Add a management user:

      ./EAP_HOME/bin/add-user.sh -b --user mgmtAdmin --password password@1 --role admin
    2. Execute ./EAP_HOME/bin/domain.sh.
    3. Log into http://localhost:9990/ using your management user.
    4. Click DeploymentsContent RepositoryAdd.
    5. Select and upload the web archive from the file system.
    6. Select the deployment and click Assign.

      Note

      If you want to deploy multiple Red Hat JBoss BPM Suite nodes on a single machine, set ports and other properties before assigning the deployment to a server. See the section called “Red Hat JBoss BPM Suite Settings for Red Hat JBoss EAP” for more information.

    7. Select the server group.

You can now log into Business Central at localhost:8080/business-central.

Note

To log into Business Central deployed on Host Controller (HC) machines, the user created on the Domain Controller machine has to be created on the Host Controller machines as well, by following the steps in Section 4.2, “Creating Users”.

Configuring Unified Execution Servers

To configure Business Central to manage the Intelligent Process Server and use the same data source, follow the instructions in the Unified Execution Servers section of the Red Hat JBoss BPM Suite Administration and Configuration Guide.

The JVM properties in the *.xml files referenced in the procedure are already present but commented out. It is sufficient to uncomment them.

Red Hat JBoss BPM Suite Settings for Red Hat JBoss EAP

If you want to run multiple instances of Red Hat JBoss EAP with Red Hat JBoss BPM Suite, the best practice is to set the following properties:

  • org.uberfire.nio.git.dir
  • org.uberfire.metadata.index.dir
  • org.uberfire.nio.git.ssh.cert.dir

When multiple Red Hat JBoss BPM Suite nodes are used on a single machine, the below properties need to be specified:

  • org.uberfire.nio.git.daemon.host: can be localhost.
  • org.uberfire.nio.git.daemon.port
  • org.uberfire.nio.git.ssh.host: can be localhost.
  • org.uberfire.nio.git.ssh.port
Note

Both the org.uberfire.nio.git.daemon.port and the org.uberfire.nio.git.ssh.port require different port values to avoid port conflicts.

Set the properties in the EAP_HOME/domain/configuration/host.xml file:

Node A:

<system-properties>
  <property name="org.uberfire.nio.git.dir" value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.metadata.index.dir"
            value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.cert.dir"
            value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.nio.git.daemon.host"
            value="10.10.10.10" boot-time="false"/>
  <property name="org.uberfire.nio.git.daemon.port" value="9417" boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.host" value="10.10.10.10" boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.port" value="8002" boot-time="false"/>
</system-properties>

Node B:

<system-properties>
  <property name="org.uberfire.nio.git.dir" value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.metadata.index.dir"
            value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.cert.dir"
            value="/valid/path/.." boot-time="false"/>
  <property name="org.uberfire.nio.git.daemon.host"
            value="10.10.10.10" boot-time="false"/>
  <property name="org.uberfire.nio.git.daemon.port" value="9418" boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.host" value="10.10.10.10" boot-time="false"/>
  <property name="org.uberfire.nio.git.ssh.port" value="8003" boot-time="false"/>
</system-properties>

The system properties depicted above should indicate the host, port, or location of the .index or .niogit files. These files, which should be used by a respective node, would then be grouped in a particular domain.

2.3. 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 the business-central.war, dashbuilder.war, and kie-server.war web applications.
  • jboss-bpmsuite-VERSION-engine.zip: supported execution engine libraries for embedding the engine into your application and other libraries needed for generic deployment.

2.3.1. Downloading Generic Deployable Package

To download the generic deployable Red Hat JBoss BPM Suite package for JBoss Web Server, do the following:

  1. Go to the Red Hat Customer Portal and log in.
  2. Click DOWNLOADS at the top of the page.
  3. From the list of products, choose Red Hat JBoss BPM Suite.
  4. From the Version drop-down menu, select version 6.4 (if not already selected).
  5. In the Software Downloads section that comes up, navigate to the Red Hat JBoss BPM Suite 6.4 Deployable for All Supported Containers row and then click Download.
  6. Also navigate to the Red Hat JBoss BPM Suite 6.4 Core Engine row and click Download to download the Red Hat JBoss BPM Suite Core Engine files.

2.3.2. Installing 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):

Important

In a fresh Red Hat JBoss BPM Suite 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.

2.3.2.1. Setting up Transaction Manager for Red Hat JBoss Web Server version 2.1 with Tomcat 7 and version 3.0 with Tomcat 8

  1. Extract the generic deployable ZIP package you downloaded from the Red Hat Customer Portal to a temporary location. This ZIP package contains the following three web application archives: business-central.war , dashbuilder.war, and kie-server.war in an exploded format. Rename these folders to remove the war extension.
  2. 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/.

  3. Extract the contents of the Red Hat JBoss BPM Suite Core Engine files archive to a temporary location from where you can copy the required libraries. This folder now contains all the core Red Hat JBoss BPM Suite libraries under the extracted folder and a lib folder.
  4. 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-bpmsuite-VERSION-deployable-generic.zip and jboss-bpmsuite-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" />
  5. Install the driver to your database.

    Copy the JAR file with the relevant database driver to $TOMCAT_DIR/lib/.

    Driver to the Embedded H2 Database

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

  6. 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).

      Make sure to change the values in the following definitions to match your environment.

      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

      Example 2.6. PostgreSQL Data Source Definition

      resource.ds1.className=org.postgresql.xa.PGXADataSource
      resource.ds1.uniqueName=jdbc/jbpm
      resource.ds1.minPoolSize=0
      resource.ds1.maxPoolSize=10
      resource.ds1.driverProperties.serverName=localhost
      resource.ds1.driverProperties.databaseName=bpm641tomcat
      resource.ds1.driverProperties.portNumber=5432
      resource.ds1.driverProperties.user=dbuser
      resource.ds1.driverProperties.password=dbpassword
      resource.ds1.allowLocalTransactions=true
  7. 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" />
  8. Define the btm.root system property and location where Bitronix configuration file is placed:

    In $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 -Ddesignerdataobjects=false"

    The java.security.auth.login.config property must be set in order for the ssh clone of the Git repository to work.

    Note

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

    Tomcat on Microsoft Windows Systems

    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 -Djbpm.tsr.jndi.lookup=java:comp/env/TransactionSynchronizationRegistry -Ddesignerdataobjects=false"

2.3.2.2. Setting up Business Central for Red Hat JBoss Web Server version 2.0 with Tomcat 7 and version 3.0 with Tomcat 8

To set up Business Central, do the following:

  1. Set up a Valve so that the Business Central web application can load the users set up in Tomcat:

    1. Define users and roles in $TOMCAT_DIR/conf/tomcat-users.xml. Note that Business Central requires users to have the roles specified as admin and/or analyst (for more information about user and role definitions, see the Tomcat 7 documentation).

      Important

      Make sure that the selected user name does not conflict with any known title of a role or a group.

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

      The program listing below shows an example of how these two roles would be added and how a user named bpmsadmin will be assigned these roles.

      <role rolename="admin"/>
      <role rolename="analyst" />
      <user username="bpmsadmin" password="P@ssw0rd" roles="admin,analyst"/>
    2. Move (not copy) kie-tomcat-integration-VERSION.jar from the extracted jboss-bpmsuite-VERSION-engine.zip to $TOMCAT_DIR/lib/.
    3. Copy jboss-jaxb-api-VERSION.jar from $TOMCAT_DIR/webapps/business-central/WEB-INF/lib/ to $TOMCAT_DIR/lib/.
  2. 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 property 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>
  3. You can now start the JBoss Web Server to log into Business Central.

    1. Run startup.sh in the $TOMCAT_HOME/bin directory.

      ./startup.sh
    2. Navigate to http://localhost:8080/business-central in a web browser.
    3. Login with the user name/password you defined earlier in tomcat-users.xml file.

2.3.2.3. Setting up Intelligent Process Server for Red Hat JBoss Web Server version 2.0 with Tomcat 7 and version 3.0 with Tomcat 8

After setting up Business Central, it is necessary to configure data sources for the Intelligent Process Server (kie-server) as well. Otherwise, Intelligent Process 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

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

Intelligent Process 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

2.3.2.4. Setting up Dashbuilder for Red Hat JBoss Web Server version 2.0 with Tomcat 7 and version 3.0 with Tomcat 8

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.3.2.2, “Setting up Business Central for Red Hat JBoss Web Server version 2.0 with Tomcat 7 and version 3.0 with Tomcat 8”. 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:

  1. Define users and roles in $TOMCAT_DIR/conf/tomcat-users.xml. Note that Dashbuilder requires users to have the role specified as admin and/or analyst. If you have already defined these users earlier for Business Central, you do not need to define them again.
  2. 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" />
  3. As with Business Central setup, if you are using a database other than the default and integrated H2 database, you will need to set up persistence.

    In this procedure, you configure a data source with the JNDI name jdbc/dashbuilderDS as defined in uniqueName=jdbc/jbpm in the Bitronix resources.properties file:

    1. In dashbuilder/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/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" />
    2. In dashbuilder/WEB-INF/web.xml, add the data source JNDI name in the <res-ref-name> element with your data source 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>
    3. In dashbuilder/META-INF/context.xml, define the transaction factory:

      <Transaction factory="bitronix.tm.BitronixUserTransactionObjectFactory"/>
    4. Update the data source 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>
  4. Restart Java Web Server for these changes to take effect. Once restarted, you can navigate to Dashbuilder from within Business Central or directly at http://localhost:8080/dashbuilder.