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.

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.

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.

1. On the command line, change to the EAP_HOME/bin/ directory.

2. In a Unix environment, run:

   ./standalone.sh

   In a Windows environment, run:

   ./standalone.bat

1. On the command line, change to the EAP_HOME/bin/ directory.

2. In a Unix environment, run:

   ./domain.sh

   In a Windows environment, run:

   ./domain.bat

1. In Configure runtime environment, select Install clustered configuration and click Next.
2. Select the JDBC vendor for your database.

3. Provide the corresponding driver JAR(s):

   • Select one or more files on the filesystem.
   • Provide one or more URLs. The installer downloads the files automatically.

   The installer copies the JAR(s) into EAP_HOME/modules and creates corresponding module.xml file.

   Figure 5.2. JDBC Driver Setup

   

4. Enter the url, username, and password for accessing the database used by Quartz.

   The installer creates:

   • The Quartz definition file in EAP_HOME/domain/configuration/quartz-definition.properties

   • Two Quartz data sources in EAP_HOME/domain/domain.xml

     Edit the domain.xml file to customize the setup.

     Note

     During the installation, Quartz DDL scripts will be run on the database selected in this step. The scripts make changes needed for Quartz to operate, such as adding tables. You can view the scripts in EAP_HOME/jboss-brms-bpmsuite-6.4-supplementary-tools/ddl-scripts. No modifications should be necessary.

     Figure 5.3. Quartz Database Configuration

     

5. Click Next to initiate the installation.

   Important

   When using the JAR installer, the war archives are automatically created from the applications in EAP_HOME/standalone/deployments/. That means additional space is necessary as the applications exist both in uncompressed and compressed state in the storage during the installation.

   Three ZooKeeper instances are created in EAP_HOME/jboss-brms-bpmsuite-6.4-supplementary-tools/ in directories zookeeper-one, zookeeper-two, and zookeeper-three.

1. Change into EAP_HOME/jboss-brms-bpmsuite-6.4-supplementary-tools/helix-core.

2. Execute the launch script:

   On UNIX systems:

   ./startCluster.sh

   On Windows:

   ./startCluster.bat

3. Change into EAP_HOME/bin.

4. Execute the following script to start Red Hat JBoss EAP:

   On UNIX systems:

   ./domain.sh

   On Windows:

   ./domain.bat

1. Start all your ZooKeeper servers, for example:

   On UNIX systems:

   ./ZOOKEEPER_HOME_ONE/bin/zkServer.sh start &
   ./ZOOKEEPER_HOME_TWO/bin/zkServer.sh start &
   ./ZOOKEEPER_HOME_THREE/bin/zkServer.sh start &

   On Windows:

   ZOOKEEPER_HOME_ONE/bin/zkServer.cmd start
   ZOOKEEPER_HOME_TWO/bin/zkServer.cmd start
   ZOOKEEPER_HOME_THREE/bin/zkServer.cmd start

2. Make the Helix Controller aware of the ZooKeeper instance(s). For example:

   ./HELIX_HOME/bin/run-helix-controller.sh --zkSvr localhost:2181,localhost:2182,localhost:2183 --cluster bpms-cluster 2>&1 > /tmp/controller.log &

3. Change into EAP_HOME/bin and start Red Hat JBoss EAP:

   On UNIX systems:

   ./domain.sh

   On Windows:

   ./domain.bat

4. You can access your Red Hat JBoss BPM Suite nodes. For example, if you created Red Hat JBoss BPM Suite cluster by using the installer, you can access your nodes at:

   localhost:8080/business-central
   localhost:8230/business-central

1. Stop the instance of Red Hat JBoss EAP, or the container you are using.

2. Stop the Helix Controller process.

   On UNIX systems, find the PID of the process:

   ps aux|grep HelixControllerMain

   Once you have the PID, terminate the process:

   kill -15 <pid of HelixControllerMain>

   On Windows, use the Task Manager to stop the process.

3. Stop the ZooKeeper server(s). For each server instance, execute:

   On UNIX systems:

   ./ZOOKEEPER_HOME_ONE/bin/zkServer.sh stop
   ./ZOOKEEPER_HOME_TWO/bin/zkServer.sh stop
   ./ZOOKEEPER_HOME_THREE/bin/zkServer.sh stop

   On Windows:

   ZOOKEEPER_HOME_ONE/bin/zkServer.cmd stop
   ZOOKEEPER_HOME_TWO/bin/zkServer.cmd stop
   ZOOKEEPER_HOME_THREE/bin/zkServer.cmd stop

1. Configure ZooKeeper and Helix according to Section 5.6.1, “Setting a Cluster”.
2. Configure Quartz according to Section 5.6.3, “Setting Quartz”.
3. Install the JDBC driver. See the Install a JDBC Driver with the Management Console chapter of the Red Hat JBoss EAP Administration and Configuration Guide.
4. Configure the data source for the server. Based on the mode you use, open domain.xml or standalone.xml, located at EAP_HOME/MODE/configuration.

5. Locate the full profile, and do the following:

   1. Add the definition of the main data source used by Red Hat JBoss BPM Suite.

      Example 5.1. PostgreSQL Data Source Defined as Main Red Hat JBoss BPM Suite Data Source

      <datasource jndi-name="java:jboss/datasources/psbpmsDS"
                  pool-name="postgresDS" enabled="true" use-java-context="true">
        <connection-url>jdbc:postgresql://localhost:5432/jbpm</connection-url>
        <driver>postgres</driver>
        <security>
          <user-name>bpms</user-name>
          <password>bpms</password>
        </security>
      </datasource>

   2. Add the definition of the data source for the Quartz service.

      Example 5.2. PostgreSQL Data Source Defined as Quartz Data Source

      <datasource jta="false" jndi-name="java:jboss/datasources/quartzNotManagedDS"
                  pool-name="quartzNotManagedDS" enabled="true" use-java-context="true">
        <connection-url>jdbc:postgresql://localhost:5432/jbpm</connection-url>
        <driver>postgres</driver>
        <security>
          <user-name>bpms</user-name>
          <password>bpms</password>
        </security>
      </datasource>

   3. Define the data source driver.

      Example 5.3. PostgreSQL Driver Definition

      <driver name="postgres" module="org.postgresql">
        <xa-datasource-class>org.postgresql.xa.PGXADataSource</xa-datasource-class>
      </driver>

   4. If you are deploying Red Hat JBoss BPM Suite on Red Hat JBoss EAP 7.0, ensure that the data sources contain schemas. To create the data source schemas, you can use the DDL scripts located in jboss-bpmsuite-brms-6.4-supplementary-tools.zip. If your data source does not contain schemas, ensure your nodes start one at a time.

      Additionally, when deploying on Red Hat JBoss EAP 7.0, open EAP_HOME/domain/business-central.war/WEB-INF/classes/META-INF/persistence.xml and change the property hibernate.hbm2ddl.auto="update" to hibernate.hbm2ddl.auto="none".

6. Configure individual server nodes that belong to the main-server-group in the EAP_HOME/domain/configuration/host.xml file with properties defined in Cluster Node Properties.

   When configuring a Red Hat JBoss EAP cluster with Apache ZooKeeper, a different number of Red Hat JBoss EAP nodes than Apache ZooKeeper nodes is possible. However, having the same node count for both ZooKeeper and Red Hat JBoss EAP is considered best practice.

   Cluster Node Properties

   jboss.node.name

   A node name unique in a Red Hat JBoss BPM Suite cluster.

   Values	Default
   String	N/A

   org.uberfire.cluster.id

   The name of the Helix cluster, for example: kie-cluster. You must set this property to the same value as defined in the Helix Controller.

   Values	Default
   String	N/A

   org.uberfire.cluster.local.id

   The unique ID of the Helix cluster node. Note that ':' is replaced with '_', for example node1_12345.

   Values	Default
   String	N/A

   org.uberfire.cluster.vfs.lock

   The name of the resource defined on the Helix cluster, for example: kie-vfs.

   Values	Default
   String	N/A

   org.uberfire.cluster.zk

   The location of the Zookeeper servers.

   Values	Default
   String of the form host1:port1,host2:port2,host3:port3,…​	N/A

   org.uberfire.metadata.index.dir

   The location of the .index directory, which Apache Lucene uses when indexing and searching.

   Values	Default
   Path	Current working directory

   org.uberfire.nio.git.daemon.host

   If the Git daemon is enabled, it uses this property as the localhost identifier.

   Values	Default
   URL	localhost

   org.uberfire.nio.git.daemon.hostport

   When running in a virtualized environment, the host’s outside port number for the Git daemon.

   Values	Default
   Port number	9418

   org.uberfire.nio.git.daemon.port

   If the Git daemon is enabled, it uses this property as the port number.

   Values	Default
   Port number	9418

   org.uberfire.nio.git.dir

   The location of the directory .niogit. Change the value for example for backup purposes.

   Values	Default
   Path	Current working directory

   org.uberfire.nio.git.ssh.host

   If the SSH daemon is enabled, it uses this property as the localhost identifier.

   Values	Default
   URL	localhost

   org.uberfire.nio.git.ssh.hostport

   When running in a virtualized environment, the host’s outside port number for the SSH daemon.

   Values	Default
   Port number	8003

   org.uberfire.nio.git.ssh.port

   If the SSH daemon is enabled, it uses this property as the port number.

   Values	Default
   Port number	8001

   Example 5.4. Cluster nodeOne Configuration

   <system-properties>
     <property name="org.uberfire.nio.git.dir" value="/tmp/bpms/nodeone"
               boot-time="false"/>
     <property name="jboss.node.name" value="nodeOne" boot-time="false"/>
     <property name="org.uberfire.cluster.id" value="bpms-cluster" boot-time="false"/>
     <property name="org.uberfire.cluster.zk"
               value="server1:2181,server2:2182,server3:2183" boot-time="false"/>
     <property name="org.uberfire.cluster.local.id" value="nodeOne_12345"
               boot-time="false"/>
     <property name="org.uberfire.cluster.vfs.lock" value="vfs-repo" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.host" value="nodeOne"/>
     <property name="org.uberfire.nio.git.daemon.port" value="9418" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.hostport" value="9418"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.port" value="8003" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.hostport" value="8003" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.host" value="nodeOne"/>
     <property name="org.uberfire.metadata.index.dir" value="/tmp/jbpm/nodeone"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.cert.dir" value="/tmp/jbpm/nodeone"
               boot-time="false"/>
     <property name="org.quartz.properties"
               value="/tmp/jbpm/quartz/quartz-db-postgres.properties" boot-time="false"/>
   </system-properties>

   Example 5.5. Cluster nodeTwo Configuration

   <system-properties>
     <property name="org.uberfire.nio.git.dir" value="/tmp/bpms/nodetwo"
               boot-time="false"/>
     <property name="jboss.node.name" value="nodeTwo" boot-time="false"/>
     <property name="org.uberfire.cluster.id" value="bpms-cluster" boot-time="false"/>
     <property name="org.uberfire.cluster.zk"
               value="server1:2181,server2:2182,server3:2183" boot-time="false"/>
     <property name="org.uberfire.cluster.local.id" value="nodeTwo_12346"
               boot-time="false"/>
     <property name="org.uberfire.cluster.vfs.lock" value="vfs-repo" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.host" value="nodeTwo" />
     <property name="org.uberfire.nio.git.daemon.port" value="9419" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.hostport" value="9419"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.port" value="8004" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.hostport" value="8004" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.host" value="nodeTwo" />
     <property name="org.uberfire.metadata.index.dir" value="/tmp/jbpm/nodetwo"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.cert.dir" value="/tmp/jbpm/nodetwo"
               boot-time="false"/>
     <property name="org.quartz.properties"
               value="/tmp/jbpm/quartz/quartz-db-postgres.properties" boot-time="false"/>
   </system-properties>

   Example 5.6. Cluster nodeThree Configuration

   <system-properties>
     <property name="org.uberfire.nio.git.dir" value="/tmp/bpms/nodethree"
               boot-time="false"/>
     <property name="jboss.node.name" value="nodeThree" boot-time="false"/>
     <property name="org.uberfire.cluster.id" value="bpms-cluster" boot-time="false"/>
     <property name="org.uberfire.cluster.zk"
               value="server1:2181,server2:2182,server3:2183" boot-time="false"/>
     <property name="org.uberfire.cluster.local.id" value="nodeThree_12347"
               boot-time="false"/>
     <property name="org.uberfire.cluster.vfs.lock" value="vfs-repo" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.host" value="nodeThree" />
     <property name="org.uberfire.nio.git.daemon.port" value="9420" boot-time="false"/>
     <property name="org.uberfire.nio.git.daemon.hostport" value="9420"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.port" value="8005" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.hostport" value="8005" boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.host" value="nodeThree" />
     <property name="org.uberfire.metadata.index.dir" value="/tmp/jbpm/nodethree"
               boot-time="false"/>
     <property name="org.uberfire.nio.git.ssh.cert.dir" value="/tmp/jbpm/nodethree"
               boot-time="false"/>
     <property name="org.quartz.properties"
               value="/tmp/jbpm/quartz/quartz-db-postgres.properties" boot-time="false"/>
   </system-properties>

7. Add management users as instructed in the Administration and Configuration Guide for Red Hat JBoss EAP and application users as instructed in Red Hat JBoss BPM Suite Administration and Configuration Guide.

8. Change to EAP_HOME/bin and start the application server in domain mode:

   On UNIX systems:

   ./domain.sh

   On Windows:

   ./domain.bat

9. Check that the nodes are available.

1. Change the predefined persistence of the application to the required database (PostgreSQL): in persistence.xml change the following:

   1. jta-data-source name to the source defined on the application server (java:jboss/datasources/psbpmsDS).
   2. Hibernate dialect to be match the data source dialect (org.hibernate.dialect.PostgreSQLDialect).
2. Log in as the management user to the server Administration console of your domain and add the new deployments using the Runtime view of the console. Once the deployment is added to the domain, assign it to the correct server group (main-server-group).

Creating an Intelligent Process Server Cluster

1. Change into CONTROLLER_HOME/bin.

2. Add a user with the kie-server role:

   $ ./add-user.sh -a --user kieserver --password kieserver1! --role kie-server

3. Start your controller:

   $ ./standalone.sh

4. Change into SERVER_1_HOME.
5. Deploy kie-server.war. Clustered servers do not need business-central.war or other applications.

6. See the <servers> part of the following host.xml as an example of required properties:

   <server name="server-one" group="main-server-group">
    <system-properties>
     <property name="org.kie.server.location" value="http://localhost:8180/kie-server/services/rest/server"></property> 1
     <property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"></property> 2
     <property name="org.kie.server.controller.user" value="kieserver"></property> 3
     <property name="org.kie.server.controller.pwd" value="kieserver1!"></property> 4
     <property name="org.kie.server.id" value="HR"></property> 5
    </system-properties>
    <socket-bindings port-offset="100"/>
   </server>
   
   <server name="server-two" group="main-server-group" auto-start="true">
    <system-properties>
     <property name="org.kie.server.location" value="http://localhost:8230/kie-server/services/rest/server"></property>
     <property name="org.kie.server.controller" value="http://localhost:8080/business-central/rest/controller"></property>
     <property name="org.kie.server.controller.user" value="kieserver"></property>
     <property name="org.kie.server.controller.pwd" value="kieserver1!"></property>
     <property name="org.kie.server.id" value="HR"></property>
    </system-properties>
    <socket-bindings port-offset="150"/>
   </server>

   1

   org.kie.server.location: URL of the server instance.

   2

   org.kie.server.controller: Comma-separated list of the controller URL(s).

   3

   org.kie.server.controller.user: Username you created for controller authentication. Uses kieserver by default.

   4

   org.kie.server.controller.pwd: Password for controller authentication. Uses kieserver1! by default.

   5

   org.kie.server.id: Server identifier that corresponds to template ID defined by the controller instance. Give the same ID to multiple server instances that represent one template.

   The example above is defined for Red Hat JBoss EAP domain mode. For further list of bootstrap switches, see section Bootstrap Switches of the Red Hat JBoss BPM Suite Administration and Configuration Guide.

7. Repeat the previous step for as many servers as you need. To start Red Hat JBoss EAP in the domain mode, execute:

1. Log into the controller Business Central.
2. Click Deploy → Execution Servers.
3. View the remote servers connected to each template.

1. Download the jboss-bpmsuite-brms-VERSION-supplementary-tools.zip, which contains Apache ZooKeeper, Apache Helix, and Quartz DDL scripts.
2. Unzip the archive: the ZooKeeper directory (ZOOKEEPER_HOME) and the Helix directory (HELIX_HOME) are created.

3. Configure Apache ZooKeeper:

   1. In the ZooKeeper directory, change to conf and execute:

      cp zoo_sample.cfg zoo.cfg

   2. Edit zoo.cfg:

      # The directory where the snapshot is stored.
      dataDir=$ZOOKEEPER_HOME/data/
      
      # The port at which the clients connects.
      clientPort=2181
      
      # Defining ZooKeeper ensemble.
      # server.{ZooKeeperNodeID}={server}:{port:range}
      server.1=localhost:2888:3888
      server.2=localhost:2889:3889
      server.3=localhost:2890:3890

      Note

      Multiple ZooKeeper nodes are not required for clustering.

      Make sure the dataDir location exists and is accessible.

   3. Assign a node ID to each member that will run ZooKeeper. For example, use 1, 2, and 3 for node 1, node 2 and node 3 respectively.

      The ZooKeeper node ID is specified in a field called myid under the data directory of ZooKeeper on each node. For example, on node 1, execute:

      echo "1" > /zookeeper/data/myid

4. Provide further ZooKeeper configuration if necessary.

5. Change to ZOOKEEPER_HOME/bin/ and start ZooKeeper:

   ./zkServer.sh start

   You can check the ZooKeeper log in the ZOOKEEPER_HOME/bin/zookeeper.out file. Check this log to ensure that the ensemble (cluster) is formed successfully. One of the nodes should be elected as leader with the other two nodes following it.

6. Once the ZooKeeper ensemble is started, configure and start Helix. Helix needs to be configured from a single node only. The configuration is then stored by the ZooKeeper ensemble and shared as appropriate.

   Configure the cluster with the ZooKeeper server as the master of the configuration:

   1. Create the cluster by providing the ZooKeeper Host and port as a comma-separated list:

      $HELIX_HOME/bin/helix-admin.sh --zkSvr ZOOKEEPER_HOST:ZOOKEEPER_PORT --addCluster <clustername>

   2. Add your nodes to the cluster:

      HELIX_HOME/bin/helix-admin.sh --zkSvr ZOOKEEPER_HOST:ZOOKEEPER_PORT --addNode <clustername> <name_uniqueID>

      Example 5.7. Adding Three Cluster Nodes

      ./helix-admin.sh --zkSvr server1:2181,server2:2182,server3:2183 --addNode bpms-cluster nodeOne:12345
      ./helix-admin.sh --zkSvr server1:2181,server2:2182,server3:2183 --addNode bpms-cluster nodeTwo:12346
      ./helix-admin.sh --zkSvr server1:2181,server2:2182,server3:2183 --addNode bpms-cluster nodeThree:12347

7. Add resources to the cluster.

   helix-admin.sh --zkSvr ZOOKEEPER_HOST:ZOOKEEPER_PORT  --addResource <clustername> <resourceName> <numPartitions> <stateModelName>

   Learn more about state machine configuration at Helix Tutorial: State Machine Configuration.

   Example 5.8. Adding vfs-repo as Resource

   ./helix-admin.sh --zkSvr server1:2181,server2:2182,server3:2183 --addResource bpms-cluster vfs-repo 1 LeaderStandby AUTO_REBALANCE

8. Rebalance the cluster with the three nodes.

   helix-admin.sh --zkSvr ZOOKEEPER_HOST:ZOOKEEPER_PORT --rebalance <clustername> <resourcename> <replicas>

   Learn more about rebalancing at Helix Tutorial: Rebalancing Algorithms.

   Example 5.9. Rebalancing bpms-cluster

   ./helix-admin.sh --zkSvr server1:2181,server2:2182,server3:2183 --rebalance bpms-cluster vfs-repo 3

   In this command, 3 stands for three bpms-cluster nodes.

9. Start the Helix controller in all the nodes in the cluster.

   Example 5.10. Starting Helix Controller

   ./run-helix-controller.sh --zkSvr server1:2181,server2:2182,server3:2183 --cluster bpms-cluster 2>&1 > ./controller.log &

1. Configure the database. Make sure to use one of the supported non-JTA data sources. Since Quartz needs a non-JTA data source, you cannot use the Business Central data source. In the example code, PostgreSQL with the user bpms and password bpms is used. The database must be connected to your application server.
2. Create Quartz tables on your database to allow timer events synchronization. To do so, use the DDL script for your database, which is available in the extracted supplementary ZIP archive in QUARTZ_HOME/docs/dbTables.

3. Create the Quartz configuration file quartz-definition.properties in JBOSS_HOME/MODE/configuration/ directory and define the Quartz properties.

   Example 5.11. Quartz Configuration File for PostgreSQL Database

   #============================================================================
   # Configure Main Scheduler Properties
   #============================================================================
   
   org.quartz.scheduler.instanceName = jBPMClusteredScheduler
   org.quartz.scheduler.instanceId = AUTO
   
   #============================================================================
   # Configure ThreadPool
   #============================================================================
   
   org.quartz.threadPool.class = org.quartz.simpl.SimpleThreadPool
   org.quartz.threadPool.threadCount = 5
   org.quartz.threadPool.threadPriority = 5
   
   #============================================================================
   # Configure JobStore
   #============================================================================
   
   org.quartz.jobStore.misfireThreshold = 60000
   
   org.quartz.jobStore.class=org.quartz.impl.jdbcjobstore.JobStoreCMT
   org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
   org.quartz.jobStore.useProperties=false
   org.quartz.jobStore.dataSource=managedDS
   org.quartz.jobStore.nonManagedTXDataSource=notManagedDS
   org.quartz.jobStore.tablePrefix=QRTZ_
   org.quartz.jobStore.isClustered=true
   org.quartz.jobStore.clusterCheckinInterval = 20000
   
   #============================================================================
   # Configure Datasources
   #============================================================================
   org.quartz.dataSource.managedDS.jndiURL=jboss/datasources/psbpmsDS
   org.quartz.dataSource.notManagedDS.jndiURL=jboss/datasources/quartzNotManagedDS

   Note the configured data sources that will accommodate the two Quartz schemes at the very end of the file.

   Note

   For MicroSoft SQL Server, add the acquireTriggersWithinLock property to the quartz-definition.properties file:

   org.quartz.jobStore.acquireTriggersWithinLock=true

   Cluster Node Check Interval

   The recommended interval for cluster discovery is 20 seconds and is set in the org.quartz.jobStore.clusterCheckinInterval of the quartz-definition.properties file. Depending on your set up consider the performance impact and modify the setting as necessary.

   The org.quartz.jobStore.driverDelegateClass property that defines the database dialect. If you use Oracle, set it to org.quartz.impl.jdbcjobstore.oracle.OracleDelegate.

4. Provide the absolute path to your quartz-definition.properties file in the org.quartz.properties property. For further details, see _cluster_properties_BRMS.