Chapter 2. Installation

This section describes installation of Red Hat JBoss BRMS on an already installed instance of Red Hat JBoss EAP 6.4 or later. If you use a different container, see the Red Hat JBoss BRMS Installation Guide.

If you followed Chapter 1, Quick Start with Red Hat JBoss BRMS, you have already installed Red Hat JBoss BRMS using the JAR installer. See Next Steps for further instructions.

Note

Red Hat JBoss BRMS is designed to work with UTF-8 encoding. If your JVM uses a different encoding system, unexpected errors may occur. To ensure UTF-8 is used by the JVM, use the following system property "-Dfile.encoding=UTF-8".

2.1. Downloading Red Hat JBoss BRMS for Red Hat JBoss EAP

  1. Open the DOWNLOADS section of the Red Hat Customer Portal in your browser.
  2. In the Product Downloads page that opens, click Red Hat JBoss BRMS and log in.
  3. From the Version drop-down menu, select version 6.4.
  4. Select Red Hat JBoss BRMS 6.4.0 Deployable for EAP 6 and click Download. If you use Red Hat JBoss EAP 7.0, select Red Hat JBoss BRMS 6.4.0 Deployable for EAP 7.

2.2. Installing Red Hat JBoss BRMS on Red Hat JBoss Enterprise Application Platform

2.2.1. Installation on a New Red Hat JBoss EAP Instance

To install the deployable package for a Red Hat JBoss Enterprise Application Platform:

  1. Move the ZIP archive you downloaded in Section 2.1, “Downloading Red Hat JBoss BRMS for Red Hat JBoss EAP” to the parent directory of the Red Hat JBoss Enterprise Application Platform home directory (referred to as EAP_HOME; the jboss-eap-6.4 directory).

  2. Unzip the downloaded ZIP archive and ensure it is merged into the EAP_HOME directory (jboss-eap-6.4).

    Warning

    Perform this step with the same user account that was used to install Red Hat JBoss EAP. This account must not be a superuser account.

  3. When prompted, overwrite the files that already exist in the EAP_HOME directory with with files from the downloaded ZIP archive.

2.2.2. Installation on an Existing Red Hat JBoss EAP Configuration

Warning

These instructions are for installing, and not for updating an existing Red Hat JBoss BRMS instance. Make sure that there is no existing Red Hat JBoss BRMS install in the target EAP.

To install the deployable package on a previously configured Red Hat JBoss EAP:

  1. Extract the ZIP package deployable for Red Hat JBoss EAP you downloaded in Section 2.1, “Downloading Red Hat JBoss BRMS for Red Hat JBoss EAP”.

  2. Unzip the downloaded ZIP archive; however, do not overwrite all of the files. Manually merge the following files into the EAP_HOME directory (jboss-eap-6.4):

    • jboss-eap-6.4/domain/configuration/* Be aware that Red Hat JBoss BRMS requires JMS, so JMS is added by default into all profiles in domain.xml provided by the Red Hat JBoss BRMS distribution.
    • jboss-eap-6.4/standalone/configuration/* Be aware that Red Hat JBoss BRMS requires JMS, so JMS is added by default into all profiles configuration files, including standalone.xml and standalone-ha.xml, provided by the Red Hat JBoss BRMS distribution.
    Warning

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

  3. Copy the folder jboss-eap-6.4/standalone/deployments into the EAP_HOME directory from the Red Hat JBoss BRMS distribution.

    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 BRMS deployments.

2.3. Defining Roles

Before starting the server and logging into Business Central, you need to create some user accounts. This section describes the different user roles that are used in Red Hat JBoss BRMS:

  • admin: The users with admin role are the administrators of the application. Administrators can manage users, manage the repositories (create and clone) and have full access to make the required changes in the application. Admins have access to all areas within the system.
  • analyst: An analyst role has access to all features to model projects. However, Authoring → Administration access is unavailable to users with the analyst role. Certain lower-level features targeted towards developers, like the Deployment → Artifact Repository view, are not accessible for this role. However, the Build & Deploy button is available for the analyst role while using the Project Editor.

For further information about roles, see section Access Control of the Red Hat JBoss Administration and Configuration Guide. For further information about roles and task interactions, see section User Task of Red Hat JBoss BPM Suite User Guide.

Other roles you can encounter:

  • REST API access control roles. For further information, see section Control of REST API of the Red Hat JBoss BPM Suite Development Guide.
  • The Intelligent Process Server kie-server role. For further information, see chapter Intelligent Process Server and Realtime Decision Server of the Red Hat JBoss BPM Suite Development Guide.
  • The kiemgmt role for the managed repository feature. See section Managing Assets of the Red Hat JBoss BRMS Administration and Configuration Guide.
Note

Enter the above mentioned roles during the user creation process.

2.4. Creating Users

To start adding new users, you will need to run the add-user.sh script on a Unix system or the add-user.bat file on a Windows system from the EAP bin directory.

Procedure: Creating New Users

  1. Change into the EAP_HOME directory.

  2. On a Unix system, run the following command: 

    bin/add-user.sh

    On a Windows system, run: 

    bin\add-user.bat
  3. Enter b to select the application user and press Enter.
  4. Accept the default realm (ApplicationRealm) by pressing Enter.

  5. At the user name prompt, enter the user name and confirm. For example: helloworlduser.

    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, do not create a user with the user name admin.

  6. Create the user password at the password prompt and reenter the password. For example: Helloworld@123.

    Note

    The password should be at least 8 characters in length and should contain upper and lower case alphabetic characters (A-Z, a-z), at least one numerical character (0-9) and at least one special character (for example ~ ! @ # $ % ^ * ( ) - _ + =).

  7. Enter a comma-separated list of roles the user will need at the roles prompt. For more information, see Section 2.3, “Defining Roles”.

    Note that Business Central users need to have the analyst or the admin role assigned.

  8. Confirm that you want to add the user.
  9. Enter yes at the next prompt to enable clustering in the future.

2.5. Starting Server

You can start your server in one of two modes:

  • Standalone, using the standalone.sh script.
  • Standalone-secure, using the standalone-secure.sh script.
Note

If you are starting the server in the domain mode, the corresponding scripts are domain.sh and domain-secure.sh respectively.

The default starting script is standalone.sh. It is optimized for performance. To run your server in the performance mode:

  1. On the command line, change into the EAP_HOME directory:

  2. In a Unix environment run: 

    bin/standalone.sh

    In a Windows environment run: 

    bin\standalone.bat

The standalone-secure.sh script is optimized for security. This script applies a security policy that protects you against a known security vulnerability.

Note

It is recommended that production environments use the standalone-secure.sh script.

Warning

The use of a security manager imposes a significant performance penalty. Consideration your individual circumstances to decide which script to use. For further information, see Section 2.6, “Java Security Manager and Performance Management”.

To start your server in the secure mode:

  1. On the command line, move into the EAP_HOME directory.

  2. In a Unix environment run: 

    bin/standalone-secure.sh

    In a Windows environment run: 

    bin\standalone-secure.bat
Note

If you installed Red Hat JBoss BRMS using the JAR installer, you can choose to apply the security policy during the installation. The installer does not provide a separate standalone-secure.sh script.

2.6. Java Security Manager and Performance Management

Enabling the Java Security Manager (JSM) to sandbox the evaluation of MVEL scripts in Red Hat JBoss BRMS causes a performance hit in high-load environments. When deploying a Red Hat JBoss BRMS application, consider the performance needs in your environment. Use the following guidelines to deploy secure and high performance Red Hat JBoss BRMS applications.

In high-load environments where performance is critical:

  • Deploy applications that have been developed on other systems and properly reviewed.
  • Do not create any users with the analyst role on such systems.

If these safeguards are followed, it is safe to leave JSM disabled on these systems so it does not introduce any performance degradation.

In testing and development environments without high loads, or in environments where rule and process authoring is exposed to external networks:

  • Enable JSM in order to achieve security benefits of properly sandboxed evaluation of MVEL.
  • Do not allow users with the analyst role to log in to the Business Central console with JSM disabled. This practice is not secure and not recommended.