SONAR-12445 improve doc for folders binding, first install, upgrade

sonarqube/content.md

@@ -6,11 +6,26 @@
 
 # How to use this image
 
-This Docker image contains the Community Edition of SonarQube.
+Here you'll find the Docker image for the Community Edition of SonarQube and beta versions of the Docker images for Developer Edition and Enterprise Edition.
 
-## Run SonarQube
+## Docker Host Requirements
 
-The server is started this way:
+Because SonarQube uses an embedded Elasticsearch, make sure that your Docker host configuration complies with the [Elasticsearch production mode requirements](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode) and [File Descriptors configuration](https://www.elastic.co/guide/en/elasticsearch/reference/current/file-descriptors.html).
+
+For example, on Linux, you can set the recommended values for the current session by running the following commands as root on the host:
+
+```console
+sysctl -w vm.max_map_count=262144
+sysctl -w fs.file-max=65536
+ulimit -n 65536
+ulimit -u 4096
+```
+
+## Get Started in Two Minutes Guide
+
+/!\ This section shows you how to quickly run a demo instance. When you are ready to move to a more sustainable setup, take some time to read the **Configuration** section below.
+
+Start the server by running:
 
 ```console
 $ docker run -d --name sonarqube -p 9000:9000 %%IMAGE%%
@@ -30,68 +45,144 @@ $ mvn sonar:sonar -Dsonar.host.url=http://$(boot2docker ip):9000
 
 To analyze other kinds of projects and for more details see [Analyzing Source Code documentation](https://redirect.sonarsource.com/doc/analyzing-source-code.html).
 
-## Requirements
+## Configuration
 
-Because SonarQube uses an embedded Elasticsearch, make sure that the Docker host configuration complies with the [Elasticsearch production mode requirements](https://www.elastic.co/guide/en/elasticsearch/reference/current/docker.html#docker-cli-run-prod-mode) and [File Descriptors configuration](https://www.elastic.co/guide/en/elasticsearch/reference/current/file-descriptors.html).
+### Database
 
-For example, on Linux, you can set the recommended values for the current session by running the following commands as root on the host:
+By default, the image will use an embedded H2 database that is not suited for production.
 
-```console
-sysctl -w vm.max_map_count=262144
-sysctl -w fs.file-max=65536
-ulimit -n 65536
-ulimit -u 4096
-```
+> Warning: Only a single instance of SonarQube can connect to a database schema. If you're using a Docker Swarm or Kubernetes, make sure that multiple SonarQube instances are never running on the same database schema simultaneously. This will cause SonarQube to behave unpredictably and data will be corrupted. There is no safeguard until [SONAR-10362](https://jira.sonarsource.com/browse/SONAR-10362).
 
-## Advanced configuration
+Setup a database by following the "Installing the Database" section of https://docs.sonarqube.org/latest/setup/install-server/.
 
-### Database configuration
+### Use bind-mounted folders
 
-By default, the image will use an embedded H2 database that is not suited for production.
+The images contain the SonarQube installation at `/opt/sonarqube`. You need to use bind-mounted folders to override selected files or directories :
 
-> Warning: Only a single instance of SonarQube can connect to a database schema. If you're using a Docker Swarm or Kubernetes, make sure that multiple SonarQube instances are never running on the same database schema simultaneously. This will cause SonarQube to behave unpredictably and data will be corrupted. There is no safeguard until [SONAR-10362](https://jira.sonarsource.com/browse/SONAR-10362).
+-	`/opt/sonarqube/conf`: configuration files, such as `sonar.properties`
+-	`/opt/sonarqube/data`: data files, such as the embedded H2 database and Elasticsearch indexes
+-	`/opt/sonarqube/logs`: contains SonarQube logs about access, web process, CE process, Elasticsearch logs
+-	`/opt/sonarqube/extensions`: plugins, such as language analyzers
 
-### Option 1: Use parameters via Docker environment variables
+### First installation
 
-The production database is configured with the following SonarQube properties used as environment variables: `sonar.jdbc.username`, `sonar.jdbc.password` and `sonar.jdbc.url`.
+Follow these steps for your first installation:
 
-```console
-$ docker run -d --name sonarqube \
-    -p 9000:9000 \
-    -e sonar.jdbc.username=sonar \
-    -e sonar.jdbc.password=sonar \
-    -e sonar.jdbc.url=jdbc:postgresql://localhost/sonar \
-    sonarqube
-```
+1.	Create a `sonarqube_home` folder and create a environment variable `$SONARQUBE_HOME` pointing to it:
 
-Use of the environment variables `SONARQUBE_JDBC_USERNAME`, `SONARQUBE_JDBC_PASSWORD` and `SONARQUBE_JDBC_URL` is deprecated, and will stop working in future releases.
+	```console
+	$ mkdir /path/to/your/filesystem/sonarqube_home
+	$ export SONARQUBE_HOME=/path/to/your/filesystem/sonarqube_home
+	```
 
-More recipes can be found [here](https://github.com/SonarSource/docker-sonarqube/blob/master/recipes.md).
+2.	Initialize SONARQUBE_HOME folder tree with `--init`. This will initialize the default configuration, copy embedded plugins, and prepare the data folder:
+
+	```console
+	$ docker run --rm \
+	 -v $SONARQUBE_HOME/conf:/opt/sonarqube/conf \
+	 -v $SONARQUBE_HOME/extensions:/opt/sonarqube/extensions \
+	 -v $SONARQUBE_HOME/data:/opt/sonarqube/data \
+	 %%IMAGE%% --init
+	```
+
+3.	Configure sonar.properties to configure the database settings. Templates are available for every supported database. Just uncomment and configure the template you need and comment out the lines dedicated to H2:
+
+	```plain
+	#Example for PostgreSQL
+	sonar.jdbc.username=sonarqube sonar.jdbc.password=mypassword
+	sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube
+	```
+
+4.	Drivers for the supported databases (except Oracle) are already provided. Do not replace the provided drivers; they are the only ones supported. For Oracle, copy the JDBC driver into `$SONARQUBE_HOME/extensions/jdbc-driver/oracle`.
+
+5.	Run the image:
+
+	```console
+	$ docker run -d --name sonarqube \
+	    -p 9000:9000 \
+	    -v $SONARQUBE_HOME/conf:/opt/sonarqube/conf \
+	    -v $SONARQUBE_HOME/extensions:/opt/sonarqube/extensions \
+	    -v $SONARQUBE_HOME/logs:/opt/sonarqube/logs \
+	    -v $SONARQUBE_HOME/data:/opt/sonarqube/data \
+	    %%IMAGE%%
+	```
+
+## Upgrade SonarQube
+
+Follow these steps to upgrade SonarQube:
+
+1.	Create a new `sonarqube_home_new` folder and backup your old folder.
+
+2.	Update the environment variable `$SONARQUBE_HOME` pointing to it. Backup the old one:
+
+	```console
+	$ mkdir /path/to/your/filesystem/sonarqube_home_new
+	$ export SONARQUBE_HOME=/path/to/your/filesystem/sonarqube_home_new
+	```
+
+3.	Initialize the new `SONARQUBE_HOME` with `--init`:
 
-You can pass `sonar.` configuration properties as Docker environment variables, as demonstrated in the example above for database configuration.
+	```console
+	$ docker run --rm \
+	    -v $SONARQUBE_HOME/conf:/opt/sonarqube/conf \
+	    -v $SONARQUBE_HOME/extensions:/opt/sonarqube/extensions \
+	    -v $SONARQUBE_HOME/data:/opt/sonarqube/data \
+	    %%IMAGE%% --init  
+	```
 
-### Option 2: Use bind-mounted persistent volumes
+4.	Take a look at the [Upgrade Guide](https://docs.sonarqube.org/latest/setup/upgrading/) for information on:
 
-The images contain the SonarQube installation at `/opt/sonarqube`. You can use bind-mounted persistent volumes to override selected files or directories, for example:
+	-	Manually installing the non-default plugins
+	-	Updating the contents of sonar.properties and wrapper.conf
+	-	Copying the Oracle DB JDBC driver if needed  
+		  
 
--	`sonarqube_conf:/opt/sonarqube/conf`: configuration files, such as `sonar.properties`
--	`sonarqube_data:/opt/sonarqube/data`: data files, such as the embedded H2 database and Elasticsearch indexes
--	`sonarqube_logs:/opt/sonarqube/logs`
--	`sonarqube_extensions:/opt/sonarqube/extensions`: plugins, such as language analyzers
+5.	Stop and remove the sonarqube container (a restart is not enough as the environment variables are only evaluated during the first run, not during a restart):
 
-You could also use bind-mounted configurations specified on the command line, for example:
+	```console
+	$ docker stop %%IMAGE%%
+	$ docker rm %%IMAGE%%
+	```
+
+6.	Run docker:
+
+	```console
+	$ docker run -d --name sq -p 9000:9000 \
+	    -v $SONARQUBE_HOME/conf:/opt/sonarqube/conf \
+	    -v $SONARQUBE_HOME/extensions:/opt/sonarqube/extensions \
+	    -v $SONARQUBE_HOME/logs:/opt/sonarqube/logs \
+	    -v $SONARQUBE_HOME/data:/opt/sonarqube/data \
+	    %%IMAGE%%
+	```
+
+7.	Browse to `http://yourSonarQubeServerURL/setup` and follow the setup instructions.
+
+8.	Reanalyze your projects to get fresh data.
+
+## Advanced configuration
+
+#### Use parameters via Docker environment variables
+
+The database can be configured with the following SonarQube properties used as environment variables: `sonar.jdbc.username`, `sonar.jdbc.password` and `sonar.jdbc.url`.
 
 ```console
 $ docker run -d --name sonarqube \
     -p 9000:9000 \
-    -v /path/to/conf:/opt/sonarqube/conf \
-    -v /path/to/data:/opt/sonarqube/data \
-    -v /path/to/logs:/opt/sonarqube/logs \
-    -v /path/to/extensions:/opt/sonarqube/extensions \
-    sonarqube
+    -e sonar.jdbc.username=sonar \
+    -e sonar.jdbc.password=sonar \
+    -e sonar.jdbc.url=jdbc:postgresql://localhost/sonar \
+    -v $SONARQUBE_HOME/conf:/opt/sonarqube/conf \
+    -v $SONARQUBE_HOME/extensions:/opt/sonarqube/extensions \
+    -v $SONARQUBE_HOME/logs:/opt/sonarqube/logs \
+    -v $SONARQUBE_HOME/data:/opt/sonarqube/data \
+    %%IMAGE%%
 ```
 
-### Option 3: Customized image
+Use of the environment variables `SONARQUBE_JDBC_USERNAME`, `SONARQUBE_JDBC_PASSWORD`, and `SONARQUBE_JDBC_URL` is deprecated and will stop working in future releases.
+
+More recipes can be found [here](https://github.com/SonarSource/docker-sonarqube/blob/master/recipes.md).
+
+### Customized image
 
 In some environments, it may make more sense to prepare a custom image containing your configuration. A `Dockerfile` to achieve this may be as simple as: