Bug 1012084

Summary: [Doc Bug Fix] Section about enabling clustering in managed domain mode is incorrect
Product: [JBoss] JBoss Enterprise Application Platform 6 Reporter: Richard Janík <rjanik>
Component: DocumentationAssignee: sgilda
Status: CLOSED CURRENTRELEASE QA Contact: Russell Dickenson <rdickens>
Severity: high Docs Contact:
Priority: unspecified    
Version: 6.2.0CC: jkudrnac, lthon, nziakova, sgilda, smumford, twells, wfink
Target Milestone: ER7Keywords: Documentation
Target Release: EAP 6.3.0Flags: sgilda: needinfo-
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2014-06-28 15:40:21 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Richard Janík 2013-09-25 16:33:16 UTC 
Document URL: 

http://documentation-devel.engineering.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/6.2/html/Development_Guide/Implement_an_HA_Singleton.html

Section Number and Name: 

8.4. Implement an HA Singleton
  -> Procedure 8.3. Implement an HA Singleton Service
    -> 2. Start each JBoss EAP 6 instance with clustering enabled.
      -> a, Enable clustering for servers running in a managed domain.

Describe the issue: 

First off, I'm not an expert on domain mode nor cli, but the examples provided didn't work for me with just unzipped EAP, so although I might have missed something, this section could definitely be improved.

There are several problems with the section:

1,
"You should see the following response:
 Connected to domain controller at 192.168.0.14"

I've seen no such response after correctly connecting to the host controller although I was using 127.0.0.1.

2,
"d. Add the main-server server group."

The main-server-group already exists in default configuration and the cli will complain about duplicate resources.

3,
"e. Create a server named server-one and add it to the main-server server group.
/host=station14Host2/server-config=server-one:add(group=main-server-group,auto-start=false) "

Server named server-one also exists in the default configuration (as does server-two) and the cli will again complain about duplicate resources. Host name station14Host2 also wasn't mentioned before, there probably should be added a note that we assume our hosts name is station14Host2 (as was done with the address of domain controller: "In this example, assume the IP address of the domain controller is 192.168.0.14.").

4,
"g. Create a server named server-two, put it in a separate server group, and set its port offset to 100."

We need to create the second server group - distinct2 - in this case. This should be mentioned.

5,
"b. Open the domain.xml configuration file for editing"

The example in this section is wrong, because it is missing the second server group - distinct2.

I hope this helps.
Comment 1 Ladislav Thon 2014-05-22 13:51:12 UTC 
Some of the issues raised here are still valid, some are not:

1. "I've seen no such response after correctly connecting to the host controller" -- yes, this issue is still valid, no such text is printed

2. "The main-server-group already exists in default configuration" -- no, this issue is NOT valid anymore, the documentation now refers to "scheduler-server-group"

3. "Server named server-one also exists in the default configuration (as does server-two) and the cli will again complain about duplicate resources" -- yes, this issue is still valid when using default domain configuration

4. "We need to create the second server group - distinct2" -- no, this issue is NOT valid anymore, as the documentation now puts server-two into scheduler-server-group; on the other hand, server-two already exists in the default domain configuration so you will get the same error as in issue 3 above

5. "The example in this section is wrong, because it is missing the second server group - distinct2" -- no, this issue is NOT valid anymore, as the example now uses only a single server group

To sum up, from the 5 issues reported, only 1 and 3 are still valid; 2, 4 and 5 are no longer issues.

Also, please consider bug 1087548 -- in short, I believe that major portions of this chapter just duplicate the respective quickstart and could easily be deleted. The quickstart is better maintained and undergoes more rigorous QA.
Comment 2 Ladislav Thon 2014-05-22 13:54:16 UTC 
I forgot to mention -- comment 1 is against Revision 6.3.0-15 of the Development Guide.
Comment 4 sgilda 2014-06-09 20:12:50 UTC 
This can be verified here:

http://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Development_Guide/index.html#Implement_an_HA_Singleton
Comment 5 Richard Janík 2014-06-10 08:58:39 UTC 
The whole subsection has been rewritten and uses standalone servers instead of domain configuration. Looks good, verified.