Red Hat JBoss BRMS Cartridge for OpenShift

Summary

This cartridge provides the Red Hat JBoss BRMS for easy deployment to OpenShift.

Deployment

To try out JBoss BRMS on OpenShift please follow the instructions:

If you want to use the OpenShift create application page, enter the cartridge URI of https://raw.githubusercontent.com/jboss-bpms/openshift-cartridge-brms/master/metadata/manifest.yml in the entry field (at the bottom left of the form).

Or if you want to use the rhc command line type:

rhc create-app -g medium <APP NAME> https://raw.githubusercontent.com/jboss-bpms/openshift-cartridge-brms/master/metadata/manifest.yml

This will output the generated users and passwords for Business Central.

Usage

Access the web application

• In order to access the BRMS Business Central navigate to http://<app_name>-<rh_domain>.<domain>:<port>/business-central

Access into the application shell

To access into the application shell:

rhc ssh <APPLICATION-ID>

Manage users and roles

When you install the cartridge, several users and roles are created. Their passwords are automatically generated for security reasons and displayed during cartridge installation. The following table summarizes this initial setup:

User	Description	Roles
brms-admin	BRMS Administrator	admin
brms-analyst	Business Rules analyst role	analyst

• The application developer can show/add/remove/modify users and roles by using the brms-users.properties and brms-roles.properties files found in the cartridge git repository at .openshift/config/ directory

• Once users or roles files changed, do a git push in order to deploy the new files in the application container configuration path.

• To display the current list of users and their passwords, you can simply run this command in your cartridge repository:

    cat .openshift/config/brms-users.properties
  

• The current assignation of roles can be displayed by running this command in your cartridge repository:

    cat .openshift/config/brms-roles.properties
  

• To create new users, change their passwords or role assignation, you must edit the following files in your cartridge repository.

    vi .openshift/config/brms-users.properties
    vi .openshift/config/brms-roles.properties
  

Manage JBoss EAP configuration

• The main configuration file for JBoss EAP is standalone.xml
• This file is available in your cartridge repository at location .openshift/config/standalone.xml
• Usefull for changing container configurations such as root logger level and so on

Manage Maven configuration

• There are two maven process builds involved in this cartridge:
  1.- Maven build for the developer cartridge git repository maven project
  Build performed when pushing data into the cartridge git repository
  2.- Maven build for the BRMS webapp projects
  Build performed when user hints Build&Deploy button in BRMS application

• Both maven processes uses same Maven settings file available in your cartridge repository at location .openshift/config/settings.xml

• User can use this Maven settings file to take control of the configuration for Maven builds, such as adding or removing external repositories.

Manage welcome root JBoss EAP web application

• The developer cartridge git repository maven project generates a WAR artifact that is used as welcome-root webapp for the application URL.
• You can modify this application and when running a git push in your cartridge git repository, it is built and re-deployed in JBoss EAP.
• The generated WAR artifact is installed in the cartridge local repository, so it can be used as a Maven dependency too.

Clone Git repositories from the web application

• All repositories present in the web application can be cloned
• OpenShift applications have opened by default the HTTPS port (8443).
• If your OpenShift client requires accessing other application public ports, you must perform port forwarding in your station.
• So in order to clone a specific web application repository, first you must perform port-forwarding from the OpenShift server and then run the clone git command (when ports are forwarded).

These are the steps:

1.- Using your rhc client, type the following command: rhc port-forward <APP_NAME>

2.- When executing the above command, a list of forwarded ports will be visible. This ports are forwarded until you finish the rhc client process (executed using port-forward argument). So DO NOT close this terminal until the application repository is fully cloned.

3.- Once OpenShift application ports are forwarded, you can run git clone using this URL: ssh://<app_user>@127.0.0.1:9521/<app_name> (NOTE that the user for the ssh connection is not a system user, is a BRMS application user)

This is an example of cloning a application repository named test-repo using a BRMS application user with login brms-admin. The application name is test-app:

rhc port-forward test-app
git clone ssh://brms-admin@127.0.0.1:9521/test-repo

IMPORTANT NOTE: If when trying to clone the application repository you see this error:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
Someone could be eavesdropping on you right now (man-in-the-middle attack)!
It is also possible that the DSA host key has just been changed.
The fingerprint for the DSA key sent by the remote host is
e7:f6:52:7d:fd:1c:fd:31:5e:a9:8c:bc:6f:d3:19:ed.
Please contact your system administrator.
Add correct host key in ~/.ssh/known_hosts to get rid of this message.
Offending key in ~/.ssh/known_hosts:5
DSA host key for [X.Y.Z.Q]:9521 has changed and you have requested strict checking.
Host key verification failed.
fatal: The remote end hung up unexpectedly

You will have to remove the existing fingerprint for your ssh connection in your ~/.ssh/known_hosts file.

Debugging application code

If you need to debug your application code, you must enable the enable_jpda marker in the cartridge git repository:

cd <app_name>/.openshift/markers/
touch enable_jpda
git add enable_jpda
git commit enable_jpda -m "message"
git push

Once the push is completed successfully, next step is to perform port forwarding:

rhc port-forward <app_name>

You should see something similar to:

Service Local               OpenShift
------- -------------- ---- ----------------
java    127.0.0.1:3528  =>  127.1.244.1:3528
java    127.0.0.1:4447  =>  127.1.244.1:4447
java    127.0.0.1:5445  =>  127.1.244.1:5445
java    127.0.0.1:8080  =>  127.1.244.1:8080
java    127.0.0.1:8787  =>  127.1.244.1:8787
java    127.0.0.1:9520  =>  127.1.244.1:9520
java    127.0.0.1:9521  =>  127.1.244.1:9521
java    127.0.0.1:9990  =>  127.1.244.1:9990
java    127.0.0.1:9999  =>  127.1.244.1:9999

The debug port is 8787. Now you can do remote debugging to 127.0.0.1:8787.