Use admonition for host IP alternative (#41)

Author: kangasta

docs/tutorials/jenkins/sonarqube-jenkins/Jenkinsfile

@@ -1,14 +1,19 @@
-def net = '' // Set the value to 'host' to use host networking.
+def attachJenkinsNetwork = true
+// If true, the pipeline will attach the SonarQube scanner to the same network
+// with Jenkins and SonarQube containers.
+
+def scannerArgs = ''
 
 pipeline {
   agent any
   stages {
     stage ('Prepare') {
       steps {
         script {
-          if (net == '') {
+          if (attachJenkinsNetwork == true) {
             // Get the name of the network that Jenkins container is using.
-            net = sh returnStdout: true, script: 'docker inspect $(hostname) -f \'{{ range $k, $v := .NetworkSettings.Networks }}{{ $k }}{{ end }}\''
+            def net = sh returnStdout: true, script: 'docker inspect $(hostname) -f \'{{ range $k, $v := .NetworkSettings.Networks }}{{ $k }}{{ end }}\''
+            scannerArgs = "--network ${net.trim()}"
           }
         }
       }
@@ -24,7 +29,7 @@ pipeline {
         docker {
           image 'sonarsource/sonar-scanner-cli'
           // In order to be able to use http://sonarqube:9000 we need to be in the same network as Jenkins and SonarQube are in.
-          args  "--net $net"
+          args scannerArgs
           // To quarantee that the workspace contains the sources pulled in previous stage, we need to use the pipeline level workspace.
           reuseNode true
         }

docs/tutorials/jenkins/sonarqube-jenkins/README.md

@@ -29,7 +29,7 @@ To get started with SonarQube, access the [Web UI](http://localhost:9000) and lo
 
 In order to test the SonarQube installation, run `sonar-scanner` in a code repository. This can be done, for example, by using the [sonarsource/sonar-scanner-cli](https://hub.docker.com/r/sonarsource/sonar-scanner-cli) Docker image:
 
-```bash
+```sh
 # This command should be run in the repository root directory
 docker run \
   --rm \
@@ -47,16 +47,20 @@ If this succeeds, you are ready to move this analysis into Jenkins.
 
 First, install SonarQube Scanner plugin to your Jenkins instance through [Manage Jenkins > Manage plugins](http://localhost:8080/pluginManager/available) menu. Configure SonarQube instance to SonarQube servers section of the [Manage Jenkins > Configure System](http://localhost:8080/configure) menu: Use `http://sonarqube:9000` as the server URL and create a secret text credential for the access token you stored earlier.
 
+??? example "Alternatives for using `sonarqube` hostname"
+
+    The `sonarqube` domain name is by default only available for containers attached to the same network. Thus the the connection from Jenkins container works with the `sonarqube` hostname, but opening these links from the browser will fail.
+
+    To define an URL that works in both Jenkins and browser, we could use hosts IP address instead of the `sonarqube` hostname. The URL would then be in `http://${HOST_IP}:9000` format. On linux systems, you can find your local IP with `hostname -I` command. On Windows systems, you can find your local by looking for IP address from the output of `ipconfig` command. Configure the with hosts IP to the [Manage Jenkins > Configure System](http://localhost:8080/configure) menu.
+
+    When using URL with hosts IP, you can omit the network argument from the docker agent block and the links from the job view should work as is. In the example Jenkinsfile this can be done by setting `attachJenkinsNetwork` to false.
+
 After the SonarQube server is configured to Jenkins, sonar-scanner can be executed in a stage that uses the same [sonarsource/sonar-scanner-cli](https://hub.docker.com/r/sonarsource/sonar-scanner-cli) Docker image that was used in the previous step as well. This can be done with a stage level Docker agent:
 
 ```Groovy title="Jenkinsfile"
 ---8<-- "docs/tutorials/jenkins/sonarqube-jenkins/Jenkinsfile"
 ```
 
-See [Jenkinsfile](./Jenkinsfile) for a example of a complete pipeline. If you try to execute this example pipeline replace `${GIT_URL}` with the URL to your git repository of choice.
-
 After the pipeline with sonar-scanner run has been executed, the job view in Jenkins should include the SonarQube quality gate status of the linked Sonar Project. Note that in this demo setup these links will not work as the Jenkins uses the `http://sonarqube:9000` URL for the SonarQube server which is likely not accessible from your browser. To see the projects in SonarQube, replace `http://sonarqube:9000` with `http://localhost:9000` in the URL.
 
-Alternative for using `http://sonarqube:9000` or `http://localhost:9000` as the SonarQube URL would be to use your host machines local IP: `http://${HOST_IP}:9000`. On linux systems, you can find your local IP with `hostname -I` command. On Windows systems, you can find your local by looking for IP address from the output of `ipconfig` command. You only need to configure this to the [Manage Jenkins > Configure System](http://localhost:8080/configure) menu. When using local host IP, you can omit the network argument from docker agent block and the links from the job view should work as is.
-
 Note that this setup should only be used for development. For anything production like, configure SonarQube to use database such as postgres, do not use root or admin credentials, and setup the Jenkins and SonarQube to a suitable private network. See also Jenkins and SonarQube documentation for production usage instructions.