Bug 851365 - [Tech Review] Write a single procedure for installing BRMS deployable to supported containers
[Tech Review] Write a single procedure for installing BRMS deployable to supp...
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise BRMS Platform 5
Classification: JBoss
Component: Documentation (Show other bugs)
BRMS 5.3.1
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: lcarlon
Petr Široký
:
: 842515 862456 870298 (view as bug list)
Depends On: 842515 845905
Blocks:
  Show dependency treegraph
 
Reported: 2012-08-23 19:22 EDT by lcarlon
Modified: 2013-03-06 00:03 EST (History)
4 users (show)

See Also:
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:


Attachments (Terms of Use)

  None (edit)
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.

Thanks
Lee
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.

Thanks,
Petr
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.

Thanks
Lee
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.

Alessandro
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.

Thanks
Lee
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
---------
http://documentation-devel.engineering.redhat.com/docs/en-US/JBoss_Enterprise_BRMS_Platform/5/html/BRMS_Administrator_Guide/Clustering_JBoss_BRMS_with_Jackrabbit2.html

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

Cheers,
Alessandro Lazarotti

Note You need to log in before you can comment on or make changes to this bug.