Bug 1309482

Summary: JBoss ON installation guide 3.7. Basic Setup: Installing the Server on Linux, Procedure 3.2, step 5 has no context
Product: [JBoss] JBoss Operations Network Reporter: Marc Shirley <mshirley>
Component: DocumentationAssignee: jon-docs <jon-docs>
Status: CLOSED DUPLICATE QA Contact: Mike Foley <mfoley>
Severity: high Docs Contact:
Priority: low    
Version: JON 3.3.0CC: tkelly
Target Milestone: post-GAKeywords: Triaged
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Build Name: 23084, Installation Guide-3.3-3.3 Build Date: 02-07-2015 06:04:11 Topic ID: 43559-752620 [Latest]
Last Closed: 2017-06-27 07:36:55 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 Marc Shirley 2016-02-17 23:05:14 UTC 
Title: Basic Setup: Installing the Server on Linux

Describe the issue:
JBoss ON 3.3 installation guide 3.7. Basic Setup: Installing the Server on Linux, Procedure 3.2, step 5 has little context in regards to the changes it is suggesting.  The step makes more sense in regards to setting up a service on a Linux machine such as described in section 2.4.2. Running the JBoss ON Server as a Service of the Configuring JON Servers and Agents guide [1].

[1] https://access.redhat.com/documentation/en-US/Red_Hat_JBoss_Operations_Network/3.3/html/Admin_and_Config/starting-the-server.html#running-jon-as-a-service

Suggestions for improvement:
The remedies I see to avoid confusion:
1. Adjust the step to point to the service setup instructions
      Reasoning: This is more relevant towards setting up JON as a Linux service, as there is an implication in the step 5 that they are running as root.  The user could actually already be running as a separate user.

2. Remove step completely
      Reasoning: The service setup instructions already address this process and in a more relevant manner.  The warning about running as root should likely be an introduction to the entire 3.7 section rather than in the middle of the installation instructions (as if they are using root as their login they have already started the server as root in step 4).

3. Clarify and adjust the example in the step 5 to not reference /etc/init.d/rhqctl
      Reasoning: This would likely be marked as an optional step to set the user as a specific user due to us not knowing what user they are currently running the installation as.  The example would need to be adjusted to clarify that the path to 'rhqctl' is in the JBoss ON installation directory rather than /etc/init.d and remove the prior line "#processname: standalone.sh" as it does not exist without the additional steps included in the service setup instructions in the config guide. In my opinion this is the least desired option as it makes assumptions on the users' operating procedures, provides a method to change the rhqctl user after the server is already started, and adds a potential for confusion on a new user that is installing for the first time.

Additional information:
Comment 1 Tyler Kelly 2017-06-14 04:40:15 UTC 
Note: It appears this was changed since the bug was created prior to my changes.
Regardless, the section 3.7 and 3.8 of the install guide (Basic Setup: Installing the server on nix/MS Windows) has been edited to change:
- the customer portal directions to better reflect the layout of the customer portal,
- change program names to reflect RH conventions (For Example: EAP = Red Hat JBoss Enterprise Application Platform, Windows = Microsoft Windows)
- step five to provide greater clarity regarding accessing the web GUI for JON server and setting the web 'portal' access password. 

See Commit: https://gitlab.cee.redhat.com/tkelly/doc-jon-docs/commit/9cd08ef8c125f37a55afd30717418d0310aa5868

Merged Branch: https://gitlab.cee.redhat.com/red-hat-jboss-operations-network-documentation/doc-jon-docs/merge_requests/11

View on Pantheon: 
https://access.qa.redhat.com/documentation/en-us/red_hat_jboss_operations_network/3.3/html-single/installation_guide/#install-rhel-jar
https://access.qa.redhat.com/documentation/en-us/red_hat_jboss_operations_network/3.3/html-single/installation_guide/#install-windows-jar
Comment 2 Tyler Kelly 2017-06-27 07:36:55 UTC 

*** This bug has been marked as a duplicate of bug 1162646 ***