diff options
| -rw-r--r-- | server/sonar-docs/src/images/jenkins-maven-setup.png | bin | 161618 -> 0 bytes | |||
| -rw-r--r-- | server/sonar-docs/src/pages/requirements/requirements.md | 12 | ||||
| -rw-r--r-- | server/sonar-docs/src/pages/setup/analysis-with-java-11.md | 119 | ||||
| -rw-r--r-- | server/sonar-docs/src/pages/setup/scanner-environment.md | 198 | ||||
| -rw-r--r-- | server/sonar-docs/src/pages/setup/upgrade-notes.md | 8 | ||||
| -rw-r--r-- | server/sonar-docs/static/SonarQubeNavigationTree.json | 2 | ||||
| -rw-r--r-- | server/sonar-docs/static/StaticNavigationTree.json | 2 |
7 files changed, 211 insertions, 130 deletions
diff --git a/server/sonar-docs/src/images/jenkins-maven-setup.png b/server/sonar-docs/src/images/jenkins-maven-setup.png Binary files differdeleted file mode 100644 index 80a88d42350..00000000000 --- a/server/sonar-docs/src/images/jenkins-maven-setup.png +++ /dev/null diff --git a/server/sonar-docs/src/pages/requirements/requirements.md b/server/sonar-docs/src/pages/requirements/requirements.md index 5f32b6ca5d2..f43b1ae8559 100644 --- a/server/sonar-docs/src/pages/requirements/requirements.md +++ b/server/sonar-docs/src/pages/requirements/requirements.md @@ -3,7 +3,7 @@ title: Prerequisites and Overview url: /requirements/requirements/ --- ## Prerequisite -You must be able to install Java (Oracle JRE 11 or OpenJDK 11) on the machine where you plan to run SonarQube. +You must be able to install Java (Oracle JRE or OpenJDK) on the machine where you plan to run SonarQube. ## Hardware Requirements 1. A small-scale (individual or small team) instance of the SonarQube server requires at least 2GB of RAM to run efficiently and 1GB of free RAM for the OS. If you are installing an instance for a large teams or Enterprise, please consider the additional recommendations below. @@ -20,17 +20,19 @@ For additional requirements and recommendations relating to database and Elastic ## Supported Platforms ### Java -The SonarQube scanners and the SonarQube server require Java version 11. Versions beyond Java 11 are not officially supported. +The SonarQube server require Java version 11 and the SonarQube scanners require Java version 11 or 17. SonarQube is able to analyze any kind of Java source files regardless of the version of Java they comply to. We recommend using the Critical Patch Update (CPU) releases. | Java | Server | Scanners | -| -------------- | ------------------------- | ------------------------- | -| Oracle JRE |  11 |  11 | +| -------------- |---------------------------|---------------------------| +| Oracle JRE |  17 |  17 | +| |  11 |  11 | | |  8 |  8 | -| OpenJDK |  11 |  11 | +| OpenJDK |  17 |  17 | +| |  11 |  11 | | |  8 |  8 | | Database | | diff --git a/server/sonar-docs/src/pages/setup/analysis-with-java-11.md b/server/sonar-docs/src/pages/setup/analysis-with-java-11.md deleted file mode 100644 index 16b76b49588..00000000000 --- a/server/sonar-docs/src/pages/setup/analysis-with-java-11.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Moving Analysis to Java 11 -url: /analysis/analysis-with-java-11/ ---- - -Java 11 is required for all scanners. If you're using a previous version of the Java, see the section below that aligns with your build for information on moving your analysis to Java 11. - -## Maven or Gradle - -We suggest basing your whole build on Java 11. If that's not compatible, you can have a dedicated script for the analysis that overrides the `JAVA_HOME` environment variable just before running it. See the following examples: - -### Maven - -``` -mvn verify ... -export JAVA_HOME=/path/to/java11 -mvn sonar:sonar ... -``` - -### Gradle - -``` -gradle build ... -export JAVA_HOME=/path/to/java11 -gradle sonarqube ... -``` - -## Azure DevOps - -If you are running your build with a Microsoft-hosted agent, this is already automatically done, and you're all set. - -If you're using a self-hosted agent, you can either modify your build pipeline to ensure that it runs with Java 11 by default or override the `JAVA_HOME` environment variable just before running the analysis. - -### Xamarin -In the specific case of Xamarin only allowing Java 8, you will need to specify a Java 8 path while invoking MSBuild, allowing the JAVA_HOME environment variable for the scanner only. - -``` -$env:XAMARIN_JAVA_HOME=/path/to/java8 -msbuild.exe /p:JavaSdkDirectory=$env:XAMARIN_JAVA_HOME -``` - -## Dockerfile - -You can use several base images to run your build with Java 11. Here are some examples: - -- openjdk:11-jre-slim -- debian:buster and above -- gradle:jre11-slim - -If your build is not compatible with Java 11, you can override `JAVA_HOME` environment variable before running scanners. - -## Jenkins - -You can easily define a new JDK version by navigating to **Manage Jenkins > Global Tool Configuration** if you have the [JDK Tool Plugin](https://plugins.jenkins.io/jdk-tool/) installed. - -### Declarative Pipelines - -If you are using a declarative pipeline with different stages you can add a 'tools' section to the stage in which the code scan occurs. This makes the scanner use the specificed JDK version. - -``` -stage('SonarQube analysis') { - tools { - jdk "jdk11" // the name you have given the JDK installation in Global Tool Configuration - } - environment { - scannerHome = tool 'SonarQube Scanner' // the name you have given the Sonar Scanner (in Global Tool Configuration) - } - steps { - withSonarQubeEnv(installationName: 'SonarQube') { - sh "${scannerHome}/bin/sonar-scanner -X" - } - } -} -``` - -If you are analyzing a Java 8 project you probably want to continue using Java 8 to build your project. The following example allows you to continue building in Java 8 but will use Java 11 to scan the code: - -``` -stage('Build') { - tools { - jdk "jdk8" // the name you have given the JDK installation using the JDK manager (Global Tool Configuration) - } - steps { - sh 'mvn compile' - } -} -stage('SonarQube analysis') { - tools { - jdk "jdk11" // the name you have given the JDK installation using the JDK manager (Global Tool Configuration) - } - environment { - scannerHome = tool 'SonarQube Scanner' // the name you have given the Sonar Scanner (Global Tool Configuration) - } - steps { - withSonarQubeEnv(installationName: 'SonarQube') { - sh 'mvn sonar:sonar' - } - } -} -``` - -The previous example is for Maven, but you can easily modify it for Gradle. - -### Classical Pipelines - -#### **Set Job JDK version** -You can set the JDK version that a job should use in the **General** section of your configuration. This option is only visible if you have configured multiple JDK versions under **Manage Jenkins > Global Tool Configuration**. - -#### **Set Execute SonarQube Scanner JDK version** -If you're using the **Execute SonarQube Scanner** step in your configuration, you can set the JDK for this step in the configuration dialog. This allows you to use JDK 11 for the code scanning performed by SonarQube and the globally configured JDK for all other steps in the job. - -#### **Java 8 projects** -Jenkins doesn't let you switch JDKs when using a 'Freestyle project' or 'Maven project' configuration, so when you want to build your project using Java 8 you have to manually set the `JAVA_HOME` variable to Java 11 when executing the scanner. - -You can do this with the [Tool Environment Plugin](https://plugins.jenkins.io/toolenv/). When this plugin is installed, you can expose the location of the JDK you added under **Manage Jenkins > Global Tool Configuration**. - -The location of the JDK can then be used to set the `JAVA_HOME` environment variable. The build and post steps sections can be configured as follows: - - diff --git a/server/sonar-docs/src/pages/setup/scanner-environment.md b/server/sonar-docs/src/pages/setup/scanner-environment.md new file mode 100644 index 00000000000..c7718955cb9 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/scanner-environment.md @@ -0,0 +1,198 @@ +--- +title: Scanner Environment +url: /analysis/scanner-environment/ +--- + +A Java runtime environment is always required to run the scanner that performs (CI-based) analysis. +This applies to all scanner variants (CLI, CI-specific, etc.) + +Additionally, in order to analyze JavaScript, TypeScript or CSS, the scanner also requires a Node.js runtime. + +The required versions for these runtimes change with successive versions of the scanner. +The current requirements and recommendations are: + +* You must use either **Java 11 or 17**. +* You should use at least **Node.js 14**, though we recommend that you use the **latest Node.js LTS**, which is currently **Node.js 16**. + +## Scanner vs project + +The requirements above refer only to the versions of Java and Node.js *used by the scanner* itself to run. +It does not restrict the versions of Java, JavaScript, TypeScript or CSS that can be analyzed by the scanner. + + +## Java configuration + +### GitHub Actions + +The SonarQube GitHub Action can be configured for different target build technologies (.NET, Gradle, Maven, etc). + + +### Maven / Gradle + +If your whole Maven or Gradle build doesn't run on Java 11 or 17, we suggest first to try to base the whole build on one of those two versions of Java. +If it's not compatible, then you can override the JAVA_HOME environment variable just before the analysis step, as shown here: + +``` +# Maven build +mvn verify ... +export JAVA_HOME=/path/to/java-11-or-17 +mvn sonar:sonar ... +``` + +``` +# Gradle build +gradle build ... +export JAVA_HOME=/path/to/java-11-or-17 +gradle sonarqube ... +``` + +### Azure DevOps + +All VM images available in Azure Pipelines for Microsoft-hosted agents already contain Java 11. +There is no further action required. +For self-hosted agents you must ensure that you are using Java 11 or 17. +You can either modify your build pipeline to ensure that it runs with Java 11 or 17 by default, or override the JAVA_HOME environment variable just before running the analysis. + + +#### Xamarin + +For the specific case of Xamarin, which only allows Java 8, you will need to specify a Java 8 path separately when invoking MSBuild (using, for example, XAMARIN_JAVA_HOME), and then leave the JAVA_HOME environment variable for the scanner only. + +``` +$env:JAVA_HOME=/path/to/java-11-or-17 +$env:XAMARIN_JAVA_HOME=/path/to/java-8 +msbuild.exe /p:JavaSdkDirectory=$env:XAMARIN_JAVA_HOME +``` + + +### Dockerfile + +Multiple base images can be used to run your build with Java 11 or 17, here are some examples: + +* `openjdk:11-jre-slim` +* `debian:buster and above` +* `gradle:jre11-slim` + +If your build is not compatible with Java 11 or 17, then you can override the `JAVA_HOME` environment variable to point to Java 11 or 17 immediately before running the analysis. + + +### Jenkins + +You can define a new JDK in **Manage Jenkins > Global Tool Configuration**, if you have the JDK Tool Plugin installed. + + +#### Declarative Pipelines + +If you are using a declarative pipeline with different stages, you can add a 'tools' section to the stage in which the code scan occurs. +This will make the scanner use the JDK version that is specified. + +``` +stage('SonarQube analysis') { + tools { + jdk "jdk11" // the name you have given the JDK installation in Global Tool Configuration + } + environment { + scannerHome = tool 'SonarQube Scanner' // the name you have given the Sonar Scanner (in Global Tool Configuration) + } + steps { + withSonarQubeEnv(installationName: 'SonarQube') { + sh "${scannerHome}/bin/sonar-scanner -X" + } + } +} +``` + +If you are analyzing a Java 8 project, you probably want to continue using Java 8 to build your project. +The following example allows you to continue building in Java 8, but will use Java 11 to scan the code: + +``` +stage('Build') { + tools { + jdk "jdk8" // the name you have given the JDK installation using the JDK manager (Global Tool Configuration) + } + steps { + sh 'mvn compile' + } +} +stage('SonarQube analysis') { + tools { + jdk "jdk11" // the name you have given the JDK installation using the JDK manager (Global Tool Configuration) + } + environment { + scannerHome = tool 'SonarQube Scanner' // the name you have given the Sonar Scanner (Global Tool Configuration) + } + steps { + withSonarQubeEnv(installationName: 'SonarQube') { + sh 'mvn sonar:sonar' + } + } +} +``` + +This example is for Maven but it can be easily modified to use Gradle. + +#### Classical pipelines + +**Set Job JDK version** + +You can easily set the JDK version to be used by a job in the **General** section of your configuration. +This option is only visible if you have configured multiple JDK versions under **Manage Jenkins > Global Tool Configuration**. + +**Set 'Execute SonarQube Scanner' JDK version** + +If you are using the **Execute SonarQube Scanner** step in your configuration, you can set the JDK for this step in the configuration dialog. +By using this approach, you can use JDK 11 or 17 only for the code scanning performed by SonarQube. +All the other steps in the job will use the globally configured JDK. + +**Java 8 projects** + +Jenkins does not offer functionality to switch JDKs when using a **Freestyle project** or **Maven project** configuration. +To build your project using Java 8, you have to manually set the `JAVA_HOME` variable to Java 11 or 17 when running the analysis. + +To do this use the **Tool Environment Plugin**. This plugin lets expose the location of the JDK you added under **Manage Jenkins > Global Tool Configuration**. +The location of the JDK can then be used to set the `JAVA_HOME` variable in a post step command, like this: + +``` +export JAVA_HOME=$OPENJDK_11_HOME/Contents/Home +mvn $SONAR_MAVEN_GOAL +``` + +## Node.js configuration + +### GitHub Actions + +The SonarQube GitHub Action already uses Node.js 14+. If you are using the official SonarQube Action, there is nothing further to do. If you are using your own GitHub Action and invoke the SonarScanner manually within that Action, then you should ensure that you are also using at least Node.js 14. See **Other cases** below. + + +### Bitbucket Pipelines + +The `sonarqube-scan` Bitbucket Pipe uses Node.js 14+. We recommend using the latest version of the pipe declaration in your `bitbucket-pipelines.yml`. For example: + +`- pipe: sonarsource/sonarqube-scan:1.1.0` + + +### Azure Pipelines + +All VM images available in Azure Pipelines for Microsoft-hosted agents already contain Node.js 14+. There is no further action required. For self-hosted agents you must ensure that you are using Node.js 14+. + + +### GitLab CI/CD + +The recommended setup for your `.gitlab-ci.yml` specifies `sonar-scanner-cli:latest` which already uses Node.js 14+. If you are using the recommended setup there is nothing further to do. + + +### Jenkins + +You should ensure that the Node.js version used by your Jenkins jobs is at least version 14. If you want to manage multiple versions of Node.js in Jenkins, the NodeJS Jenkins plugin may be useful. + + +### Other cases + +If your build set up falls into one of the following categories, then you will need to ensure that the build environment within which the SonarScanner runs has Node.js 14+ installed: + +* Manual invocation of the SonarScanner from the command line. +* Custom local build script invoking the SonarScanner. +* Non-standard use of a CI listed above. For example, using GitHub Actions but not using the provided SonarQube GitHub Action and instead using some other custom Action. +* Use of a CI which is not listed above. + +In general, if you are running the SonarScanner command line tool as an executable, then Node.js 14+ needs to be installed on the machine where it is run. Alternatively, if you are using the SonarScanner Docker image, then you just have to ensure that you are using at least version 4.6 of the image, as it already bundles the correct version of Node.js. diff --git a/server/sonar-docs/src/pages/setup/upgrade-notes.md b/server/sonar-docs/src/pages/setup/upgrade-notes.md index 96544b1e636..60763713e2f 100644 --- a/server/sonar-docs/src/pages/setup/upgrade-notes.md +++ b/server/sonar-docs/src/pages/setup/upgrade-notes.md @@ -24,13 +24,13 @@ If you are using Microsoft SQL Server with Integrated Authentication, you will n **Bitbucket Cloud authentication now built-in** Support for Bitbucket Cloud authentication is now built-in. If you were using the Bitbucket Cloud authentication plugin before, you need to remove it from SonarQube before upgrading. -SonarQube uses the same settings as the plugin, so you do not need to update them. The Teams restriction has been replaced with the Workspaces restriction and is migrated accordingly. ([MMF-2512](https://jira.sonarsource.com/browse/MMF-2512)). +SonarQube uses the same settings as the plugin, so you do not need to update them. The Teams restriction has been replaced with the Workspaces restriction and is migrated accordingly. [Full release notes](https://jira.sonarsource.com/secure/ReleaseNote.jspa?projectId=10930&version=16959) ## Release 9.1 Upgrade Notes **Secured settings no longer available in web services and on the scanner side** -This change especially affects the analysis of SVN projects but also, possibly, the use of some 3rd-party plugins. Secured settings required to perform the analysis now need to be passed to the scanner as parameters. ([MMF-2407](https://jira.sonarsource.com/browse/MMF-2407)). +This change especially affects the analysis of SVN projects but also, possibly, the use of some 3rd-party plugins. Secured settings required to perform the analysis now need to be passed to the scanner as parameters. **Custom measures feature has been dropped** The custom measures feature, which was previously deprecated, has been removed. ([SONAR-10762](https://jira.sonarsource.com/browse/SONAR-10762)). @@ -42,7 +42,7 @@ The WebAPI endpoints and parameters deprecated during the 7.X release cycle have ## Release 9.0 Upgrade Notes **Scanners require Java 11** -Java 11 is required for SonarQube scanners. Use of Java 8 is no longer supported. See the documentation on [Moving Analysis to Java 11](/analysis/analysis-with-java-11/) for more information. ([MMF-2051](https://jira.sonarsource.com/browse/MMF-2051)). +Java 11 is required for SonarQube scanners. Use of Java 8 is no longer supported. See the documentation on [Scanner Environment](/analysis/scanner-environment/) for more information. **Support for Internet Explorer 11 dropped** Support for Internet Explorer 11 and other legacy browsers has been dropped. ([SONAR-14387](https://jira.sonarsource.com/browse/SONAR-14387)). @@ -65,7 +65,7 @@ Upgrading directly from SonarQube _v7.9 LTS to v8.9 LTS_? Refer to the [LTS to L SonarQube 8.9 only supports GitHub Enterprise 2.21+ for pull request decoration (the previous minimum version was 2.15). **Plugins require risk consent** -When upgrading, if you're using plugins, a SonarQube administrator needs to acknowledge the risk involved with plugin installation when prompted in SonarQube. ([MMF-2301](https://jira.sonarsource.com/browse/MMF-2301)). +When upgrading, if you're using plugins, a SonarQube administrator needs to acknowledge the risk involved with plugin installation when prompted in SonarQube. **Database support updated** SonarQube 8.9 supports the following database versions: diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json index 24d15f448e0..21bacc6ee5a 100644 --- a/server/sonar-docs/static/SonarQubeNavigationTree.json +++ b/server/sonar-docs/static/SonarQubeNavigationTree.json @@ -72,7 +72,7 @@ }, "/analysis/scm-integration/", "/analysis/security_configuration/", - "/analysis/analysis-with-java-11/" + "/analysis/scanner-environment/" ] }, { diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json index 7eaf46b0e17..e2f09ea6c1c 100644 --- a/server/sonar-docs/static/StaticNavigationTree.json +++ b/server/sonar-docs/static/StaticNavigationTree.json @@ -97,7 +97,7 @@ }, "/analysis/scm-integration/", "/analysis/security_configuration/", - "/analysis/analysis-with-java-11/" + "/analysis/scanner-environment/" ] }, { |
