Bug 851365

Summary: [Tech Review] Write a single procedure for installing BRMS deployable to supported containers
Product: [JBoss] JBoss Enterprise BRMS Platform 5 Reporter: lcarlon <lcarlon>
Component: DocumentationAssignee: lcarlon <lcarlon>
Status: CLOSED CURRENTRELEASE QA Contact: Petr Široký <psiroky>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: BRMS 5.3.1CC: alazarot, brms-jira, jshepherd, psiroky
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Instance Name: Not Defined Build: CSProcessor Builder Version 1.5 Build Filter: null Build Name: Build Date: 23-08-2012 13:10:03
Last Closed: 2013-03-06 00:03:47 EST Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---
Bug Depends On: 842515, 845905    
Bug Blocks:    

Description lcarlon 2012-08-23 19:22:09 EDT
Description of problem:

BRMS is supported on several containers, there should be a installation procedure for installing BRMS, that provides instructions for each container.

Write a procedure that can be followed by users installing to one of the supported containers.
Comment 9 lcarlon 2012-10-11 00:14:23 EDT
Alessandro, Petr,

I think we might need to include some addition sections for EWS, perhaps a config users section in the admin guide, I've already created a section for datasources.

Alessandro, I'll take a look at the KCS article and another look at Petr's document and see what can be included.

Petr, regarding the EAP 6 specific steps, I had initially thought the steps would vary substantially from the other steps for the other containers, but now that I have them written, I think it may be possible to include them with the other containers. I'm going to take a look at that this afternoon, and will post an update as soon as I can.

I'm changing the status back to modified, will put it back on QA as soon as I'm done.

Comment 10 lcarlon 2012-10-18 19:59:05 EDT
*** Bug 862456 has been marked as a duplicate of this bug. ***
Comment 15 lcarlon 2012-10-24 02:54:42 EDT
*** Bug 842515 has been marked as a duplicate of this bug. ***
Comment 16 lcarlon 2012-10-25 02:35:46 EDT
I've added the updates from Alessandro's comments, except for the datasource and transaction information which will be added to the admin guide. 

I'll post a link as soon as the content is live on the doc stage. I'll also post a link to the EWS datasource information after it has been added.

- Lee
Comment 18 Petr Široký 2012-10-30 05:26:45 EDT
Hi Lee,

deployable guide is looking good. 

Sum up what I think is remaining to be done (also from Alessandro's previous comments):

-- Tomcat is not truncating .war extension from the context root of the deployed app. Deployable guide should state that those extensions should be deleted from directory's name (otherwise the URL for e.g Guvnor would be http://<host>/jboss-brms.war instead of just http://<host>/jboss-brms)

-- Datasource and Transaction manager configuration examples (there will be just link to EWS docs right?)

-- just formatting error: last XML listing on Adding Users page is badly indented

I will ask my colleague to check the EAP 6 steps to be sure I did not miss anything.

Comment 19 lcarlon 2012-10-30 16:16:14 EDT
Hi Petr,

-- .war archives: I've added a step (number 4) that instructs EWS users to remove the .war extension from the deployed archives.

I've added a topic to the Admin guide "Configuring a Datasource for JBoss Enterprise Web Server", and have raised BZ870298 to have the content checked.

Step 8 (now step 9) of the installing the deployable package states:

The default configurations use embedded databases that are not suitable or supported for production environments. Before deploying into a production environment, this configuration must be changed to a supported database. Please refer to the BRMS Administration Guide for database configuration instructions.

I haven't made a special reference to the EWS steps there, as all users are instructed to refer to the admin guide, and I have just realized that I need to add a similar topic (configuring datasources) for EAP6 users as well.

-- XML formatting in the final step of the Adding Users section has been fixed.

Comment 20 lcarlon 2012-10-30 17:30:33 EDT
If only we could edit bugzilla comments...

That's step 5 that I've added for renaming .war archives.

Also, as soon as the content is available I'll leave a link.

- Lee
Comment 22 Alessandro Lazarotti 2012-10-31 08:29:11 EDT
Hi Lee,
For Tomcat/EWS, as I've reported before I can't see there any information about jaas and the necessity to setup a external transaction manager (like Bitronix) and how to do that (or linking to some external site).

Those information are mandatory to install BRMS in non-JavaEE servers, like Tomcat.

Comment 25 lcarlon 2012-11-28 00:41:43 EST
*** Bug 870298 has been marked as a duplicate of this bug. ***
Comment 26 lcarlon 2012-11-28 23:08:58 EST
Hi Petr,

I've updated the doc with a link to the bitronix homepage and configuration instructions. I'll post a link as soon as it is live on the doc stage.

Comment 28 Petr Široký 2012-11-29 05:02:05 EST
Hi Lee,

I will try once more to sutup EWS folowing steps in the docs to be sure it's complete. I will comment once I am done and then we could close the issue.

Also before closing this issue I would like to know if Alessandro thinks the guide is OK or if it's still missing something.
Comment 30 Alessandro Lazarotti 2012-11-29 22:39:56 EST
The new documentation looks great, really nice job!
You are right Petr, HornetQ also works with Tomcat, we don't need to change to Mina. Thanks for remembering that it uses bundled HornetQ jars, I've also tested and it works.

I have some few points that I would like to discuss:

Getting Started: Installing the Deployable Package
IMHO we need to add some note about EWS/Tomcat related to TransactionManager and how to configure a database. Ok, it is not necessary be included in the getting started since it is already in Administrator Guide, but we must be say that they *must* be configured. The current text says:
"The default configurations use embedded databases that are not suitable or supported for production environments. Before deploying into a production environment, this configuration must be changed to a supported database. Please refer to the BRMS Administration Guide for database configuration instructions" - it is not true for EWS/Tomcat, there aren't default embedded databases configured and there isn't a transaction manager also, so this should be good be mentioned in this part of the guide.

Getting Started: Password Configuration for JAAS
I think the text must be reviewed here.

"When using the default JAAS authentication system, usernames and passwords need to be synchronized between JBoss Enterprise BRMS, the Process Designer, and the Business Central console. If the same usernames and passwords are not used, the different components will not function together.

*If the additional users are added to the brms-users.properties file*, they also need to be synchronized for the Process Designer and Business Central Console. "

It is not totally true. In fact the Business Central and Process Designer must have *a single* brms user with admin rights (as default is usually uncommented the user admin to access jboss-brms.war which is not configured to use Role-Based Authorization out-of-box, admin/admin will work for Designer and BC) - this is necessary because these web applications need to access the Guvnor API to read the full JCR repository tree. Looking the text it looks like saying that every user need to be synchronized with that files (jbpm.xml and jbpm.console.properties ), this is definitely not necessary.

Getting Started: Cluster

There is an information missing in how to cluster the BRM (Guvnor). The most of customer repositories has large binaries generated for example by packages snapshots or decision tables. These binaries are stored by default in filesystem and can not be clustered, even though using PersistenceManagers configured to databases. Some exceptions can occurr if this is not fixed. To fix this, the repository.xml should use a shared DataStore[1] (must not use a FileDataStore) or case not used a DataStore, then must be configured the property externalBLOBs as false in the PersistenceManagers.

There is a little session in the Jackrabbit configuration explaning this[2]:
"All cluster nodes must point to the same data store location. The data store should be used to store large binaries (all cluster nodes need to access the same data store). When not using the data store, one need to set the parameter externalBLOBs to false so that large binaries are stored in the persistence manager. The file system blob store does not support clustering, because it uses a local directory."

... that is a detail really important which solved some support cases.

[1] http://wiki.apache.org/jackrabbit/DataStore
[2] http://wiki.apache.org/jackrabbit/Clustering#Data_Store_Configuration (DataStoreConfiguration)

Also I am not sure why this topic is placed on "BRMS Administrator Guide > 2. Database Configuration" - in my opinion make senses to be together with Business Central Cluster, in the BRMS Getting Started Guide - usually the administrator will try to configure both applications to a cluster, separated documentation about this is confused.

I think that can be fine this sequence to BRMS Getting Started Guide:

2.1. Installation Options
    2.2.  Installing the Standalone Package
    2.3.  Installing the Deployable Package
    2.4.  Configuring Authentication
    2.5.  Adding Users
    2.6.  Password Configuration for JAAS
    2.7.  Configuring Business Process Management
    2.8.  Clustering the Business Central Console
    2.9.  Clustering JBoss BRMS with Jackrabbit   
    2.10. Starting the Server
    2.11. Logging On

Alessandro Lazarotti