DOC Update cluster installation guide (#1527)

* DOC Update cluster installation guide

* Update install-cluster.md

* Incorporated suggestions and improvements

1 files changed, 82 insertions, 51 deletions

diff --git a/server/sonar-docs/src/pages/setup/install-cluster.md b/server/sonar-docs/src/pages/setup/install-cluster.md
index aea9d3b4dca..c609497421c 100644
--- a/server/sonar-docs/src/pages/setup/install-cluster.md
+++ b/server/sonar-docs/src/pages/setup/install-cluster.md
@@ -9,133 +9,164 @@ _Running SonarQube as a Cluster is only possible with a [Data Center Edition](ht
 
 The Data Center Edition allows SonarQube to run in a clustered configuration to make it resilient to failures.
 
-## Requirements
-
-### App Servers
+## Overview
 
-You need five servers dedicated to SonarQube. Servers can be VMs, it's not necessary to have physical machines.
+The only supported configuration for the Data Center Edition comprises 5 application servers, a load balancer and a database server:
 
-Servers must be co-located (geographical redundancy is not supported).
+- 2 application nodes responsible for handling web requests from users (WebServer process) and handling analysis reports (ComputeEngine process)
+- 3 search nodes that host Elasticsearch process that will store indices of data. For performance reasons, SSD are significantly better than HDD for these nodes
+- PostgreSQL, Oracle or Microsoft SQL Server database server. This software must be supplied by the installing organization
+- A reverse proxy / load balancer to load balance traffic between the two application nodes. This hardware or software component must be supplied by the installing organization
 
-You can find the operating system requirements for servers in the [Requirements](/requirements/requirements/) page.
+With this configuration, one application node and one search node can be lost without impacting users.  Here is a diagram of the supported topology:
 
+![DCE Cluster Machines Topology.](/images/cluster-dce.png)
 
-### Database Server
+## Requirements
 
-The Data Center Edition supports PostgreSQL, Oracle, and Microsoft SQL Server. If your data is currently stored in MySQL you can use the [SonarQube DB Copy Tool](/instance-administration/db-copy/) to move it.
+### Network
 
-### Load Balancer
-In addition to the five SonarQube servers, you must configure a reverse proxy / load balancer to load balance traffic between the two application nodes. The precise configuration of the reverse proxy / load balancer will vary by vendor, but the SonarQube Data Center Edition requirements are very simple:
+All servers, including database server, must be co-located (geographical redundancy is not supported) and have  static IP addressess (reference via hostname is not supported).  Network traffic should not be restricted between application and search nodes.
 
-- Share requests (load) between the two application nodes configured in the SonarQube cluster
-- If you are using HTTPS, ensure you are meeting the requirements set out in Securing SonarQube Behind a Proxy
-- **Note**: there is no requirement for the load balancer to preserve sessions; this is handled by the in-built JWT mechanism
+### Servers
 
-### License
-You need a dedicated license to activate the DC Edition. If you don't have it yet, please contact the SonarSource Sales Team.
+Five servers are needed to form the SonarQube application cluster. Servers can be VMs; it is not necessary to use physical machines.
 
-### Support
-Don't start this journey alone; as a Data Center Edition customer SonarSource will assist with the setup and configuration of your cluster. Get in touch with [SonarSource Support](https://support.sonarsource.com/) for help.
+The operating system requirements for servers are available on the [Requirements](/requirements/requirements/) page.  All application nodes should be identical in terms of hardware and software. Similarly, all search nodes should be identical to each other. But application and search nodes can differ. Generally, search nodes are configured with more CPU and RAM than application nodes.
 
-## Cluster Topology
-There are two types of nodes:
+Here are the types of machines we use to perform our validation with a 200M issues database. This could be used as a minimum recommendation to build your cluster.
 
-- an **application** node responsible for handling web requests from users (**WebServer** process) and handling analysis reports (**ComputeEngine** process)
-- a **search** node that is an Elasticsearch process that will store indices of data
-
-In order to achieve high availability, the **only supported configuration** for the Data Center Edition comprises 5 servers:
-
-- 2 **application** nodes containing both WebServer and ComputeEngine
-- 3 **search** nodes that host Elasticsearch. For performance reasons, SSD are significantly better than HDD for these nodes
+- App Node made of [Amazon EC2 m4.xlarge](https://aws.amazon.com/ec2/instance-types/): 4 vCPUs, 16GB RAM
+- Search Node made of [Amazon EC2 m4.2xlarge](https://aws.amazon.com/ec2/instance-types/): 8 vCPUs, 32GB RAM - 16GB allocated to Elasticsearch. SSDs perform significantly better than HDDs for these nodes
 
-_With this configuration, a node can be lost without impacting the service. More precisely, one application node and one search node can be lost without impacting users._
+### Database Server
 
-Here is a schema for the supported topology:
+Supported database systems are available on the [Requirements](/requirements/requirements/) page.
 
-![DCE Cluster Machines Topology.](/images/cluster-dce.png)
+### Load Balancer
 
-### Machines
+SonarSource does not provide specific recommendations for reverse proxy / load balancer or solution-specific configuration.  The general requirements to use with SonarQube Data Center Edition are:
 
-Here are the type of machines we used to perform our validation with a 200M Issues database. This could be used as a minimum recommendation to build your cluster.
+- Ability to balance HTTP requests (load) between the two application nodes configured in the SonarQube cluster
+- If terminating HTTPS, meets the requirements set out in [Securing SonarQube Behind a Proxy](/setup/operate-server/)
+- No requirement to preserve or sticky sessions; this is handled by the built-in JWT mechanism
 
-- Search Node made of [Amazon EC2 m4.2xlarge](https://aws.amazon.com/ec2/instance-types/): 8 vCPUs, 32GB RAM - 16GB allocated to Elasticsearch
-- App Node made of [Amazon EC2 m4.xlarge](https://aws.amazon.com/ec2/instance-types/): 4 vCPUs, 16GB RAM
+### License
 
-## Installation Details
+A dedicated license to activate the Data Center Edition. If you don't have it yet, please contact the SonarSource Sales Team.
 
-**Prepare your personalized SonarQube package:**
+### Support
 
-1. Install the SonarQube Data Center Edition, following the usual [Installing the Server](/setup/install-server/) documentation
-2. Install all the other plugins you may want, confirm the connectivity with the DB is working well. If you do this step manually be sure to check compatibility with your SonarQube version using the [Plugin Version Matrix](https://docs.sonarqube.org/display/PLUG/Plugin+Version+Matrix)
-3. Zip the directory $SONARQUBE_HOME
-4. You now have your own personalized SonarQube Data Center Edition package
+Don't start this journey alone!  As a Data Center Edition subscriber, SonarSource will assist with the setup and configuration of your cluster. Get in touch with [SonarSource Support](https://support.sonarsource.com) for help.
 
-**Deploy your SonarQube package on the 4 other nodes:**
+## Configuration
 
-It is expected that all **application** nodes are identical in term of hardware and software (same JVM build). Similarly, all **search** nodes should be identical to each other. But **application** and **search** nodes can differ. Generally, **search** nodes are configured with more CPU and RAM than **application** nodes.
+Additional parameters are required to activate clustering capabilities and specialize each node. These parameters are in addition to standard configuration properties used in a single node configuration.
 
-1. Unzip your personalized SonarQube package from the previous step on the 4 others nodes
-2. Congratulations, you now have 2 applications nodes and 3 search nodes completely identical in term of SonarQube softwares
+The **sonar.properties** file on each node will be edited to configure the node's specialization. A list of all cluster-specific configuration parameters is available in the [Operate the Cluster](/setup/operate-cluster/) documentation.
 
+Prior to configuration, you will need to generate a value for the `sonar.auth.jwtBase64Hs256Secret` property for the application nodes.  The value is a HS256 key encoded with base64 and will be the same for both nodes.  The following is an example on how to generate this value on a Unix system:
 
-## Configuration
+```
+echo -n "your_secret" | openssl dgst -sha256 -hmac "your_key" -binary | base64
+```
 
-Now you have 5 machines with the same SonarQube software it's time to start configuring them to specialize them. Some will become **application** nodes, some **search** nodes.
+### Sample Configuration
 
-The idea is as follows: you need to edit the sonar.properties file on each node to configure the node's specialization. In the following example we will assume:
+The following example represents the minimal parameters required to configure a SonarQube cluster.  The example assumes:
 
 - The VMs (server1, server2) having IP addresses ip1 and ip2 are going to be application nodes
 - The VMs having IP addresses ip3, ip4 and ip5 (server3, server4 and server5) are going to be search nodes
 
-The default configuration to be applied for each node is the following:
+The configuration to be added to sonar.properties for each node is the following:
 
 **server1**
 ```
+...
 sonar.cluster.enabled=true
 sonar.cluster.hosts=ip1,ip2,ip3,ip4,ip5
 sonar.cluster.search.hosts=ip3,ip4,ip5
 sonar.cluster.node.type=application
-sonar.auth.jwtBase64Hs256Secret=Vf4TRrfS6tvsFIHsQlgfhDUkiw3r8=
+sonar.auth.jwtBase64Hs256Secret=YOURGENERATEDSECRET
+...
 ```
 
 **server2**
 ```
+...
 sonar.cluster.enabled=true
 sonar.cluster.hosts=ip1,ip2,ip3,ip4,ip5
 sonar.cluster.search.hosts=ip3,ip4,ip5
 sonar.cluster.node.type=application
-sonar.auth.jwtBase64Hs256Secret=Vf4TRrfS6tvsFIHsQlgfhDUkiw3r8=
+sonar.auth.jwtBase64Hs256Secret=YOURGENERATEDSECRET
+...
 ```
 
 **server3**
 ```
+...
 sonar.cluster.enabled=true
 sonar.cluster.hosts=ip1,ip2,ip3,ip4,ip5
 sonar.cluster.search.hosts=ip3,ip4,ip5
 sonar.cluster.node.type=search
 sonar.search.host=ip3
+...
 ```
 
 **server4**
 ```
+...
 sonar.cluster.enabled=true
 sonar.cluster.hosts=ip1,ip2,ip3,ip4,ip5
 sonar.cluster.search.hosts=ip3,ip4,ip5
 sonar.cluster.node.type=search
 sonar.search.host=ip4
+...
 ```
 
 **server5**
 ```
+...
 sonar.cluster.enabled=true
 sonar.cluster.hosts=ip1,ip2,ip3,ip4,ip5
 sonar.cluster.search.hosts=ip3,ip4,ip5
 sonar.cluster.node.type=search
 sonar.search.host=ip5
+...
 ```
 
-The full set of cluster parameters is listed [here](/setup/operate-cluster/).
+## Sample Installation Process
+
+The following is an example of the SonarQube cluster installation process. You need to tailor these steps to the specifics of the target installation environment and the operational requirements of the hosting organization.
+
+**Prepare the cluster environment:**
+
+1. Prepare the cluster environment by setting up the network, provisioning nodes and load balancer. 
+2. Follow the [Installing the Server](/setup/install-server/) documentation to configure the database server
+
+**Prepare a personalized SonarQube package:**
+
+1. On a single application node of the cluster, download and install SonarQube Data Center Edition, following the usual [Installing the Server](/setup/install-server/) documentation.
+2. Add cluster-related parameters to `$SONARQUBE_HOME/conf/sonar.properties`
+3. As the Marketplace is not available in SonarQube Data Center Edition, this is a good opportunity to install additional plugins. Download and place a copy of each plugin JAR in `$SONARQUBE_HOME/extensions/plugins`.  Be sure to check compatibility with your SonarQube version using the [Plugin Version Matrix](https://docs.sonarqube.org/display/PLUG/Plugin+Version+Matrix)
+4. Zip the directory `$SONARQUBE_HOME`. This archive is a customized SonarQube Data Center Edition package that can be copied to other nodes
+
+**Test configuration on a single node:**
+
+1. On the application node where you created your Zip package, comment out all cluster-related parameters in `$SONARQUBE_HOME/conf/sonar.properties`
+2. Configure the load balancer to proxy with single application node
+3. Start server and test access through load balancer
+4. Request license from SonarSource Sales Team
+5. After applying license, you will have a full-featured SonarQube system operating on a single node.
+
+**Deploy SonarQube package on other nodes:**
+
+1. Unzip SonarQube package on the other four nodes
+2. Configure node-specific parameters on all five nodes in `$SONARQUBE_HOME/conf/sonar.properties` and ensure application node-specific and search node-specific parameters are properly set
+3. Start all search nodes
+4. After all search nodes are running, start all application nodes
+5. Configure the load balancer to proxy with both application nodes
 
-Once this configuration is done, take a break and a coffee, then you can [Operate your Cluster](/setup/operate-cluster/).
+Congratulations, you have a fully-functional SonarQube cluster.  Once these steps are complete, take a break and a coffee, then you can [Operate your Cluster](/setup/operate-cluster/).
 
 <!-- /sonarqube -->