diff options
| author | G. Ann Campbell <ann.campbell@sonarsource.com> | 2018-10-10 15:38:53 +0200 |
|---|---|---|
| committer | SonarTech <sonartech@sonarsource.com> | 2018-10-10 20:20:56 +0200 |
| commit | 2fac84bbe12515bb7d446a7cdc6be86fd3377b86 (patch) | |
| tree | 3669638c0af0b95904309b0c17ebec8b5e2a9e43 /server | |
| parent | 75ff5a8ed492a1d980b17ad7cc2b87ee2439649c (diff) | |
| download | sonarqube-2fac84bbe12515bb7d446a7cdc6be86fd3377b86.tar.gz sonarqube-2fac84bbe12515bb7d446a7cdc6be86fd3377b86.zip | |
Port remaining SONAR space docs
Diffstat (limited to 'server')
95 files changed, 3734 insertions, 142 deletions
diff --git a/server/sonar-docs/README.md b/server/sonar-docs/README.md index aca7bd3b15d..ec1c9164310 100644 --- a/server/sonar-docs/README.md +++ b/server/sonar-docs/README.md @@ -68,13 +68,14 @@ As documentation writers there are two ways it is possible for us to break the S * broken links Even without spinning up servers, you can double-check that your changes won't break the build. -**Test everything** + +**Test everything** You can run all the tests, and make sure that both your markup is well-formed and your links are correct by running the build script: ``` cd sonar-enterprise/ ./build.sh -x test -x obfuscate ``` -**Test links only** +**Test links only** If you only want to double-check your links changes, you can ``` cd sonar-enterprise/server/sonar-docs @@ -104,13 +105,13 @@ Ex.: ``` --- title: Demo page -url: /sonarcloud-pricing +url: /sonarcloud-pricing/ --- ``` ** Metadata conventions** * Metadata tags can appear in any order, but by convention, `title` should come first. -* The `url` tag is optional, but by convention, should be specified to both make the publish path explicit and avoid problems potentially caused by moving or renaming files. +* The `url` tag is required, and should start and end with '/' ### Includes @@ -221,7 +222,8 @@ baz Basic syntax: -```[[collapse]] +``` +[[collapse]] | ## Block title | Block content ``` diff --git a/server/sonar-docs/src/EmbedDocsSuggestions.json b/server/sonar-docs/src/EmbedDocsSuggestions.json index 614dea5734a..b161e8cfcf0 100644 --- a/server/sonar-docs/src/EmbedDocsSuggestions.json +++ b/server/sonar-docs/src/EmbedDocsSuggestions.json @@ -122,14 +122,14 @@ ], "projects_management": [ { - "link": "/documentation/analyze-a-project/", + "link": "/documentation/analysis/overview/", "text": "Analyze a Project", "scope": "sonarcloud" } ], "projects": [ { - "link": "/documentation/analyze-a-project/", + "link": "/documentation/analysis/overview/", "text": "Analyze a Project", "scope": "sonarcloud" } diff --git a/server/sonar-docs/src/images/architecture-integrate.png b/server/sonar-docs/src/images/architecture-integrate.png Binary files differnew file mode 100644 index 00000000000..7dc7960fd89 --- /dev/null +++ b/server/sonar-docs/src/images/architecture-integrate.png diff --git a/server/sonar-docs/src/images/architecture-scanning.png b/server/sonar-docs/src/images/architecture-scanning.png Binary files differnew file mode 100644 index 00000000000..cea3ebbfeeb --- /dev/null +++ b/server/sonar-docs/src/images/architecture-scanning.png diff --git a/server/sonar-docs/src/images/cluster-dce.png b/server/sonar-docs/src/images/cluster-dce.png Binary files differnew file mode 100644 index 00000000000..0c23a25f664 --- /dev/null +++ b/server/sonar-docs/src/images/cluster-dce.png diff --git a/server/sonar-docs/src/images/db-copy/copy-data.png b/server/sonar-docs/src/images/db-copy/copy-data.png Binary files differnew file mode 100644 index 00000000000..4ba4dad9b87 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/copy-data.png diff --git a/server/sonar-docs/src/images/db-copy/copy-errors-shown.png b/server/sonar-docs/src/images/db-copy/copy-errors-shown.png Binary files differnew file mode 100644 index 00000000000..397a02134da --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/copy-errors-shown.png diff --git a/server/sonar-docs/src/images/db-copy/missing-table-not-copied.png b/server/sonar-docs/src/images/db-copy/missing-table-not-copied.png Binary files differnew file mode 100644 index 00000000000..39aebfac4cb --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/missing-table-not-copied.png diff --git a/server/sonar-docs/src/images/db-copy/missing-table-not-purged.png b/server/sonar-docs/src/images/db-copy/missing-table-not-purged.png Binary files differnew file mode 100644 index 00000000000..4812bb920a9 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/missing-table-not-purged.png diff --git a/server/sonar-docs/src/images/db-copy/missing-table-warning.png b/server/sonar-docs/src/images/db-copy/missing-table-warning.png Binary files differnew file mode 100644 index 00000000000..7a5816fa9a5 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/missing-table-warning.png diff --git a/server/sonar-docs/src/images/db-copy/search-tables.png b/server/sonar-docs/src/images/db-copy/search-tables.png Binary files differnew file mode 100644 index 00000000000..ce1eed90d3c --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/search-tables.png diff --git a/server/sonar-docs/src/images/db-copy/summary-of-differences.png b/server/sonar-docs/src/images/db-copy/summary-of-differences.png Binary files differnew file mode 100644 index 00000000000..3d396fde944 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/summary-of-differences.png diff --git a/server/sonar-docs/src/images/db-copy/truncate-tables.png b/server/sonar-docs/src/images/db-copy/truncate-tables.png Binary files differnew file mode 100644 index 00000000000..4812bb920a9 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/truncate-tables.png diff --git a/server/sonar-docs/src/images/db-copy/verify-urls.png b/server/sonar-docs/src/images/db-copy/verify-urls.png Binary files differnew file mode 100644 index 00000000000..3a6b5a45417 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/verify-urls.png diff --git a/server/sonar-docs/src/images/db-copy/verify-versions.png b/server/sonar-docs/src/images/db-copy/verify-versions.png Binary files differnew file mode 100644 index 00000000000..dc30216d2b7 --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/verify-versions.png diff --git a/server/sonar-docs/src/images/db-copy/version0-ok.png b/server/sonar-docs/src/images/db-copy/version0-ok.png Binary files differnew file mode 100644 index 00000000000..e7d2436a87b --- /dev/null +++ b/server/sonar-docs/src/images/db-copy/version0-ok.png diff --git a/server/sonar-docs/src/images/encrypt-value.png b/server/sonar-docs/src/images/encrypt-value.png Binary files differnew file mode 100644 index 00000000000..c22aa1dc2d7 --- /dev/null +++ b/server/sonar-docs/src/images/encrypt-value.png diff --git a/server/sonar-docs/src/images/http-header-authentication.png b/server/sonar-docs/src/images/http-header-authentication.png Binary files differnew file mode 100644 index 00000000000..221ded008ca --- /dev/null +++ b/server/sonar-docs/src/images/http-header-authentication.png diff --git a/server/sonar-docs/src/images/rule-template-details.png b/server/sonar-docs/src/images/rule-template-details.png Binary files differnew file mode 100644 index 00000000000..65d78741261 --- /dev/null +++ b/server/sonar-docs/src/images/rule-template-details.png diff --git a/server/sonar-docs/src/images/rule-templates.png b/server/sonar-docs/src/images/rule-templates.png Binary files differnew file mode 100644 index 00000000000..f3e565d8218 --- /dev/null +++ b/server/sonar-docs/src/images/rule-templates.png diff --git a/server/sonar-docs/src/images/rules-custom.png b/server/sonar-docs/src/images/rules-custom.png Binary files differnew file mode 100644 index 00000000000..ba16cc2841b --- /dev/null +++ b/server/sonar-docs/src/images/rules-custom.png diff --git a/server/sonar-docs/src/images/visualizations.png b/server/sonar-docs/src/images/visualizations.png Binary files differnew file mode 100644 index 00000000000..b53b37e49fe --- /dev/null +++ b/server/sonar-docs/src/images/visualizations.png diff --git a/server/sonar-docs/src/layouts/components/Footer.js b/server/sonar-docs/src/layouts/components/Footer.js index 83e72f5c56f..9e879632bad 100644 --- a/server/sonar-docs/src/layouts/components/Footer.js +++ b/server/sonar-docs/src/layouts/components/Footer.js @@ -32,7 +32,7 @@ export default function Footer() { src="https://licensebuttons.net/l/by-nc/3.0/us/88x31.png" /> </a> - © 2008-2017, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space + © 2008-2018, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a{' '} <a href="https://creativecommons.org/licenses/by-nc/3.0/us/" diff --git a/server/sonar-docs/src/pages/analysis/analysis-parameters.md b/server/sonar-docs/src/pages/analysis/analysis-parameters.md new file mode 100644 index 00000000000..b2b73502646 --- /dev/null +++ b/server/sonar-docs/src/pages/analysis/analysis-parameters.md @@ -0,0 +1,104 @@ +--- +title: Analysis Parameters +url: /analysis/analysis-parameters/ +--- + +## Table of Contents + +Parameters to configure project analysis can be set in multiple places. Here is the hierarchy of parameters: + +* Global analysis parameters, defined in the UI, apply to all the projects (From the top bar, go to **[Administration > Configuration > General Settings](/#sonarqube-admin#/admin/settings)**) +* Project analysis parameters, defined in the UI, override global parameters (At a project level, go to Administration > General Settings) +* Project analysis parameters, defined in a project analysis configuration file or an analyzer configuration file, override the ones defined in the UI +* Analysis / Command line parameters, defined when launching an analysis, override project analysis parameters + +Note that only parameters set through the UI are stored in the database. +For example, if you override the sonar.exclusions parameter via command line for a specific project, it will not be stored in the database. Local analyses in Eclipse, for example, would still be executed with the exclusions defined in the UI and therefore stored in the DB. + +Note that the list of parameters below is not exhaustive. Most of the property keys shown in the interface, at both global and project levels, can also be set as analysis parameters. However, exclusions/inclusions are far easier to manage in the UI. + +## Mandatory Parameters + +### Server +Key | Description | Default +---|----|--- +`sonar.host.url`| the server URL | http://localhost:9000 + +### Project Configuration +Key | Description | Default +---|----|--- +`sonar.projectKey`|The project's unique key. Allowed characters are: letters, numbers, `-`, `_`, `.` and `:`, with at least one non-digit. | For Maven projects, this is automatically set to `<groupId>:<artifactId>` +`sonar.sources` | Comma-separated paths to directories containing source files. | Read from build system for Maven, Gradle, MSBuild projects + +## Optional Parameters + +### Project Identity +Key | Description | Default +---|----|--- +`sonar.projectName`|Name of the project that will be displayed on the web interface.|`<name>` for Maven projects, otherwise project key. If there is already a name in the DB, it won't be overwritten +`sonar.projectVersion` | The project version. | `<version>` for Maven projects, otherwise "not provided" + + +### Authentication +If the "Anyone" pseudo-group does not have permission to perform analyses, you'll need to supply the credentials of a user with Execute Analysis permission for the analysis to run under. + + +Key | Description | Default +---|----|--- +`sonar.login` | The login or authentication token of a {instance} user with Execute Analysis permission on the project. | +`sonar.password` | The password that goes with the `sonar.login` username. This should be left blank if an authentication token is being used. | + +### Web Services +Key | Description | Default +---|----|--- +`sonar.ws.timeout` | Maximum time to wait for the response of a Web Service call (in seconds). Modifying this value from the default is useful only when you're experiencing timeouts during analysis while waiting for the server to respond to Web Service calls. | 60 + +### Project Configuration +Key | Description | Default +---|----|--- +`sonar.projectDescription` | The project description. Not compatible with Maven. | `<description>` for Maven projects +`sonar.links.homepage` | Project home page. Not compatible with Maven. | `<url>` for Maven projects +`sonar.links.ci` | Continuous integration. Not compatible with Maven. | `<ciManagement><url>` for Maven projects +`sonar.links.issue` | Issue tracker. Not compatible with Maven. | `<issueManagement><url>` for Maven projects +`sonar.links.scm` | Project source repository. Not compatible with Maven. | `<scm><url>` for Maven projects +`sonar.links.scm_dev` | Developer connection. Not compatible with Maven. | `<scm><developerConnection>` for Maven projects +`sonar.tests` | Comma-separated paths to directories containing tests. Not compatible with Maven. | Default tests location for Java Maven projects. +`sonar.sourceEncoding` | Encoding of the source files. Ex: `UTF-8`, `MacRoman`, `Shift_JIS`. This property can be replaced by the standard property `project.build.sourceEncoding` in Maven projects. The list of available encodings depends on your JVM. | System encoding +`sonar.externalIssuesReportPaths` | Comma-delimited list of paths to Generic Issue reports. | +`sonar.projectDate` | Assign a date to the analysis. This parameter is only useful when you need to retroactively create the history of a not-analyzed-before project. The format is `yyyy-MM-dd`, for example: 2010-12-01. Since you cannot perform an analysis dated prior to the most recent one in the database, you must analyze recreate your project history in chronological order, oldest first.  Note: You may need to adjust your housekeeping settings if you wish to create a long-running history. | Current date +`sonar.projectBaseDir` | Use this property when you need analysis to take place in a directory other than the one from which it was launched. E.G. analysis begins from `jenkins/jobs/myjob/workspace` but the files to be analyzed are in `ftpdrop/cobol/project1`. The path may be relative or absolute. Specify not the the source directory, but some parent of the source directory. The value specified here becomes the new "analysis directory", and other paths are then specified as though the analysis were starting from the specified value of `sonar.projectBaseDir`. Note that the analysis process will need write permissions in this directory; it is where the `sonar.working.directory` will be created. | +`sonar.working.directory` | Set the working directory for an analysis triggered with the SonarScanner or the SonarScanner for Ant (versions greater than 2.0). This property is not compatible with the SonarScanner for MSBuild. Path must be relative, and unique for each project.  Beware: the specified folder is deleted before each analysis. | `.sonar` +`sonar.scm.provider` | This property can be used to explicitly tell {instance} which SCM plugin should be used to grab SCM data on the project (in case auto-detection does not work). The value of this property is always lowercase and depends on the plugin (ex. "tfvc" for the TFVC plugin). Check the documentation page of each plugin for more. | +`sonar.scm.forceReloadAll` | By default, blame information is only retrieved for changed files. Set this property to `true` to load blame information for all files. This can be useful is you feel that some SCM data is outdated but {instance} does not get the latest information from the SCM engine. | +`sonar.coverage.jacoco.xmlReportPaths` | Import JaCoCo code coverage reports provided as XML files. This property accepts multiple, comma-delimited entries. The JaCoCo XML report must be generated prior to analysis. | `target/site/jacoco/jacoco.xml` `build/reports/jacoco/test/jacocoTestReport.xml` | + + +### Duplications +Key | Description | Default +---|----|--- +`sonar.cpd.exclusions` | Comma-delimited list of file path patterns to be excluded from duplication detection | +`sonar.cpd.${language}.minimumtokens` | A piece of code is considered duplicated as soon as there are at least 100 duplicated tokens in a row (overide with `sonar.cpd.${language}.minimumTokens`) spread across at least 10 lines of code (override with `sonar.cpd.${language}.minimumLines`). For Java projects, a piece of code is considered duplicated when there is a series of at least 10 statements in a row, regardless of the number of tokens and lines. This threshold cannot be overridden. | 100 +`sonar.cpd.${language}.minimumLines` | (see above) | 10 + + +### Analysis Logging +Key | Description | Default +---|----|--- +`sonar.log.level` | Control the quantity / level of logs produced during an analysis. `DEBUG`: Display `INFO` logs + more details at `DEBUG` level. Similar to `sonar.verbose=true`. `TRACE`: Display `DEBUG` logs + the timings of all ElasticSearch queries and Web API calls executed by the SonarScanner. | `INFO` +`sonar.verbose` | Add more detail to both client and server-side analysis logs. Activates `DEBUG` mode for the scanner, and adds client-side environment variables and system properties to server-side log of analysis report processing. NOTE: There is the potential for this setting to expose sensitive information such as passwords if they are stored as server-side environment variables. | false +`sonar.showProfiling` | Display logs to see where the analyzer spends time. This parameter generates a file containing these timing infos in `<workingDir>/profiling/<moduleKey>-profiler.xml` where `<workingDir>` is: `.sonar/profiling/` when analysis is run with SonarScanner, and `target/sonar/profiling/` when SonarScanner for Maven is used. | `false` +`sonar.scanner.dumpToFile` | Outputs to the specified file the full list of properties passed to the scanner API as a means to debug analysis. | +`sonar.scanner.metadataFilePath` | Set the location where the scanner writes the `report-task.txt` file containing among other things the `ceTaskId`. | value of `sonar.working.directory` + +<!-- sonarqube --> +### Deprecated +[[danger]] +|  These parameters are listed for completeness, but are deprecated and should not be used in new analyses. +Key | Description +---|----|--- +`sonar.branch` **Deprecated since SQ 6.7** | _The Developer Edition provides fuller-featured branch functionality._ Manage SCM branches. Two branches of the same project are considered to be different projects in SonarQube. As a consequence issues found in a project A in a branch B1 are not linked to issues found for this project A in a branch B2. There is no way to automatically resolve issues from B2 when they are resolved in B1 as again A-B1 & A-B2 are considered separated projects. +`sonar.language` **Deprecated since SQ 4.5** | Set the language of the source code to analyze. Browse the Plugin Library page to get the list of all available languages. If not set, a multi-language analysis will be triggered. +`sonar.profile` **Deprecated since SQ 4.5** | Override the profile to be used. This should be set on a per-langauge basis through the UI instead. +`sonar.analysis.mode` **Deprecated since SQ 6.6** | This parameter is set to `preview` as part of non-Developer Edition PR decoration. + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/analysis/background-tasks.md b/server/sonar-docs/src/pages/analysis/background-tasks.md index c12fcfde131..63c1af4b9d1 100644 --- a/server/sonar-docs/src/pages/analysis/background-tasks.md +++ b/server/sonar-docs/src/pages/analysis/background-tasks.md @@ -10,7 +10,7 @@ A Background Task can be: ## What happens after the scanner is done analyzing? -Analysis is not complete until the relevant Background Task has been completed. Even though the SonarQube Scanner's log shows `EXECUTION SUCCESS`, the analysis results will not be visible in the SonarQube project until the Background Task has been completed. After a SonarQube Scanner has finished analyzing your code, the result of the analysis (Sources, Issues, Metrics) - the Analysis Report - is sent to SonarQube Server for final processing by the Compute Engine. Analysis Reports are queued and processed serially. +Analysis is not complete until the relevant Background Task has been completed. Even though the SonarScanner's log shows `EXECUTION SUCCESS`, the analysis results will not be visible in the {instance} project until the Background Task has been completed. After a SonarScanner has finished analyzing your code, the result of the analysis (Sources, Issues, Metrics) - the Analysis Report - is sent to {instance} Server for final processing by the Compute Engine. Analysis Reports are queued and processed serially. At the Project level, when there is a pending Analysis Report waiting to be consumed, you have a "Pending" notification in the header, next to the date of the most recent completed analysis. diff --git a/server/sonar-docs/src/pages/analysis/generic-issue.md b/server/sonar-docs/src/pages/analysis/generic-issue.md index 27ef5577131..6028d9f16d4 100644 --- a/server/sonar-docs/src/pages/analysis/generic-issue.md +++ b/server/sonar-docs/src/pages/analysis/generic-issue.md @@ -3,12 +3,12 @@ title: Generic Issue Data url: /analysis/generic-issue/ --- -SonarQube supports a generic import format for raising "external" issues in code. It is intended to allow you to import the issues from your favorite linter even if no plugin exists for it. +{instance} supports a generic import format for raising "external" issues in code. It is intended to allow you to import the issues from your favorite linter even if no plugin exists for it. External issues suffer from two important limitations: -* they cannot be managed within SonarQube; for instance, there is no ability to mark them False Positive. -* the activation of the rules that raise these issues cannot be managed within SonarQube. In fact, external rules are not visible in the Rules page or reflected in any Quality Profile. +* they cannot be managed within {instance}; for instance, there is no ability to mark them False Positive. +* the activation of the rules that raise these issues cannot be managed within {instance}. In fact, external rules are not visible in the Rules page or reflected in any Quality Profile. External issues and the rules that raise them must be managed in the configuration of your linter. diff --git a/server/sonar-docs/src/pages/analysis/generic-test.md b/server/sonar-docs/src/pages/analysis/generic-test.md index d7fa694f7d9..a6ae2269af4 100644 --- a/server/sonar-docs/src/pages/analysis/generic-test.md +++ b/server/sonar-docs/src/pages/analysis/generic-test.md @@ -3,7 +3,7 @@ title: Generic Test Data url: /analysis/generic-test/ --- -Out of the box, SonarQube supports generic formats for test coverage and test execution import. If your coverage engines' native output formats aren't supported by your language plugins, simply covert them to these formats. +Out of the box, {instance} supports generic formats for test coverage and test execution import. If your coverage engines' native output formats aren't supported by your language plugins, simply covert them to these formats. ## Generic Coverage Report paths should be passed in a comma-delimited list to: diff --git a/server/sonar-docs/src/pages/analysis/overview.md b/server/sonar-docs/src/pages/analysis/overview.md index 1dc4166abed..6aa11afa5c0 100644 --- a/server/sonar-docs/src/pages/analysis/overview.md +++ b/server/sonar-docs/src/pages/analysis/overview.md @@ -3,26 +3,54 @@ title: Overview url: /analysis/overview/ --- -Once the SonarQube platform has been installed, you're ready to install an analyzer and begin creating projects. To do that, you must install and configure the scanner that is most appropriate for your needs. Do you build with: - <!-- sonarcloud --> -* TravisCI for SonarCloud - [SonarCloud Travis addon](https://docs.travis-ci.com/user/sonarcloud/) +## Prepare your organization + +A project must belong to an [organization](/organizations/overview/). Create one if you intend to collaborate with your team mates, or use your personal organization for test purposes. + +[[info]] +| ** Important note for private code:** Newly created organizations and personal organizations are under a free plan by default. This means projects analyzed on these organizations are public by default: the code will be browsable by anyone. If you want private projects, you should [upgrade your organization to a paid plan](/sonarcloud-pricing/). + +Find the key of your organization, you will need it at later stages. It can be found on the top right corner of your organization's header. + +## Run analysis + +SonarCloud currently does not trigger analyses automatically - this feature will come in a near future. Currently, it's up to you to launch them inside your existing CI scripts using the available scanners: +* Gradle - [SonarScanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) +* MSBuild - [SonarScanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) +* Maven - use the [SonarScanner for Maven](https://redirect.sonarsource.com/doc/install-configure-scanner-maven.html) +* Ant - [SonarScanner for Ant](https://redirect.sonarsource.com/doc/install-configure-scanner-ant.html) +* anything else (CLI) - [SonarScanner](https://redirect.sonarsource.com/doc/install-configure-scanner.html) + +After creating a project, the tutorial available on its homepage will guide you to find how to trigger an analysis. + + Remember that depending on which cloud solution you are using for your developments, you can rely on dedicated integrations to help you: + +* [GitHub](/integrations/github/) +* [Bitbucket Cloud](/integrations/bitbucketcloud/) +* [Azure DevOps (formerly VSTS)](/integrations/vsts/) + <!-- /sonarcloud --> -* Gradle - [SonarQube Scanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) -* MSBuild - [SonarQube Scanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) -* Maven - use the [SonarQube Scanner for Maven](https://redirect.sonarsource.com/doc/install-configure-scanner-maven.html) -* Jenkins - [SonarQube Scanner for Jenkins](https://redirect.sonarsource.com/plugins/jenkins.html) -* VSTS / TFS - [SonarQube Extension for VSTS-TFS](https://redirect.sonarsource.com/doc/install-configure-scanner-tfs-ts.html) -* Ant - [SonarQube Scanner for Ant](https://redirect.sonarsource.com/doc/install-configure-scanner-ant.html) -* anything else (CLI) - [SonarQube Scanner](https://redirect.sonarsource.com/doc/install-configure-scanner.html) + +<!-- sonarqube --> +Once the SonarQube platform has been installed, you're ready to install an analyzer and begin creating projects. To do that, you must install and configure the scanner that is most appropriate for your needs. Do you build with: + +* Gradle - [SonarScanner for Gradle](https://redirect.sonarsource.com/doc/gradle.html) +* MSBuild - [SonarScanner for MSBuild](https://redirect.sonarsource.com/doc/install-configure-scanner-msbuild.html) +* Maven - use the [SonarScanner for Maven](https://redirect.sonarsource.com/doc/install-configure-scanner-maven.html) +* Jenkins - [SonarScanner for Jenkins](https://redirect.sonarsource.com/plugins/jenkins.html) +* Azure DevOps - [SonarQube Extension for Azure DevOps](https://redirect.sonarsource.com/doc/install-configure-scanner-tfs-ts.html) +* Ant - [SonarScanner for Ant](https://redirect.sonarsource.com/doc/install-configure-scanner-ant.html) +* anything else (CLI) - [SonarScanner](https://redirect.sonarsource.com/doc/install-configure-scanner.html) **Note** that we do not recommend running an antivirus scanner on the machine where a SonarQube analysis runs, it could result in unpredictable behavior. A project is created in the platform automatically on its first analysis. However, if you need to set some configuration on your project before its first analysis, you have the option of provisioning it via Administration options. +<!-- /sonarqube --> ## What does analysis produce? -SonarQube can perform analysis on 20+ different languages. The outcome of this analysis will be quality measures and issues (instances where coding rules were broken). However, what gets analyzed will vary depending on the language: +{instance} can perform analysis on 20+ different languages. The outcome of this analysis will be quality measures and issues (instances where coding rules were broken). However, what gets analyzed will vary depending on the language: * On all languages, "blame" data will automatically be imported from supported SCM providers. Git and SVN are supported automatically. Other providers require additional plugins. * On all languages, a static analysis of source code is performed (Java files, COBOL programs, etc.) @@ -30,12 +58,15 @@ SonarQube can perform analysis on 20+ different languages. The outcome of this a * A dynamic analysis of code can be performed on certain languages. ## Will all files be analyzed? -By default, only files that are recognized by a language analyzer are loaded into the project during analysis. For example if your SonarQube instance had only SonarJava SonarJS on board, all .java and .js files would be loaded, but .xml files would be ignored. +By default, only files that are recognized by a language analyzer are loaded into the project during analysis. +<!-- sonarqube --> +For example if your SonarQube instance had only SonarJava SonarJS on board, all .java and .js files would be loaded, but .xml files would be ignored. +<!-- /sonarqube --> ## What happens during analysis? During analysis, data is requested from the server, the files provided to the analysis are analyzed, and the resulting data is sent back to the server at the end in the form of a report, which is then analyzed asynchronously server-side. -Analysis reports are queued, and processed sequentially, so it is quite possible that for a brief period after your analysis log shows completion, the updated values are not visible in your SonarQube project. However, you will be able to tell what's going on because an icon will be added on the project homepage to the right of the project name. Mouse over it for more detail (and links if you're logged in with the proper permissions). +Analysis reports are queued, and processed sequentially, so it is quite possible that for a brief period after your analysis log shows completion, the updated values are not visible in your {instance} project. However, you will be able to tell what's going on because an icon will be added on the project homepage to the right of the project name. Mouse over it for more detail (and links if you're logged in with the proper permissions).  @@ -45,7 +76,7 @@ The icon goes away once processing is complete, but if analysis report processin  -## F.A.Q. +## FAQ **Q.** Analysis errors out with `java.lang.OutOfMemoryError: GC overhead limit exceeded`. What do I do? **A.** This means your project is too large or too intricate for the scanner to analyze with the default memory allocation. To fix this you'll want to allocate a larger heap (using `-Xmx[numeric value here]`) to the process running the analysis. Some CI engines may give you an input to specify the necessary values, for instance if you're using a Maven Build Step in a Jenkins job to run analysis. Otherwise, use Java Options to set a higher value. Note that details of setting Java Options are omitted here because they vary depending on the environment. diff --git a/server/sonar-docs/src/pages/analysis/pull-request.md b/server/sonar-docs/src/pages/analysis/pull-request.md index 4e17d90c01d..50c85a98307 100644 --- a/server/sonar-docs/src/pages/analysis/pull-request.md +++ b/server/sonar-docs/src/pages/analysis/pull-request.md @@ -12,24 +12,24 @@ _Pull Request analysis is available as part of [Developer Edition](https://redir Pull Request analysis allows you to: -* see your Pull Request (PR) analysis results in the SonarQube UI and see the green or red status to highlight the existence of open issues. -* automatically decorate your PRs with SonarQube issues in your SCM provider's interface. +* see your Pull Request (PR) analysis results in the {instance} UI and see the green or red status to highlight the existence of open issues. +* automatically decorate your PRs with {instance} issues in your SCM provider's interface. -PRs are visible in SonarQube from the "branches and pull requests" dropdown menu of your project. +PRs are visible in {instance} from the "branches and pull requests" dropdown menu of your project. -When PR decoration is enabled, SonarQube publishes the status of the analysis (Quality Gate) on the PR. +When PR decoration is enabled, {instance} publishes the status of the analysis (Quality Gate) on the PR. -When "Confirm", "Resolved as False Positive" or "Won't Fix" actions are performed on issues in SonarQube UI, the status of the PR is updated accordingly. This means, if you want to get a green status on the PR, you can either fix the issues for real or "Confirm", "Resolved as False Positive" or "Won't Fix" any remaining issues available on the PR. +When "Confirm", "Resolved as False Positive" or "Won't Fix" actions are performed on issues in {instance} UI, the status of the PR is updated accordingly. This means, if you want to get a green status on the PR, you can either fix the issues for real or "Confirm", "Resolved as False Positive" or "Won't Fix" any remaining issues available on the PR. -PR analyses on SonarQube are deleted automatically after 30 days with no analysis. This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. +PR analyses on {instance} are deleted automatically after 30 days with no analysis. This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. <!-- sonarcloud --> -## Integrations for GitHub, Bitbucket Cloud and VSTS -If your repositories are hosted on GitHub, Bitbucket Cloud or VSTS, check out first the dedicated Integrations for: [BitBucketCloud](/integrations/bitbucketcloud/), [GitHub](/integrations/github/), and [VSTS](/integrations/vsts/). Chances are that you do not need to read this page further since those integrations handle the configuration and analysis parameters for you. +## Integrations for GitHub, Bitbucket Cloud and Azure DevOps +If your repositories are hosted on GitHub, Bitbucket Cloud or Azure DevOps, check out first the dedicated Integrations for: [BitBucketCloud](/integrations/bitbucketcloud/), [GitHub](/integrations/github/), and [Azure DevOps](/integrations/vsts/). Chances are that you do not need to read this page further since those integrations handle the configuration and analysis parameters for you. <!-- /sonarcloud --> ## Analysis Parameters -### Pull Request Analysis in SonarQube +### Pull Request Analysis in {instance} These parameters enable PR analysis: | Parameter Name | Description | @@ -46,14 +46,14 @@ To activate PR decoration, you need to: * feed some specific parameters (GitHub only) #### Authentication Token -The first thing to configure is the authentication token that will be used by SonarQube to decorate the PRs. This can be configured in **Administration > Pull Requests**. The field to configure depends on the provider. +The first thing to configure is the authentication token that will be used by {instance} to decorate the PRs. This can be configured in **Administration > Pull Requests**. The field to configure depends on the provider. -For GitHub Enterprise or GitHub.com, you need to configure the **Authentication token** field. For VSTS/TFS, it's the **Personal access token**. +For GitHub Enterprise or GitHub.com, you need to configure the **Authentication token** field. For Azure DevOps, it's the **Personal access token**. #### Pull Request Provider | Parameter Name | Description | | --------------------- | ------------------ | -| `sonar.pullrequest.provider` | `github` or `vsts` or `bitbucketcloud`<br/> This is the name of the system managing your PR. In VSTS/TFS, when the Analyzing with SonarQube Extension for VSTS-TFS is used, `sonar.pullrequest.provider` is automatically populated with "vsts". Same on GitHub if you are using the Travis CI Add-on, and on Bitbucket Cloud if you are building with Bitbucket Pipelines.| +| `sonar.pullrequest.provider` | `github` or `vsts` or `bitbucketcloud`<br/> This is the name of the system managing your PR. In Azure DevOps, when the {instance} Extension for Azure DevOps is used, `sonar.pullrequest.provider` is automatically populated with "vsts". Same on GitHub if you are using the Travis CI Add-on, and on Bitbucket Cloud if you are building with Bitbucket Pipelines.| #### GitHub Parameters | Parameter Name | Description | diff --git a/server/sonar-docs/src/pages/analysis/scm-integration.md b/server/sonar-docs/src/pages/analysis/scm-integration.md index 78a498f9c81..badf2de871b 100644 --- a/server/sonar-docs/src/pages/analysis/scm-integration.md +++ b/server/sonar-docs/src/pages/analysis/scm-integration.md @@ -3,14 +3,56 @@ title: SCM Integration url: /analysis/scm-integration/ --- +## Table of Contents + Collecting SCM data during code analysis can unlock a number of SonarQube features: * Automatic Issue Assignment * code annotation (blame data) in the Code Viewer * SCM-driven detection of new code (to help with [Fixing the Water Leak](/user-guide/fixing-the-water-leak/)). Without SCM data, SonarQube determines new code using analysis dates (to timestamp modification of lines). -### Turning it on/off SCM integration requires support for your individual SCM provider. Git and SVN are supported by default. <!-- sonarqube -->For other SCM providers, see the Marketplace.<!-- /sonarqube --> If need be, you can toggle it off at global/project level via administration settings. +## Git +[Git](http://www.git-scm.com/) integration is supported out of the box with a pure Java implementation so there's no need to have Git command line tool installed on the machine where analysis is performed. + +Auto-detection of Git during analysis will happen if there is a .git folder in the project root directory or in one of its parent folders. Otherwise you can force the provider using `-Dsonar.scm.provider=git`. A full clone is required for this integration to be able to collect the required blame information (see Known Issues). If a shallow clone is detected, a warning will be logged and no attempt will be made to retrieve blame information.. + +### Known Issues + +* Git doesn't consider old "Mac" line ends (CR) as new lines. As a result the blame operation will contain fewer lines than expected by SonarQube and analysis will fail. The solution is to fix line ends to use either Windows (CR/LF) or Unix (LF) line ends. +* JGit doesn't support .mailmap file to "clean" email adress during the blame + +### Advanced information +The plugin uses [JGit](https://www.eclipse.org/jgit/) 4.9.0. JGit is a pure Java implementation of Git client. + +### How to investigate error during blame (only possible on Unix/Linux)? + +If you get an error when blame is executed on a file, it may be a limitation or a bug in JGit. To confirm please follow these steps: + +1. Download the standalone JGit command line distribution + +2. Try to execute the blame command on the offending file: + `chmod +x /path/to/org.eclipse.jgit.pgm-4.9.0.201710071750-r.sh /path/to/org.eclipse.jgit.pgm-4.9.0.201710071750-r.sh blame -w /path/to/offending/file` + +3. If you get the same error as during analysis, then this really looks like a bug in JGit (especially if you don't have an issue with the native git command line tool). Please try to do the previous steps with latest version of JGit and report all information to the [SonarQube Community Forum](https://community.sonarsource.com/). + + +## Subversion +[Subversion](https://subversion.apache.org/) integration is supported out of the box for Subversion 1.6 to 1.9.x. + +Auto-detection of SVN during analysis will happen if there is a `.svn` folder somewhere in the parent hierarchy of the project root. Otherwise you can force the provider using `-Dsonar.scm.provider=svn` on the analysis command line. + +### Known issues +If you get errors like: + +`Caused by: org.tmatesoft.svn.core.SVNException: svn: E200007: Retrieval of mergeinfo unsupported by 'https://pmd.svn.sourceforge.net/svnroot/pmd/trunk/pmd/src/main/java/net/sourceforge/pmd/AbstractConfiguration.java';` +It means the SVN server is not advertising the 'mergeinfo' capability. You can check the advertised capabilities by simply connecting to it: + +`telnet <svn_server> 3690` +Often this is because your SVN server is not >= 1.5 or your project was not properly migrated after a server upgrade. It could also be a misconfiguration of the server. + +You should try to run svnadmin upgrade **on the server**. For more information, please read https://subversion.apache.org/docs/release-notes/1.5.html#repos-upgrades. + diff --git a/server/sonar-docs/src/pages/architecture/architecture-integration.md b/server/sonar-docs/src/pages/architecture/architecture-integration.md new file mode 100644 index 00000000000..60e11c1efc9 --- /dev/null +++ b/server/sonar-docs/src/pages/architecture/architecture-integration.md @@ -0,0 +1,40 @@ +--- +title: Architecture and Integration +url: /architecture/architecture-integration/ +--- +## Overview +The SonarQube Platform is made of 4 components: + + +1. One SonarQube Server starting 3 main processes: + * Web Server for developers, managers to browse quality snapshots and configure the SonarQube instance + * Search Server based on Elasticsearch to back searches from the UI + * Compute Engine Server in charge of processing code analysis reports and saving them in the SonarQube Database +2. One SonarQube Database to store: + * the configuration of the SonarQube instance (security, plugins settings, etc.) + * the quality snapshots of projects, views, etc. +3. Multiple SonarQube Plugins installed on the server, possibly including language, SCM, integration, authentication, and governance plugins +4. One or more SonarScanners running on your Build / Continuous Integration Servers to analyze projects + +## Integration +The following schema shows how SonarQube integrates with other ALM tools and where the various components of SonarQube are used. + + +1. Developers code in their IDEs and use [SonarLint](https://sonarlint.org) to run local analysis. +2. Developers push their code into their favourite SCM : git, SVN, TFVC, ... +3. The Continuous Integration Server triggers an automatic build, and the execution of the SonarScanner required to run the SonarQube analysis. +4. The analysis report is sent to the SonarQube Server for processing. +5. SonarQube Server processes and stores the analysis report results in the SonarQube Database, and displays the results in the UI. +6. Developers review, comment, challenge their Issues to manage and reduce their Technical Debt through the SonarQube UI. +7. Managers receive Reports from the analysis. +Ops use APIs to automate configuration and extract data from SonarQube. +Ops use JMX to monitor SonarQube Server. + +## About Machines and Locations +* The SonarQube Platform cannot have more than one SonarQube Server and one SonarQube Database. +* For optimal performance, each component (server, database, scanners) should be installed on a separate machine, and the server machine should be dedicated. +* SonarScanners scale by adding machines. +* All machines must be time synchronized. +* The SonarQube Server and the SonarQube Database must be located in the same network +* SonarScanners don't need to be on the same network as the SonarQube Server. +* There is **no communication** between **SonarScanners** and the **SonarQube Database**. diff --git a/server/sonar-docs/src/pages/branches/branches-faq.md b/server/sonar-docs/src/pages/branches/branches-faq.md index 304db0a2fdd..bd67ff819a5 100644 --- a/server/sonar-docs/src/pages/branches/branches-faq.md +++ b/server/sonar-docs/src/pages/branches/branches-faq.md @@ -13,7 +13,7 @@ _Branch analysis is available as part of [Developer Edition](https://redirect.so ## How long are branches retained? Long-lived branches are retained until you delete them manually (**Administration > Branches**). Short-lived branches are deleted automatically after 30 days with no analysis. -This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. +This can be updated in **Configuration > General > Number of days before purging inactive short living branches**. For more, see [Housekeeping](/instance-administration/housekeeping/). ## Does my project need to be stored in an SCM like Git or SVN? No, you don't need to be connected to a SCM. But if you use Git or SVN we can better track the new files on short-lived branches and so better report new issues on the files that really changed during the life of the short-lived branch. diff --git a/server/sonar-docs/src/pages/faq.md b/server/sonar-docs/src/pages/faq.md new file mode 100644 index 00000000000..eab2b9ebd6b --- /dev/null +++ b/server/sonar-docs/src/pages/faq.md @@ -0,0 +1,42 @@ +--- +title: Frequently Asked Questions +url: /faq/ +--- + +## Table of Contents + +## How do I get rid of issues that are False-Positives? +**False-Positive and Won't Fix** +You can mark individual issues False Positive or Won't Fix through the issues interface. If you're using Short-lived branch and PR analysis provided by the Developer Edition, issues marked False Positive or Won't Fix will retain that status after merge. This is the preferred approach. + +**//NOSONAR** +Most language analyzers support the use of the generic mechanism: `//NOSONAR` at the end of the line of the issue. This will suppress the all issues - now and in the future - that might be raised on the line. + +## How do I find and remove projects that haven't been analyzed in a while? +In **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management)** you can search for **Last analysis before** to filter projects not analyzed since a specific date, and then use bulk **Delete** to remove the projects that match your filter. + +This can be automated by using the corresponding Web API: `api/projects/bulk_delete?analyzedBefore=YYYY-MM-DD`. + +<!-- sonarqube --> +## How do I trigger a full ElasticSearch reindex? +Currently, the only way to force a reindex is to: + +* Stop your server +* Remove the contents of the $SQ_HOME/data/es5 directory +* Start your server + +Before doing this, you should be aware first that processes are in place on the SonarQube side that out-of-sync indices are detected and corrected, and second that a full re-index can be quite lengthy depending on the size of your instance. + +## Why can't I use my HTTP Proxy since I upgraded to Java8u111? + +If you are getting this error in the logs when trying to use the Marketplace: +``` +java.io.IOException: Unable to tunnel through proxy. Proxy returns "HTTP/1.1 407 Proxy Authentication Required +``` +... you probably upgraded your Java8 installation with an update greater than 111. To fix that, update _$SONARQUBE_HOME/conf/sonar.properties` like this: +``` +sonar.web.javaOpts=-Xmx512m -Xms128m -XX:+HeapDumpOnOutOfMemoryError -Djdk.http.auth.tunneling.disabledSchemes="" +``` +Reference: http://www.oracle.com/technetwork/java/javase/8u111-relnotes-3124969.html +<!-- /sonarqube --> + diff --git a/server/sonar-docs/src/pages/index.md b/server/sonar-docs/src/pages/index.md index 240e76889da..3ae0bab7ea9 100644 --- a/server/sonar-docs/src/pages/index.md +++ b/server/sonar-docs/src/pages/index.md @@ -3,21 +3,65 @@ title: Documentation url: / --- +<!-- sonarcloud --> + +SonarCloud is the leading product for Continuous Code Quality online, totally free for open-source projects. It supports all major programming languages, including Java, C#, JavaScript, TypeScript, C/C++ and many more. If your code is closed source, SonarCloud also offers [a paid plan](/sonarcloud-pricing/) to run private analyses. + +SonarCloud offers end-to-end integrations for teams leveraging the following solutions in their development processes: + +* [GitHub](/integrations/github/) +* [Bitbucket Cloud](/integrations/bitbucketcloud/) +* [Azure DevOps](/integrations/vsts/) + +Are you ready to eliminate bugs and vulnerabilities? Will you champion quality code in your projects? + +<!-- /sonarcloud --> +<!-- static --> + +[[info]] +| **Welcome to the new SonarQube documentation** +| If you already have a SonarQube instance, you should be aware that we've made this documentation available within SonarQube itself (from v7.4). Just look under the "?" in the top menu to be sure you're always looking at the right documentation for _your_ version! +<!-- /static --> <!-- sonarqube --> -[SonarQube](http://www.sonarqube.org/)® software (previously called Sonar) is an open source quality management platform, dedicated to continuously analyze and measure technical quality, from project portfolio to method. If you wish to extend the SonarQube platform with open source plugins, have a look at our [plugin library](https://docs.sonarqube.org/display/PLUG/Plugin+Library). +[SonarQube](http://www.sonarqube.org/)® is an automatic code review tool to detect bugs, vulnerabilities and code smells in your code. It can integrate with your existing workflow to enable continuous code inspection across your project branches and pull requests. -## I write code +Below are a few key pointers, otherwise head over to the left pane for full documentation content and search capabilities. -* [Fixing the Water Leak](/user-guide/fixing-the-water-leak/) +### I write code +* Why [new code](/user-guide/fixing-the-water-leak/) is the most important +* [Concepts](/user-guide/concepts/) * [Quality Gates](/user-guide/quality-gates/) -* [Quality Profiles](/instance-administration/quality-profiles/) - <!-- /sonarqube --> +* [Issues](/user-guide/issues/) -<!-- sonarcloud --> +### I need to set up analysis +* [Analyzing Source Code](/analysis/overview/) +* [Branches](/branches/overview/) +* [Pull Requests](/analysis/pull-request/) -SonarCloud is the leading product for Continuous Code Quality online, totally free for open-source projects. It supports all major programming languages, including Java, C#, JavaScript, TypeScript, C/C++ and many more. If your code is closed source, SonarCloud also offers a paid plan to run private analyses. +### I administer a project +* [Project Existence](/project-administration/project-existence/) +* What's [included, excluded](/project-administration/narrowing-the-focus/) from analysis +* [Webhooks](/project-administration/webhooks/) +* [Project Settings](/project-administration/project-settings/) -SonarCloud offers end-to-end integrations for teams leveraging [GitHub](/integrations/github/), [VSTS](/integrations/vsts/), or [Bitbucket Cloud](/integrations/bitbucketcloud/) in their development processes. +### I administer a SonarQube Instance +* [Security](/instance-administration/security/) +* [Notifications](/instance-administration/notifications/) +* [Housekeeping](/instance-administration/housekeeping/) -<!-- /sonarcloud --> +### I do DevOps +* [Upgrading](/setup/upgrading/) +* [Monitoring](/instance-administration/monitoring/) +* [Running a Cluster](/setup/operate-cluster/) + +### Stay in touch! +* [Get help in the community](https://www.sonarqube.org/community/) +* [Source code](https://github.com/SonarSource) +* [Issue tracker](https://jira.sonarsource.com/) + +--- +Not using the current version? +[6.7.x (current LTS)](https://docs.sonarqube.org/display/SONARQUBE67/Documentation) +[Documentation for other versions](/previous-versions/) +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/instance-administration/compute-engine-performance.md b/server/sonar-docs/src/pages/instance-administration/compute-engine-performance.md new file mode 100644 index 00000000000..8542f72d597 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/compute-engine-performance.md @@ -0,0 +1,35 @@ +--- +title: Compute Engine Performance +url: /instance-administration/compute-engine-performance/ +--- + +_The ability to manage Compute Engine performance is available as part of the Enterprise Edition._ + +### How can I get analyses through the Compute Engine Queue faster? +If analyses are taking too long to process, it may be that you need to increase the number of Compute Engine (CE) workers (**[Administration > Projects > Background Tasks > Number of Workers](/#sonarqube-admin#/admin/background_tasks)**). + +There are two cases to consider: + +1. slowness comes from the fact that the queue is often full of pending tasks +1. individual tasks take a long time to process + +In the first case, increasing the number of workers could help. The second case should be carefully evaluated. In either case, when considering increasing the number of CE workers, two questions should be answered. + +* does my infrastructure allow me to increase the number of workers? +* to what extent should I increase the number of workers? I.E. What number should I configure? + +Increasing the number of workers will increase the stress on the resources consumed by the Compute Engine. Those resources are: + +* the DB +* disk I/O +* network +* heap +* CPU + +Of those, only the last two are internal to the CE. + +If slowness comes from any of the external resources (DB, disk I/O, network), then increasing the number of workers could actually slow the processing of individual reports (think of two people trying to go through a door at the same time). However, if your slowness is caused by large individual analysis reports hogging the CE worker for extended periods of time, then enabling parallel processing by adding another worker could help. But if you do, you need to take a look at the internal resources. + +CE workers are not CPU-intensive and memory use depends entirely on the project that was analyzed. Some need a lot of memory, others don't. But with multiple CE workers, you should increase CE heap size by a multiple of the number of workers. The same logic applies to CPU: if running with one worker consumes up to Y% of CPU, then you should plan for Z workers requiring Y*Z% of CPU. + +To accurately diagnose your situation, monitor network latency, the I/O of the SonarQube instance, and the database CPU and memory usage to evaluate whether slowness is mainly/mostly/only related to external resources. diff --git a/server/sonar-docs/src/pages/instance-administration/db-copy.md b/server/sonar-docs/src/pages/instance-administration/db-copy.md new file mode 100644 index 00000000000..6b3121f08f0 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/db-copy.md @@ -0,0 +1,98 @@ +--- +title: SonarQube DB Copy Tool +url: /instance-administration/db-copy/ +--- + +_The SonarQube DB Copy Tool is available to [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) customers._ + +This tool is provided to help you migrate your SonarQube database from one DB vendor to another. If, for instance, you've been using your SonarQube instance with Oracle and you want to migrate to PostgreSQL without loosing your analysis history, the SonarQube DB Copy Tool is what you need. + +In the following lines we will talk about "source" and "target" SonarQube database instances. The source instance is the database you want to discard and the target the one running you want to move to. + +The procedure is basically as follows: + +* connect to the source and target database +* read the data of the source database table by table +* save the data into the target database table by table +* recreate the sequences, index, ... on the target database + +## Installation +The SonarQube DB Copy Tool is provided as a standalone JAR file. **It must not be installed on your source or target SonarQube instances**. Put the JAR wherever your want on your machine, the only prerequisite is that this machine must be authorized to access your source and target SonarQube databases. + +The version of the JAR to use must be at least **1.3.1.48** + +## DB Copy Preparation Phase +In the preparation phase, you ready the target database by setting up SonarQube schema and populating it with the necessary tables so that you end up with the same database schema in the source and the target. + +1. Make sure your target database is up and running +1. On your target database, create the `sonar` schema. +1. Download and expand a copy of SonarQube that exactly matches the version you're running. +1. Configure your SonarQube copy to connect to the target database. (If you've placed your SonarQube copy on the same server that runs your primary SonarQube instance, you'll also need to configure non-default ports for your copy SonarQube instance.) +1. Start your copy SonarQube instance. It will connect to your empty target and populate the schema. +1. Once your copy instance is up and running (this indicates that the schema is fully populated), you can stop and delete it. +1. Refresh the Database Statistics on the target database before restarting SonarQube + +At this point, you have in your source and target databases the exact same lists of tables. + +## DB Copy Run Phase +There are only four steps in this phase: + +1. **Stop your primary SonarQube instance.** +1. Execute the base command jar with the correct parameters. +1. Update your primary SonarQube instance's configuration to point to the target DB +1. Restart your primary SonarQube instance. + +### Base command +``` +java -jar sonar-db-copy-1.3.1.480-jar-with-dependencies.jar +``` + +### Parameters +Name | Description | Required +---|---|---|--- +`-help`|Print this parameters help| no +`-urlSrc`|JDBC URL of the source database|yes +`-userSrc`|Username of the source database|yes +`-pwdSrc`|Password of the source database|yes +`-urlDest`|JDBC URL of the target database|yes +`-userDest`|Username of the target database|yes +`-pwdDest`|Password of the target database|yes +`-driverDest`|JDBC Driver of the target database|no +`-driverSrc`|JDBC Driver of the source database|no +`-T`|Comma separated list of tables to migrate|no + +## Execution Examples +First sonar-db-copy verifies if URLs can be reached and the database versions: + + +When the versions are different, the application stops. + + +Sometime when you have restarted the copy, the destination database version is 0. This is not a problem, the copy will continue. + + +Then it searches tables in source and destination database: + + +If there are missing tables, you will read this log: + + +Second sonar-db-copy truncates tables in target database and indicates the number of tables purged: + + +Of course, the tables missing can not be purged: + + +Third, sonar-db-copy reproduces data from source to destination and adjusts the sequence of destination database after the copy: + + +If there are some missing tables: + + +If errors appear during the copy, the process does NOT stop but the errors are displayed: + + +At the end sonar-db-copy reiterates the difference between source and destination database. + + + diff --git a/server/sonar-docs/src/pages/instance-administration/delegated-auth.md b/server/sonar-docs/src/pages/instance-administration/delegated-auth.md new file mode 100644 index 00000000000..ee89ab45118 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/delegated-auth.md @@ -0,0 +1,167 @@ +--- +title: Delegating Authentication +url: /instance-administration/delegated-auth/ +--- + +## Table of Contents + + +SonarQube comes with an onboard user database, as well as the ability to delegate authentication via HTTP Headers, or LDAP. + +## HTTP Header Authentication +This feature is designed to delegate user authentication to third-party systems (proxies/servers). + +When this feature is activated, SonarQube expects that the authentication is handled prior any query reaching the server. +The tool that handles the authentication should: + +* intercept calls to the SonarQube server +* take care of the authentication +* update the HTTP request header with the relevant SonarQube user information +* re-route the request to SonarQube with the appropriate header information + + + +All the parameters required to activate and configure this feature are available in SonarQube server configuration file (in _$SONARQUBE-HOME/conf/sonar.properties_). + +Using Http header authentication is an easy way integrate your SonarQube deployment with an in-house SSO implementation. + +## LDAP Authentication +You can configure SonarQube authentication and authorization to an LDAP server (including LDAP Service of Active Directory) by configuring the correct values in _$SONARQUBE-HOME/conf/sonar.properties_. + +The main features are: + +* Password checking against the external authentication engine. +* Automatic synchronization of usernames and emails. +* Automatic synchronization of relationships between users and groups (authorization). +* Ability to authenticate against both the external and the internal authentication systems. There is an automatic fallback on SonarQube internal system if the LDAP server is down. +* During the first authentication trial, if the user's password is correct, the SonarQube database is automatically populated with the new user. Each time a user logs into SonarQube, the username, the email and the groups this user belongs to that are refreshed in the SonarQube database. You can choose to have group membership synchronized as well, but this is not the default. + + + | Apache DS | OpenLDAP | Open DS | Active Directory +----|-----------|----------|---------|----------------- +Anonymous |  | | | +Simple|||| +LDAPS||| | +DIGEST-MD5|| || +CRAM-MD5|| || +GSSAPI|| | | + = successfully tested + +### Setup +1. Configure the LDAP plugin by editing _$SONARQUBE-HOME/conf/sonar.properties_ (see table below) +2. Restart the SonarQube server and check the log file for: +``` +INFO org.sonar.INFO Security realm: LDAP ... +INFO o.s.p.l.LdapContextFactory Test LDAP connection: OK +``` +1. Log into SonarQube +1. On logout users will be presented a login page (_/sessions/login_), where they can choose to login as technical user or a domain user by passing appropriate credentials + +From SonarScanners, we recommend using [local technical users](/instance-administration/security/) for authentication against SonarQube Server. + +**General Configuration** + +Property|Description|Default value|Required|Example +---|---|---|---|--- +`sonar.security.realm`|Set this to `LDAP` authenticate first against the external sytem. If the external system is not reachable or if the user is not defined in the external system, authentication will be performed against SonarQube's internal database.| none |Yes|`LDAP` (only possible value) +`sonar.authenticator.downcase`|Set to true when connecting to a LDAP server using a case-insensitive setup.|`false`|No +`ldap.url`|URL of the LDAP server. If you are using ldaps, you should install the server certificate into the Java truststore.| none |Yes|`ldap://localhost:10389` +`ldap.bindDn`|The username of an LDAP user to connect (or bind) with. Leave this blank for anonymous access to the LDAP directory.|none|No|`cn=sonar,ou=users,o=mycompany` +`ldap.bindPassword`|The password of the user to connect with. Leave this blank for anonymous access to the LDAP directory.|none|No|`secret` +`ldap.authentication`|Possible values: `simple`, `CRAM-MD5`, `DIGEST-MD5`, `GSSAPI`. See [the tutorial on authentication mechanisms](http://java.sun.com/products/jndi/tutorial/ldap/security/auth.html)|`simple`|No +`ldap.realm`|See [Digest-MD5 Authentication](http://java.sun.com/products/jndi/tutorial/ldap/security/digest.html), [CRAM-MD5 Authentication](http://java.sun.com/products/jndi/tutorial/ldap/security/crammd5.html)| none|No|example.org +`ldap.contextFactoryClass`|Context factory class.|`com.sun.jndi.ldap.LdapCtxFactory`|No +`ldap.StartTLS`|Enable use of `StartTLS`|`false`|No +`ldap.followReferrals`|Follow referrals or not. See [Referrals in the JNDI](http://docs.oracle.com/javase/jndi/tutorial/ldap/referral/jndi.html)|`true` + +**User Mapping** + +Property|Description|Default value|Required|Example for Active Directory +---|---|---|---|--- +`ldap.user.baseDn`|Distinguished Name (DN) of the root node in LDAP from which to search for users.|None|Yes|`cn=users,dc=example,dc=org` +`ldap.user.request`|LDAP user request.|`(&(objectClass=inetOrgPerson)(uid={login}))`|No|`(&(objectClass=user)(sAMAccountName={login}))` +`ldap.user.realNameAttribute`|Attribute in LDAP defining the user’s real name.|`cn`|No| +`ldap.user.emailAttribute`|Attribute in LDAP defining the user’s email.|`mail`|No| + +**Group Mapping** +Only [groups](http://identitycontrol.blogspot.fr/2007/07/static-vs-dynamic-ldap-groups.html) are supported (not [roles](http://identitycontrol.blogspot.fr/2007/07/static-vs-dynamic-ldap-groups.html)). Only [static groups](http://identitycontrol.blogspot.fr/2007/07/static-vs-dynamic-ldap-groups.html) are supported (not [dynamic groups](http://identitycontrol.blogspot.fr/2007/07/static-vs-dynamic-ldap-groups.html)). + +[[warning]] +|When group mapping is configured (i.e the below `ldap.group.*` properties are configured), membership in LDAP server will override any membership locally configured in SonarQube. LDAP server becomes the one and only place to manage group membership (and the info is fetched each time the user logs in). + +For the delegation of authorization, [groups must be first defined in SonarQube](/instance-administration/security/). Then, the following properties must be defined to allow SonarQube to automatically synchronize the relationships between users and groups. + +Property|Description|Default value|Required|Example for Active Directory +---|---|---|---|--- +`ldap.group.baseDn`|Distinguished Name (DN) of the root node in LDAP from which to search for groups.|none|No|`cn=groups,dc=example,dc=org` +`ldap.group.request`|LDAP group request.|`(&(objectClass=groupOfUniqueNames)(uniqueMember={dn}))`|No|`(&(objectClass=group)(member={dn}))` +`ldap.group.idAttribute`|Property used to specifiy the attribute to be used for returning the list of user groups in the compatibility mode.|`cn`|No|`sAMAccountName` + +### Sample Configuration +``` +# LDAP configuration +# General Configuration +sonar.security.realm=LDAP +ldap.url=ldap://myserver.mycompany.com +ldap.bindDn=my_bind_dn +ldap.bindPassword=my_bind_password + +# User Configuration +ldap.user.baseDn=ou=Users,dc=mycompany,dc=com +ldap.user.request=(&(objectClass=inetOrgPerson)(uid={login})) +ldap.user.realNameAttribute=cn +ldap.user.emailAttribute=mail + +# Group Configuration +ldap.group.baseDn=ou=Groups,dc=sonarsource,dc=com +ldap.group.request=(&(objectClass=posixGroup)(memberUid={uid})) +``` + +## Advanced LDAP Topics +### Authentication Methods +* **`Anonymous`** - Used when only read-only access to non-protected entries and attributes is needed when binding to the LDAP server. +* **`Simple`** Simple authentication is not recommended for production deployments not using the ldaps secure protocol since it sends a cleartext password over the network. +* **`CRAM-MD5`** - The Challenge-Response Authentication Method (CRAM) based on the HMAC-MD5 MAC algorithm ([RFC 2195](http://tools.ietf.org/html/rfc2195)). +* **`DIGEST-MD5`** - This is an improvement on the CRAM-MD5 authentication method ([RFC 2831](http://www.ietf.org/rfc/rfc2831.txt)). +* **`GSSAPI`** - GSS-API is Generic Security Service API ([RFC 2744](http://www.ietf.org/rfc/rfc2744.txt)). One of the most popular security services available for GSS-API is the Kerberos v5, used in Microsoft's Windows 2000 platform. + +For a full discussion of LDAP authentication approaches, see [RFC 2829](http://www.ietf.org/rfc/rfc2829.txt) and [RFC 2251](http://www.ietf.org/rfc/rfc2251.txt). + +### Multiple Servers +To configure multiple servers: +``` +# List the different servers +ldap.servers=server1,server2 + +# Configure server1 +ldap.server1.url=ldap://server1:1389 +ldap.server1.user.baseDn=dc=dept1,dc=com +... + +# Configure server2 +ldap.server2.url=ldap://server2:1389 +ldap.server2.user.baseDn=dc=dept2,dc=com +... +``` + +Authentication will be tried on each server, in the order they are listed in the configurations, until one succeeds. User/Group mapping will be performed against the first server on which the user is found. + +Note that all the LDAP servers must be available while (re)starting the SonarQube server. + +### Troubleshooting +* Detailed connection logs (and potential error codes received from LDAP server) are output to SonarQube's _$SONARQUBE_HOME/logs/web.log_, when logging is in `DEBUG` mode. + +* Time out when running SonarQube analysis using LDAP +Java parameters are documented here: http://docs.oracle.com/javase/jndi/tutorial/ldap/connect/config.html. Such parameters can be set in `sonar.web.javaAdditionalOpts` in _$SONARQUBE-HOME/conf/sonar.properties_. + +* Kerberos Troubleshooting resources + * [Enabling Kerberos Logging](http://support.microsoft.com/kb/262177/en-us) + * [Troubleshooting Kerberos Delegation](https://gallery.technet.microsoft.com/Troubleshooting-Kerberos-72837743) +* Troubleshooting NTLM + * [Enabling NTLM Logging](http://blogs.technet.com/b/askds/archive/2009/10/08/ntlm-blocking-and-you-application-analysis-and-auditing-methodologies-in-windows-7.aspx) + +## Authenticating Via Other Systems +Additionally, several plugins are available to allow delegation to other providers: +* Crowd - [SonarQube Crowd Plugin](https://github.com/SonarCommunity/sonar-crowd) +* GitHub - [GitHub Authentication Plugin](https://redirect.sonarsource.com/plugins/authgithub.html) +* Bitbucket - [Bitbucket Authentication Plugin](https://github.com/SonarQubeCommunity/sonar-auth-bitbucket) diff --git a/server/sonar-docs/src/pages/instance-administration/housekeeping.md b/server/sonar-docs/src/pages/instance-administration/housekeeping.md index bd11f3fd403..a99c78f682e 100644 --- a/server/sonar-docs/src/pages/instance-administration/housekeeping.md +++ b/server/sonar-docs/src/pages/instance-administration/housekeeping.md @@ -3,7 +3,7 @@ title: Housekeeping url: /instance-administration/housekeeping/ --- -When you run a new analysis of your project, some data that was previously available is cleaned out of the database. For example the source code of the previous analysis, measures at directory and file levels, and so on are automatically removed at the end of a new analysis. Additionally, some old analysis snapshots are also removed. +When you run a new analysis of your project or its branches or pull requests(PRs), some data that was previously available is cleaned out of the database. For example the source code of the previous analysis, measures at directory and file levels, and so on are automatically removed at the end of a new analysis. Additionally, some old analysis snapshots, PR analyses, and branches are also removed. Why? Well, it's useful to analyze a project frequently to see how its quality evolves. It is also useful to be able to see the trends over weeks, months, years. But when you look back in time, you don't really need the same level of detail as you do for the project's current state. To save space and to improve overall performance, the Database Cleaner deletes some rows in the database. Here is its default configuration: diff --git a/server/sonar-docs/src/pages/instance-administration/marketplace.md b/server/sonar-docs/src/pages/instance-administration/marketplace.md new file mode 100644 index 00000000000..06833157a83 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/marketplace.md @@ -0,0 +1,60 @@ +--- +title: Marketplace +url: /instance-administration/marketplace/ +--- + +## Table of Contents + +Administrators can access the Marketplace via **[Administration > Marketplace](/#sonarqube-admin#/admin/marketplace)**. The Marketplace is the place for keeping the pieces of the SonarQube platform up to date. It lets you: + +See + +* The currently installed SonarQube Edition +* Which plugins are installed +* Whether plugin updates are available +* Which other plugins are compatible with your version of SonarQube + +Discover + +* Which other Editions are available, to enable more features + +Install + +* New plugins +* Plugin updates + +To view/install plugin updates, your SonarQube server needs internet access. Installations require the platform to be restarted before they take effect. + +## Pending Operations + +When you perform an action in the Markplace (install, update or uninstall a plugin), a yellow banner appears at the top of the page showing pending operations that will be executed once SonarQube is restarted. Pending operations can be canceled until the server is restarted. + +## Restart SonarQube +Restarting SonarQube can be done manually from the command line by running `sonar.sh restart` or directly from the UI: + +* in the Update Center when you have Pending Changes, the restart button will be displayed in the yellow banner (see Pending Operations) +* in the System Info page at any time + +## Manual Updates +If your server has no access to the internet, you won't be able to rely on the Marketplace for plugins, and will have to handle plugin installations and upgrades manually. + +To see what plugins are available and which version of a plugin is appropriate for your server, use the [plugin version matrix](https://redirect.sonarsource.com/doc/plugin-version-matrix.html), which is kept up to date with plugin availability and compatibility. + +To install a plugin, simply download it using the manual download link on the plugin documentation page, place it in _$SONARQUBE_HOME/extensions/downloads_, and restart the server. + +## Which URLs does the Marketplace connect to? +The SonarQube Marketplace connects to https://update.sonarsource.org/ to get the list of plugins. Most of the referenced plugins are downloaded from: +* https://binaries.sonarsource.com/ +* https://github.com/ + +## Using the Marketplace behind a Proxy +Marketplace uses HTTP(S) connections to external servers to provide these services. If SonarQube is located behind a proxy, additional information must be provided in the _$SONARQUBE-HOME/conf/sonar.properties_ configuration file: +``` +http.proxyHost=<your.proxy.host> +http.proxyPort=<yout.proxy.port> + +#If proxy authentication is required +http.proxyUser=<your.proxy.user> +http.proxyPassword=<your.proxy.password> +``` +Note: the same properties can be used in the 'https.' form for HTTPS connections. diff --git a/server/sonar-docs/src/pages/instance-administration/monitoring.md b/server/sonar-docs/src/pages/instance-administration/monitoring.md new file mode 100644 index 00000000000..1b9036c8991 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/monitoring.md @@ -0,0 +1,137 @@ +--- +title: Monitoring +url: /instance-administration/monitoring/ +--- + +## Table of Contents + +Monitoring your SonarQube instance is key to keeping it healthy and having happy users. + +As a start, you can use this Web API to get an overview of the health of your SonarQube installation: + +* [api/system/health](/#sonarqube-admin#/api/system/health) + +## Java Process Memory + +The SonarQube application server consists of three main Java processes: + +* Web (including embedded web server) +* ElasticSearch +* Compute Engine + +Each of these Java processes has its own memory settings that can be configured in the _$SONARQUBE-HOME/conf/sonar.properties_ file. The default memory settings that ship with SonarQube are fine for most instances. If you are supporting a large SonarQube instance (more than 100 users or more than 5,000,000 lines of code) or an instance that is part of your Continuous Integration pipeline, you should monitor the memory and CPU usage of all three key Java processes on your instance, along with overall disk space. Monitoring will allow you to see if any of the processes is running short of resources and take action ahead of resource shortages. There are a large number of monitoring tools available, both open source and commercial, to help you with this task. SonarSource does not recommend or endorse any particular tool. + +## Memory settings + +You may need to increase your memory settings if you see the following symptoms: + +* Your monitoring tools show one or more of the SonarQube processes is reaching its memory limit +* Any of the SonarQube processes crashes and/or generates an out-of-memory error in the sonar.log file +* A SonarQube background task fails with an out-of-memory error in the background task log +* The size of the Issues index of your ElasticSearch instance (visible in the System Info) is greater than or equal to the memory allocated to the ElasticSearch Java process + +You can increase the maximum memory allocated to the appropriate process by increasing the -Xmx memory setting for the corresponding Java process in your _$SONARQUBE-HOME/conf/sonar.properties_ file: + +* For Web: sonar.web.javaOpts +* For ElasticSearch: sonar.search.javaOpts +* For Compute Engine: sonar.ce.javaOpts + +The -Xmx parameter accepts numbers in both megabytes (e.g. -Xmx2048m) and gigabytes (e.g. -Xmx2G) + +For detailed information on JMX Beans exposed by SonarQube and more ElasticSearch monitoring options, please visit our Monitoring Details page. + +## Exposed JMX MBeans + +The SonarQube Server offers visibility about what happens internally through the exposure of JMX MBeans. + +In addition to the classical Java MBeans providing information about the ClassLoader, OS, Memory and Threads you have access to four more MBeans in the SonarQube Server: + +* ComputeEngine +* Database +* SonarQube + +All these MBeans are read-only. It's not possible to modify or reset their values in real time. + +## ComputeEngineTasks MBean + +[[collapse]] +| ## ComputeEngineTasks MBean +| Attribute Name | Description +| ---|--- +| ProcessingTime | Measure the time (in ms) spent to process Background Tasks since the last restart of SonarQube. Its value will always increase and will be reset by a restart of SonarQube. This measure is very powerful when combined with SuccessCount and ErrorCount measures to get the average time to handle a Background Task, or when used to understand how much time the SonarQube Server is spending during a day to handle Background Tasks. It gives you an indication of the load on your server. +| ErrorCount | Number of Background Tasks which failed since the last restart of SonarQube +| PendingCount | Number of Background Tasks waiting to be processed since the last restart of SonarQube +| InProgressCount | Number of Background Tasks currently under processing. Its value is either 1 or 0, since SonarQube can process only one task at a time. +| SuccessCount | Number of Background Tasks successfully processed since the last restart of SonarQube +| WorkerCount | Number of Background Tasks that can be processed at the same time +| +| Note: +| * the total number of Background Tasks handled since the last restart of SonarQube is equal to SuccessCount + ErrorCount +| * these values are reset to their default values by restarting SonarQube + +[[collapse]] +| ## Database MBean +| ### Same attributes are available for both ComputeEngineServer and WebServer. +| Attribute Name | Description +| ---|--- +| MigrationStatus | Possible values are: UP_TO_DATE, REQUIRES_UPGRADE, REQUIRES_DOWNGRADE, FRESH_INSTALL (only available for WebServer). +| PoolActiveConnections | Number of active database connections +| PoolIdleConnections | Number of database connections waiting to be used +| PoolInitialSize | Initial size of the database connections pool. +| PoolMaxActiveConnections | Maximum number of active database connections +| PoolMaxIdleConnections | Maximum number of database connections waiting to be used +| PoolMaxWaitMillis | In milliseconds +| PoolRemoveAbandoned | Possible values : true, false +| PoolRemoveAbandonedTimeoutSeconds | In Seconds + +[[collapse]] +| ## SonarQube MBean +| Attribute Name | Description +| LogLevel | Log Level: INFO, DEBUG, TRACE +| ServerId | SonarQube Server ID +| Version | SonarQube Version + +## How do I Activate JMX? + +### Local Access + +There is nothing to activate to view SonarQube MBeans if your tool is running on the same server as the SonarQube Server. + +### Remote Access + +Here are examples of configuration to activate remote access to JMX MBeans. + +For the WebServer: +``` +# JMX WEB - 10443/10444 +sonar.web.javaAdditionalOpts=-Dcom.sun.management.jmxremote=true -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=true -Dcom.sun.management.jmxremote.port=10443 -Dcom.sun.management.jmxremote.rmi.port=10444 -Dcom.sun.management.jmxremote.password.file=/opt/sonarsource/sonar/conf/jmxremote.password -Dcom.sun.management.jmxremote.access.file=/opt/sonarsource/sonar/conf/jmxremote.access +``` + +For the ComputeEngine: + +There is no specific javaAdditionalOpts entry, simply amend the sonar.ce.javaOpts one. + +Example of `jmxremote.access`: + +``` +# +# JMX Access Control file +# +reader readonly +admin readwrite \ + create javax.management.monitor.*,javax.management.timer.*,com.sun.management.*,com.oracle.jrockit.* \ + unregister +``` + +Example of `jmxremote.password`: + +``` +# +# JMX Access Password file +# +reader readerpassword +admin adminpassword +``` + +Note: on `jmxremote.password`, you should apply `chmod 600` or `400` for security reasons. + diff --git a/server/sonar-docs/src/pages/instance-administration/notifications.md b/server/sonar-docs/src/pages/instance-administration/notifications.md new file mode 100644 index 00000000000..43563dc077c --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/notifications.md @@ -0,0 +1,18 @@ +--- +title: Notifications +url: /instance-administration/notifications/ +--- +At the end of each analysis, notifications are computed for each subscribed user. Then, asynchronously, these notifications are sent via email. + +To set the frequency with which the notification queue is processed, set `the sonar.notifications.delay` property (in seconds) in _$SONARQUBE-HOME/conf/sonar.properties_. The server must be restarted for the new value to be taken into account. + +## Who gets notifications +Only users who subscribe themselves will get notifications. With only one exception, there is no admin functionality to proactively subscribe another user. If you believe a user should be receiving notifications, then it's time to practice the gentle art of persuasion. + +### The exception +Notifications will automatically (without user opt-in) be sent to users with Quality Profile Administration rights when built-in quality profiles are updated. These updates can only happen via an upgrade of the relevant analyzer. This type of notification is on by default, and can be toggled globally in **[Administration > General Settings > General](/#sonarqube-admin#/admin/settings/)**. + +## Email Configuration +To configure the email server, go to **[Administration > General Settings > Email](/#sonarqube-admin#/admin/settings)**. + +Check also the Server base URL property at Administration > General Settings > General to make sure that links in those notification emails will redirect to the right SonarQube server URL. diff --git a/server/sonar-docs/src/pages/instance-administration/project-move.md b/server/sonar-docs/src/pages/instance-administration/project-move.md new file mode 100644 index 00000000000..e4ce1de9219 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/project-move.md @@ -0,0 +1,48 @@ +--- +title: Project Move +url: /instance-administration/project-move/ +--- + +_Project Move is available as part of [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html)_ + +## Table of Contents + +Project Move allows you to export a project from one SonarQube instance and import it into another, identically configured SonarQube instance. To use Project Move, you must have the Administer permission on the project in the source instance, and access to the file systems of both instances. + +## When to Use "Project Move" +In the following cases: + +* you want to create a central SonarQube instance at enterprise level and you want to keep the history created on N instances used previously at the team level +* your company is acquiring another company that already has a central SonarQube instance +* an application is transferred from one team to another in a large company and that company has several SonarQube instances + +## Prerequisites +In order to be able to export and then load your Project's data, the two SonarQube instances must have: + +* the exact same version +* the same plugins with the same versions +* the same custom metrics +* the same custom rules + +## How To Export +On the source instance: +* reanalyze the project one last time to make sure it is populated with data corresponding to your current SonarQube installation +* navigate to the project and at the project level, choose **Administration > Import / Export** +* click on the **Export** button to generate a zip file containing the settings and history of your Project (but not the source code). Note that if you need to change the Project's key, you must to do it before performing the export. + +A zip file containing all project data ex is generated in _$SONAR_SOURCE_HOME/data/governance/project_dumps/export/_ named _<project_key>.zip_ + +## How To Import +On the target instance: + +* With a user having the "Administer System" and "Create Projects" permissions, go to **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management/)** and [provision the project](/project-administration/project-existence/) using the same key the project had in the source instance. +* Configure the Project's permissions, and the Quality Profiles and Quality Gate associated to the Project +* Put the generated zip file into the directory _$SONAR_TARGET_HOME/data/governance/project_dumps/import_ +* Go to the Project's Home Page and choose **Administration > Import / Export** +* Click on the Import button to start importing your data +** Source code is not included in the zip file. Once the import is finished, trigger an analysis to import source files into the new instance. + +Notes: + +* If the import is successful, the zip file will automatically be deleted. +* It is not possible to import a Project that has been already analyzed on the target instance. diff --git a/server/sonar-docs/src/pages/instance-administration/quality-profiles.md b/server/sonar-docs/src/pages/instance-administration/quality-profiles.md index db513e758ac..cf514804e6a 100644 --- a/server/sonar-docs/src/pages/instance-administration/quality-profiles.md +++ b/server/sonar-docs/src/pages/instance-administration/quality-profiles.md @@ -5,7 +5,7 @@ url: /instance-administration/quality-profiles/ ## Overview -The Quality Profiles service is central to SonarQube, since it is where you define your requirements by defining sets of **rules** (ex: Methods should not have a Cognitive Complexity greater than 15). +The Quality Profiles service is central to {instance}, since it is where you define your requirements by defining sets of **rules** (ex: Methods should not have a Cognitive Complexity greater than 15). Ideally, all projects will be measured with the same profile for any given language, but that's not always practical. For instance, you may find that: @@ -15,7 +15,7 @@ Ideally, all projects will be measured with the same profile for any given langu Which is why you can define as many quality profiles as you wish even though it is recommended to have as few Quality Profiles as possible to ensure consistency across the projects in your company. To manage quality profiles, go to <!-- sonarqube -->[**Quality Profiles**](/#sonarqube#/profiles)<!-- /sonarqube --><!-- sonarcloud -->**Quality Profiles** page of your organization<!-- /sonarcloud -->, where you'll find profiles grouped by language. -Each language plugin comes with a predefined, built-in profile (usually called "Sonar way") so that you can get started very quickly with SonarQube analyses. This is why as soon as you install a new language plugin, at least one quality profile will be available for you. Each language must have a default profile (marked with the Default tag). Projects that are not explicitly associated with a specific profile will be analyzed using the language's default profile. +Each language plugin comes with a predefined, built-in profile (usually called "Sonar way") so that you can get started very quickly with {instance} analyses. This is why as soon as you install a new language plugin, at least one quality profile will be available for you. Each language must have a default profile (marked with the Default tag). Projects that are not explicitly associated with a specific profile will be analyzed using the language's default profile. When starting from a new installation, it's tempting to use Sonar way as your default profile because it contains all the rules that are generally applicable to most projects. But as a best practice, you should create a new profile (you can populate it by copying the contents of Sonar way) and use it instead. Why? First because Sonar way profiles aren't editable, so you won't be able to customize it to your needs. Also, that lets you treat Sonar way as a baseline against which you can track your own profile as you make changes to it (and you will). Plus, Sonar way is typically updated with each new version of the plugin to add rules and sometimes adjust rule severities. Any profile that inherits from the built-in Sonar Way will de-facto be automatically updated at the same time. @@ -33,7 +33,7 @@ Many times people want to work from a profile that's based on a built-in profile ### Know what's changed in a profile? -When SonarQube notices that an analysis was performed with a profile that is different in some way from the previous analysis, a Quality Profile event is added to the project's event log. To see the changes in a profile, navigate to the profile (**Quality Profiles > [ Profile Name ]**), and choose **Changelog**. This may help you understand how profile changes impact the issues raised in an analysis. +When {instance} notices that an analysis was performed with a profile that is different in some way from the previous analysis, a Quality Profile event is added to the project's event log. To see the changes in a profile, navigate to the profile (**Quality Profiles > [ Profile Name ]**), and choose **Changelog**. This may help you understand how profile changes impact the issues raised in an analysis. Additionally, users with Quality Profile administration privileges are notified by email each time a built-in profile (one that is provided directly by an analyzer) is updated. These updates can only be caused by analyzer updates. diff --git a/server/sonar-docs/src/pages/instance-administration/security.md b/server/sonar-docs/src/pages/instance-administration/security.md new file mode 100644 index 00000000000..c2457f22898 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/security.md @@ -0,0 +1,155 @@ +--- +title: Security +url: /instance-administration/security/ +--- + +## Table of Contents + +## Overview + +SonarQube comes with a number of global security features: + +* on-board authentication and authorization mechanisms +* the ability to force users to authenticate before they can see any part of a SonarQube instance +* the ability to delegate to authentication (for more see [Delegating Authentication](/instance-administration/delegated-auth/)) + +Additionally, you can configure at a group or user level who can: +* see that a project even exists +* access a project's source code +* administer a project (set exclusion patterns, tune plugin configuration for that project, etc.) +* administer Quality Profiles, Quality Gates, and the SonarQube instance itself. + + +Another aspect of security is the encryption of settings such as passwords. SonarQube provides a built-in mechanism to encrypt settings. + +## Authentication +The first question that should be answered when setting the security strategy for SonarQube is: Can anonymous users browse the SonarQube instance or is authentication be required? + +To force user authentication, log in as a system administrator, go to **[Administration > Configuration > General Settings > Security](/#sonarqube-admin#/admin/settings?category=security)**, and set the **Force user authentication** property to true. + +### Authentication Mechanisms +Authentication can be managed through a number of mechanisms: + +* Via the SonarQube built-in users/groups database +* Via external identity providers such as an LDAP server (including LDAP Service of Active Directory), GitHub etc. See the Authentication & Authorization section of the Plugin Library. +* Via HTTP headers + +### Technical Users +When you create a user in SonarQube's own database, it is considered local and will only be authenticated against SonarQube's own user/group database rather than against any external tool (LDAP, Active Directory, Crowd, etc.). By default `admin` is a local account. + +Similarly, all non-local accounts will be authenticated only against the external tool. + +An Administrator can manage tokens on a user's behalf via **[Administration > Security > Users](/#sonarqube-admin#/admin/users)**. From here, click in the user's **Tokens** column to see the user's existing tokens, and either revoke existing tokens or generate new ones. Once established, a token is the only credential needed to run an analysis. Tokens should be passed as the value of the `sonar.login` property. + +### Default Admin Credentials +When installing SonarQube, a default user with Administer System permission is created automatically: + +* Login: admin +* Password: admin + +## Reinstating Admin Access +If you changed and then lost the `admin` password, you can reset it using the following query: +``` +update users set crypted_password = '$2a$12$uCkkXmhW5ThVK8mpBvnXOOJRLd64LJeHTeCkSuB3lfaR2N0AYBaSi', salt=null, hash_method='BCRYPT' where login = 'admin' +``` +If you've deleted `admin` and subsequently locked out the other users with global administrative permissions, you'll need to re-grant `admin` to a user with the following query: +``` +INSERT INTO user_roles(user_id, role) VALUES ((select id from users where login='mylogin'), 'admin'); +``` + +## Authorization +The way authorization is implemented in SonarQube is pretty standard. It is possible to create as many users and groups of users as needed. The users can then be attached (or not) to (multiple) groups. Groups and / or users are then given (multiple) permissions. The permissions grant access to projects, services and functionalities. + +To administer groups and users, choose **Administration > Security**, and use the sub-menu items. + +### User +Multiple integrations that allow the delegation of authentication are available (see the [Plugin Library](https://redirect.sonarsource.com/doc/plugin-library.html) and [Other Plugins](https://docs.sonarqube.org/display/PLUG/Other+Plugins), but you can manually create and edit users at **[Settings > Security > Users](/#sonarqube-admin#/admin/users)**. For manually-created users, login and password can be set at creation. Manually-created users can edit their passwords. + +During both user creation and edit, you can set an account's screen name, email address. User login and email address will be implicitly recognized by the Issue Assignment feature as SCM accounts if applicable, but you can set additional SCM accounts explicitly. + +### Group +A group is a set of users. + +To administer groups, go to **[Administration > Security > Groups](/#sonarqube-admin#/admin/groups)**. + +To edit the membership of a group, click the icon next to the membership total. + +Two groups have a special meaning: + +* **Anyone** is a group that exists in the system, but that cannot be managed. Every user belongs to this group, including Anonymous user. +* **sonar-users** is the default group to which users are automatically added. + +### Global Permissions +To set global permissions, log in as a System administrator and go to **[Administration > Security > Global Permissions](/#sonarqube-admin#/admin/permissions)**. + +* **Administer System**: All administration functions for the instance: global configuration. +* **Administer Quality Profiles**: Any action on quality profiles. +* **Administer Quality Gates**: Any action on quality gates +* **Execute Analysis**: Execute analyses (project, view, report, developer), and to get all settings required to perform the analysis, even the secured ones like the scm account password, and so on. +* **Create Projects**: Initialize the structure of a new project before its first analysis. This permission is also required when doing the very first analysis of a project that has not already been created via the GUI. * ** +* **Create Applications**: Create a new Application. * ** +* **Create Portfolios**: Create a new Portfolio. * ** + +\* Users with any explicit create permission will see a "+" item in the top menu giving access to these functions. If these permissions are removed from global administrators, they will loose quick access to them via the "+" menu, **but retain access to creation** via the **Administration** menu. + +** Creating an item does not automatically grant rights to administer it. For that, see _Creators permission_ below. + +### Project Permissions +Project permissions are available from the project-level Administration menu: **Administration > Permissions**. + +Project visibility may be toggled between public or private. Making a project private hides its source code and measures from the `Anyone` group. For both public and private projects, four different permissions can be set: + +* **Administer Issues**: Change the type and severity of issues, resolve issues as being "Won't Fix" or "False Positive" (users also need "Browse" permission). +* **Administer Security Hotspots**: "Detect" (convert) a Vulnerability from a "Security Hotspot", reject, clear, accept or reopen a "Security Hotspot" (users also need "Browse" permission). +* **Administer**: Access project settings and perform administration tasks (users also need "Browse" permission). +* **Execute Analysis**: Execute analyses (project, view, report, developer), and to get all settings required to perform the analysis, even the secured ones like the scm account password, the jira account password, and so on. + +Private projects have two additional permissions: +* **Browse**: Access a project, browse its measures, issues and perform some issue edits (confirm/resolve/reopen, assignment, comment). +* **See Source Code**: View the project's source code. + +Note that permissions _are not_ cumulative. For instance, if you want to be able to administer the project, you also have to be granted the Browse permission to be able to access the project (which is the default for Public project). + +You can either manually grant permissions for each project to some users and groups or apply permission templates to projects. + +## Permission Templates for Default Permissions +SonarQube ships with a default permissions template, which automatically grants specific permissions to certain groups when a project, portfolio, or application is created. It is possible to edit this template, and to create additional templates. A separate template can be set for each type of resource. Further, for projects you can have a template apply only to a subset of new projects using a project key regular expression (the template's **Project Key Pattern**). By default, every new project with a key that matches the supplied pattern will have template's permissions applied. + +Templates are empty immediately after creation. Clicking on the template name will take you to its permission editing interface. + +Templates are administered through **[Administration > Security > Permission Templates](/#sonarqube-admin#/admin/permission_templates)**. + +### Creators permissions +**Creators** is a special group that appears only in the permission template editing interface. Any permissions assigned to this group will at the time of project/portfolio/application creation be granted to the single user account used to create the project. This allows SonarQube administrators to let users autonomously create and administer their own projects. + +While templates can be applied after project creation, applying a template that includes "Creators" permissions to an existing project/portfolio/application will not grant the relevant permissions to the project's original creator because that association is not stored. + +### Reset project permissions to a template +To apply permission templates to projects go to **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management)**. You can either apply a template to a specific project using the project-specific **Actions > Apply Permission Template** option or use the Bulk Apply Permission Template to apply a template to all selected projects. + +Note that there is no relation between a project and a permission template, meaning that: +* the permissions of a project can be modified after a permission template has been applied to this project +* none of the project permissions is changed when a permission template is modified + +## Settings Encryption +Encryption is mostly used to remove clear passwords from settings (database or SCM credentials for instance). The implemented solution is based on a symetric key algorithm. The key point is that the secret key is stored in a secured file on disk. This file must owned by and readable only by the system account that runs the SonarQube server. + +The algorithm is AES 128 bits. Note that 256 bits cipher is not used because it's not supported by default on all Java Virtual Machines ([see this article](https://confluence.terena.org/display/~visser/No+256+bit+ciphers+for+Java+apps)). + +1. **Generate the secret key** +A unique secret key must be shared between all parts of the SonarQube infrastructure (server and analyzers). To generate it, go to **[Administration > Configuration > Encryption](/#sonarqube-admin#/admin/settings/encryption)** and click on Generate Secret Key. +1. **Store the secret key on the SonarQube server** + * Copy the generated secred key to a file on the machine hosting the SonarQube server. The default location is _~/.sonar/sonar-secret.txt_. If you want to store it somewhere else, set its path through the `sonar.secretKeyPath` property in _$SONARQUBE-HOME/conf/sonar.properties_ + * Restrict file permissions to the account running the SonarQube server (ownership and read-access only). + * Restart your SonarQube server +1. **Generate the encrypted values of your settings** +Go back to **[Administration > Configuration > Encryption](/#sonarqube-admin#/admin/settings/encryption)** and use the form that has been added to the interface to generated encrypted versions of your values. + +1. **Use the encrypted values in your SonarQube server configuration** +Simply copy these encrypted values into _$SONARQUBE-HOME/conf/sonar.properties_ +``` +sonar.jdbc.password={aes}CCGCFg4Xpm6r+PiJb1Swfg== # Encrypted DB password +... +sonar.secretKeyPath=C:/path/to/my/secure/location/my_secret_key.txt +``` + diff --git a/server/sonar-docs/src/pages/instance-administration/system-info.md b/server/sonar-docs/src/pages/instance-administration/system-info.md new file mode 100644 index 00000000000..6ce0dc6ea67 --- /dev/null +++ b/server/sonar-docs/src/pages/instance-administration/system-info.md @@ -0,0 +1,399 @@ +--- +title: Server Logs & System Info +url: /instance-administration/system-info/ +--- + +## Table of Contents + +The System Info page is found at **[Administration > System](/#sonarqube-admin#/admin/system)**. It gives you access to detailed information on the state of your SonarQube instance. + +## System Info + +You can browse details about your running instance on this page. + +### Download + +Additionally, if you have a Support contract, you might be asked by a Support representative to send in your System Info, which can be downloaded from the page **[Administration > System](/#sonarqube-admin#/admin/system)** using the **"Download System Info"** button at the top. + +### Server Id +Your server id can be obtained from this page by expanding the **System** section. If you're running a commercial instance, you can also find this value on the License page (**[Administration > Configuration > License Manager](/#sonarqube-admin#/admin/extension/license/app)**) + +## Logs +Server-side logging is controlled by properties set in _$SONARQUBE-HOME/conf/sonar.properties_. + +4 logs files are created: one per SonarQube process. + +### Log Level +The server-side log level can be customized via the `sonar.log.level` property. Supported values are: + +* **`INFO`** - the default +* **`DEBUG`** - for advanced logs. +* **`TRACE`** - show advanced logs and all SQL and Elasticsearch requests. `TRACE` level logging slows down the server environment, and should be used only for tracking web request performance problems. + +### Log Level by Process +The server-side log level can be adjusted more precisely for the 4 processes of SonarQube Server via the following property: + +* **`sonar.log.level.app`** - for the Main process of SonarQube (aka WrapperSimpleApp, the bootstrapper process starting the 3 others) +* **`sonar.log.level.web`** - for the WebServer +* **`sonar.log.level.ce`** - for the ComputeEngineServer +* **`sonar.log.level.es`** - for the SearchServer + +### Log Rotation +To control log rolling, use the `sonar.log.rollingPolicy` + +* **`time:[value]`** - for time-based rotation. For example, use `time:yyyy-MM-dd` for daily rotation, and * `time:yyyy-MM` for monthly rotation. +* **`size:[value]`** - for size-based rotation. For example, `size:10MB`. +* **`none`** - for no rotation. Typically this would be used when logs are handled by an external system like logrotate. + +`sonar.log.maxFiles` is the maximum number of files to keep. This property is ignored if `sonar.log.rollingPolicy=none`. + +### UI Access to Logs and Log Levels + +The System Info page gives you the ability to download your instance's current log files (log files rotate on a regular basis), and to tune the log level via controls at the top of the page. Changes made here are temporary, and last only until the next time the instance is restarted, at which point the level will be reset to the more permanent value set in _$SONARQUBE-HOME/conf/sonar.properties_. Regardless, if you change your log level _from_ `INFO`, but sure to change it back as soon as is practical; log files can get very large very quickly at lower log levels. + +## Total Lines of Code + +### SonarQube 6.7 LTS and newer +The number of Lines of Code (for licensing purposes) in an instance can be found in the **System** section of the System Info page on, and on the License page (**[Administration > Configuration > License Manager](/#sonarqube-admin#/admin/extension/license/app)** in commercial editions. + +If you're on a commercial edition and using Branch or PR analysis, rest assured that only lines from the single largest branch in a project are considered for licensing purposes. The Lines of Code in the rest of the branches are ignored. + +### Versions older than 6.7 +The best approach there is to query the database. The actual query varies based on the version of SonarQube and the database engine. Two queries are provided: + +* one query that counts LOCs across *all* projects +& one query that filters out project branches (i.e. projects analysed with the `sonar.branch` parameter). However, this query is accurate only if projects with branches are also analysed once without sonar.branch. + +**SonarQube LTS v5.6.x** + +[[collapse]] +| ## MySQL +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +|``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| INSTR(p.kee, ':') = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTR(p.kee, 1, LENGTH(p.kee) - INSTR(REVERSE(p.kee), ':')) +| )); +|``` + +[[collapse]] +| ## PostgreSQL 8.0-9.0 +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| Not feasible on this specific database + +[[collapse]] +| ## PostgreSQL 9.1+ +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| POSITION(':' IN p.kee) = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTRING(p.kee, 0, LENGTH(p.kee) - POSITION(':' in REVERSE(p.kee)) + 1) +| )); +| ``` + +[[collapse]] +| ## Oracle +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| INSTR(p.kee, ':') = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTR(p.kee, 0, INSTR(p.kee, ':', -1) - 1) +| )); +| ``` + +[[collapse]] +| ## Microsoft SQL Server (a.k.a MSSQL) +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.project_id = p.id +| inner join project_measures pm on pm.snapshot_id = s.id +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_resource_id is null +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| CHARINDEX(':', p.kee) = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTRING(p.kee, 0, LEN(p.kee) - CHARINDEX(':', REVERSE(p.kee)) + 1 ) +| )); +| ``` + +**SonarQube 6.0-6.6** +[[collapse]] +| ## MySQL +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| INSTR(p.kee, ':') = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTR(p.kee, 1, LENGTH(p.kee) - INSTR(REVERSE(p.kee), ':')) +| )); +| ``` + +[[collapse]] +| ## PostgreSQL 8.0-9.0 +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| Not feasible on this specific database + + +[[collapse]] +| ## PostgreSQL 9.1+ +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = true +| and p.enabled = true +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc' and ( +| POSITION(':' IN p.kee) = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTRING(p.kee, 0, LENGTH(p.kee) - POSITION(':' in REVERSE(p.kee)) + 1) +| )); +| ``` + + +[[collapse]] +| ## Oracle +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| INSTR(p.kee, ':') = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTR(p.kee, 0, INSTR(p.kee, ':', -1) - 1) +| )); +| ``` + + +[[collapse]] +| ## Microsoft SQL Server (a.k.a. MSSQL) +| Global LOCs +| ``` +| select sum(pm.value) as global_loc from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc'; +| ``` +| LOCs without `sonar.branch` +| ``` +| select sum(pm.value) as loc_without_branch from projects p +| inner join snapshots s on s.component_uuid = p.uuid +| inner join project_measures pm on pm.analysis_uuid = s.uuid +| inner join metrics m on m.id=pm.metric_id +| where s.islast = 1 +| and p.enabled = 1 +| and p.qualifier = 'TRK' +| and p.scope = 'PRJ' +| and p.copy_component_uuid is null +| and pm.component_uuid = p.uuid +| and pm.person_id is null +| and m.name='ncloc' +| and ( +| CHARINDEX(':', p.kee) = 0 or not exists( +| select * from projects p_root where p_root.kee = SUBSTRING(p.kee, 0, LEN(p.kee) - CHARINDEX(':', REVERSE(p.kee)) + 1 ) +| )); +| ``` + + diff --git a/server/sonar-docs/src/pages/previous-versions.md b/server/sonar-docs/src/pages/previous-versions.md new file mode 100644 index 00000000000..c4fdac47b89 --- /dev/null +++ b/server/sonar-docs/src/pages/previous-versions.md @@ -0,0 +1,14 @@ +--- +title: Docs for Previous Versions +url: /previous-versions/ +--- + +**Not using the latest and greatest version of SonarQube?** + +Here are the links to the documentation of previous versions: + +* [Documentation for 7.3](https://docs.sonarqube.org/display/SONARQUBE73) +* [Documentation for 7.2](https://docs.sonarqube.org/display/SONARQUBE72) +* [Documentation for 7.1](https://docs.sonarqube.org/display/SONARqube71) +* [Documentation for 7.0](https://docs.sonarqube.org/display/SONARQUBE70) +* [Documentation for 6.7 LTS](https://docs.sonarqube.org/display/SONARQUBE67) diff --git a/server/sonar-docs/src/pages/project-administration/configuring-portfolios-and-applications.md b/server/sonar-docs/src/pages/project-administration/configuring-portfolios-and-applications.md new file mode 100644 index 00000000000..49ce68d6a84 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/configuring-portfolios-and-applications.md @@ -0,0 +1,45 @@ +--- +title: Configuring Portfolios and Applications +url: /project-administration/configuring-portfolios-and-applications/ +--- + +*Portfolios and Applications are available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html).* + +## Table of Contents + +## Permissions +Users with the Create Portfolios or Create Applications permission have access to the creation interfaces from the "+" item in the top menu. + +Global Administrators have access to the overall Portfolio and Application administration interface at **[Administration > Configuration > Portfolios](/#sonarqube-admin#/admin/extension/governance/views_console)**. From this page, Portfolios and Applications can be created and edited. + +Users of either type can edit an individual Portfolio or Application definition from the lower-level **Administration > Edit Definition** interface. + +## Populating Portfolios +Once your Portfolio exists, you can populate it with any mix of projects, Applications, and sub-portfolios. Applications may only be populated with projects. + +## Adding a Sub-portfolio +To add a sub-portfolio, click on “Add Portfolio” at the top of the third column, and choose: + +* **Standard** - This option allows you to create a new sub-Portfolio from scratch. Once created, you can add projects, applications, and more layers of sub-portfolios. +* **Local Reference** - This option allows you to reference an existing Portfolio/Application as a sub-portfolio. Once added, it is not editable here, but must be chosen in the left-most column to be edited. + +## Adding Projects to a Portfolio +To add projects directly to a Portfolio or standard sub-Portfolio first make sure the correct item is selected, then choose the **Project selection mode**: + +* **Manual** – choose the projects individually. +* **Tags** - select one or more project tags. Projects with those tags will automatically be included. +* **Regular Expression** – specify a regular expression and projects with a matching name OR key will be included. +* **All Remaining Projects** – choose this option to add all projects not already included in this Portfolio (directly or via sub-Portfolio). + +[[info]] +|**Project unicity under a portfolio**<br/><br/> +|Projects, applications and sub-portfolios can only appear once in any given hierarchy in order to avoid magnifying their impacts on aggregated ratings. The portfolio configuration interface has some logic to prevent obvious duplications (e.g. manually adding the same project), however in case of more subtle duplications (e.g. due to regex, or other bulk definition), then the calculation of that portfolio will fail with a helpful error message. + +## Populating Applications +Once your Application exists, you can populate it with manually-selected projects. By default, the configuration interface shows the list of projects currently selected for the application. To add additional projects, choose the "Unselected" or "All" filter. + +## Creating Application Branches +Once your Application is populated with projects, you can create application branches by choosing long-lived branches from the application's component projects. This option is available in the Application's **Administration > Edit Definition** interface, or from the global administration interface. + +## Calculation +Applications and Portfolios are queued to be re-calculated after each analysis of an included project. For each relevant Portfolio and Application, a “Background Task” is created, and you can follow the progress on each in the **[Administration > Projects > Background Tasks](/#sonarqube-admin#/admin/background_tasks)** by looking at the logs available for each item. diff --git a/server/sonar-docs/src/pages/project-administration/managing-project-history.md b/server/sonar-docs/src/pages/project-administration/managing-project-history.md new file mode 100644 index 00000000000..f3315428c65 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/managing-project-history.md @@ -0,0 +1,25 @@ +--- +title: Managing Project History +url: /project-administration/managing-project-history/ +--- + +One of the most powerful features of {instance} is that it shows you not just your project health today, but how it has changed over time. It does that by selectively keeping data from previous analyses (see [Housekeeping](/instance-administration/housekeeping/)). It doesn't keep all previous analyses - that would bloat the database. Similarly, for the analyses it does keep, {instance} doesn't keep all the data. Once a project snapshot moves from the "Last analysis" (i.e. the most recent) to being part of the project's history, data below the project level is purged - again to keep from bloating the database. + +Typically these aren't things you need to even think about; {instance} just handles them for you. But occasionally you may need to remove a bad snapshot from a project's history or change the housekeeping algorithms. + +## Managing History +Occasionally, you may need to manually delete a project snapshot, whether because the wrong quality profile was used, or because there was a problem with analysis, and so on. Note that the most recent snapshot (labeled "Last snapshot") can never be deleted. + +[[warning]] +|**About deleting snapshots**<br/><br/> +|Deleting a snapshot is a 2-step process:<br/><br/> +|* The snapshot must first be removed from the project history by clicking on Delete snapshot. It |won't be displayed anymore on this History page but will still be present in the database. +|* The snapshot is actually deleted during the next project analysis. + +At project level, from the front page **Activity** list, choose **Show More** to see the full activity list. + +For every snapshot, it is possible to manually: + +* Add, rename or remove a version +* Add, rename or remove an event +* Delete the snapshot diff --git a/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md b/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md new file mode 100644 index 00000000000..e3beaaf6130 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/narrowing-the-focus.md @@ -0,0 +1,142 @@ +--- +title: Narrowing the Focus +url: /project-administration/narrowing-the-focus/ +--- + +## Table of Contents + +If {instance}'s results aren't relevant, developers will push back on using it. That's why precisely configuring what to analyze for each project is a very important step. Doing so allows you to remove noise, like the issues and duplications marked on generated code, or the issues from rules that aren't relevant for certain types of objects. + +{instance} gives you several options for configuring exactly what will be analyzed. You can + +* completely ignore some files or directories +* exclude files/directories from Issues detection (specific rules or all of them) but analyze all other aspects +* exclude files/directories from Duplications detection but analyze all other aspects +* exclude files/directories from Coverage calculations but analyze all other aspects + +You can make these changes globally or at a project level. At both levels, the navigation path is the same: **Administration > General Settings > Analysis Scope**. + +## Ignore Files +We recommend that you exclude generated code, source code from libraries, etc. There are four different ways to narrow your analysis to the source code that will be relevant to the development team. You can combine them all together to tune your analysis scope. + +### Source Directories +Set the [sonar.sources](/analysis/analysis-parameters/) property to limit the scope of the analysis to certain directories. + +### File Suffixes +Most language plugins offer a way to restrict the scope of analysis to files matching a set of extensions. Go to **Administration > General Settings > [Language]** to set the File suffixes property. + +### Choosing Files +To specify which files are are and are not included in an analysis go to **Administration > General Settings > Analysis Scope > Files**. + +Use exclusion to analyze everything but the specified files: + +* sonar.exclusions - to exclude source code files +* sonar.test.exclusions - to exclude unit test files + +Use inclusion to analyzes only the specified files: + +* sonar.inclusions +* sonar.test.inclusions + +You can set these properties at the project and global levels. + +See the Patterns section for more details on the syntax to use in these inputs. + +## Ignore Issues +You can have {instance} ignore issues on certain components and against certain coding rules. Go to **Administration > General Settings > Analysis Scope > Issues**. + +Note that the properties below can only be set through the web interface because they are multi-valued. + +### Ignore Issues on Files +You can ignore all issues on files that contain a block of code matching a given regular expression. + +Example: +* *Ignore all issues in files containing "@javax.annotation.Generated"* +`@javax\.annotation\.Generated` + +### Ignore Issues in Blocks +You can ignore all issues on specific blocks of code, while continuing to scan and mark issues on the remainder of the file. Blocks to be ignored are delimited by start and end strings which can be specified by regular expressions (or plain strings). + +Notes: + +* If the first regular expression is found but not the second one, the end of the file is considered to be the end of the block. +* Regular expressions are not matched on a multi-line basis. + +### Ignore Issues on Multiple Criteria +You can ignore issues on certain components and for certain coding rules. To list a specific rule, use the fully qualified rule ID. + +[[info]] +|  You can find the fully qualified rule ID on the Rule definition. + +Examples: + +* *Ignore all issues on all files* +KEY = `*` +PATH = `**/*` +* *Ignore all issues on COBOL program "bank/ZTR00021.cbl"* +KEY = `*` +PATH = `bank/ZTR00021.cbl` +* *Ignore all issues on classes located directly in the Java package "com.foo", but not in its sub-packages* +KEY = `*` +PATH = `com/foo/*` +* *Ignore all issues against coding rule "cpp:Union" on files in the directory "object" and its sub-directories* +KEY = `cpp:Union` +PATH = `object/**/*` + +### Restrict Scope of Coding Rules + +You can restrict the application of a rule to only certain components, ignoring all others. + +Examples: + +* *Only check the rule "Magic Number" on "Bean" objects and not on anything else* +KEY = `checkstyle:com.puppycrawl.tools.checkstyle.checks.coding.MagicNumberCheck` +PATH = `**/*Bean.java` +* *Only check the rule "Prevent GO TO statement from transferring control outside current module on COBOL programs" located in the directories "bank/creditcard" and "bank/bankcard". This requires two criteria to define it:* +KEY #1 = `cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck` +PATH #1 = `bank/creditcard/**/*` +KEY #2 = `cobol:COBOL.GotoTransferControlOutsideCurrentModuleCheck` +PATH #2 = `bank/bankcard/**/*` + +## Ignore Duplications + +You can prevent some files from being checked for duplications. + +To do so, go to **Administration > General Settings > Analysis Scope > Duplications** and set the *Duplication Exclusions* property. See the Patterns section for more details on the syntax. + +## Ignore Code Coverage + +You can prevent some files from being taken into account for code coverage by unit tests. + +To do so, go to **Administration > General Settings > Analysis Scope > Code Coverage** and set the *Coverage Exclusions* property. See the Patterns section for more details on the syntax. + +## Patterns + +Paths are relative to the project base directory. + +The following wildcards can be used: + +\* zero or more characters +\*\* zero or more directories +\? a single character + +Relative paths are based on the fully qualified name of the component. + +Examples: + +`# Exclude all classes ending by "Bean"` +`# Matches org/sonar.api/MyBean.java, org/sonar/util/MyOtherBean.java, org/sonar/util/MyDTO.java, etc.` +`sonar.exclusions=**/*Bean.java,**/*DTO.java` + +`# Exclude all classes in the "src/main/java/org/sonar" directory` +`# Matches src/main/java/org/sonar/MyClass.java, src/main/java/org/sonar/MyOtherClass.java` +`# But does not match src/main/java/org/sonar/util/MyClassUtil.java` +`sonar.exclusions=src/main/java/org/sonar/*` + +`# Exclude all COBOL programs in the "bank" directory and its sub-directories` +`# Matches bank/ZTR00021.cbl, bank/data/CBR00354.cbl, bank/data/REM012345.cob` +`sonar.exclusions=bank/**/*` + +`# Exclude all COBOL programs in the "bank" directory and its sub-directories whose extension is .cbl` +`# Matches bank/ZTR00021.cbl, bank/data/CBR00354.cbl` +`sonar.exclusions=bank/**/*.cbl` diff --git a/server/sonar-docs/src/pages/project-administration/portfolio-pdf-configuration.md b/server/sonar-docs/src/pages/project-administration/portfolio-pdf-configuration.md new file mode 100644 index 00000000000..ab32f968584 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/portfolio-pdf-configuration.md @@ -0,0 +1,18 @@ +--- +title: Portfolio PDF Configuration +url: /project-administration/portfolio-pdf-configuration/ +--- + +*Portfolio PDFs are available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html).* + +A user with administrative rights on a portfolio can configure email distribution of the PDF. From a Portfolio Home Page go to **Administration > Executive Report**. + +###Frequency +You can tune the email frequency of the PDF Report. The possible values are: + +* Daily: report is sent during the first portfolio calculation of the day (if any) +* Weekly: report is sent during the first portfolio calculation of the week (if any) from Monday +* Monthly (default): report is sent during the first portfolio calculation of the month (if any), starting from the first day of the current month + +###Other Recipients +If people without SonarQube accounts want to receive the PDF, you can feed the administrative "Other Recipients" field with their email addresses. diff --git a/server/sonar-docs/src/pages/project-administration/project-existence.md b/server/sonar-docs/src/pages/project-administration/project-existence.md new file mode 100644 index 00000000000..c8b2e5a5988 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/project-existence.md @@ -0,0 +1,34 @@ +--- +title: Project Existence +url: /project-administration/project-existence/ +--- + +Typically, projects are created during their first analysis and never deleted (because old software never dies). For atypical situations, there is the page at **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management/)**, which allows you to manage project existence. + +## How do I provision a project before its first analysis? +Provisioning a project allows you to declare and configure it (define permissions, set quality profiles, etc.) before running the first analysis. To be able to provision projects, you have to be logged in and be granted the Provision Projects permission. + +To provision a new project, go to **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management/)** and click on **Create Project**. The only required information is the key and the name of your project. + +Once the project is provisioned, you can configure it (define permissions, set quality profiles, etc.), and when you're finished with the configuration, you can simply run the project's first analysis. + +You can also provision and configure projects using the Web API. + +## How do I find provisioned projects (that haven't been analyzed yet)? +The **[Projects Management](/#sonarqube-admin#/admin/projects_management/)** search interface includes a toggle to allow you to narrow your results on this page to only projects that have never been analyzed. From there you can deal with them on this page as a set, or click through to the individual project homepages for individual attention and administration. + +## How do I lock down permissions on a project? (Private vs Public) +By default, any newly created project will be considered "Public". It means every SonarQube user, authenticated or not, will be able to: + +* **Browse**: Access a project, browse its measures, issues and perform some issue edits (confirm/resolve/reopen, assignment, comment). +* **See Source Code**: View the project's source code. + +If you want to be sure only a limited list of Groups and Users can see the project, you need to mark it Private. Once a project is private you will be able to define which Groups and Users can **Browse** the project or **See Source Code**. + +If you want all newly created projects to be considered "Private", you can change the default visibility in **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management/)**. + +## How do I delete projects? +A project may be deleted individually from the Administration page of the project. See Project Settings for more details. To delete projects in bulk, use **[Administration > Projects > Management](/#sonarqube-admin#/admin/projects_management/)**. Here you can select the projects to delete. A deleted project is gone for good, there is no way to undo this action. + +## How do I find projects that are no longer analyzed? +The **[Projects Management](/#sonarqube-admin#/admin/projects_management/)** search interface includes a date picker to help you find all projects last analyzed before your specified date. From there you can deal with them on this page as a set, or click through to the individual project homepages for individual attention and administration. diff --git a/server/sonar-docs/src/pages/project-administration/project-settings.md b/server/sonar-docs/src/pages/project-administration/project-settings.md new file mode 100644 index 00000000000..532ffdeafa1 --- /dev/null +++ b/server/sonar-docs/src/pages/project-administration/project-settings.md @@ -0,0 +1,63 @@ +--- +title: Project Settings +url: /project-administration/project-settings/ +--- + +## Table of Contents + +## Tags + +Project tags allow you to categorize and group projects for easier selection on the **Projects** page. Project tags can be administered from the project home page. Administrators will see a dropdown menu indicator next to the project's list of current tags (or next to the "No tags" indicator). If the tag you want isn't visible in the dropdown, use the built in "search" input to find what you're looking for or create it on the fly. + +## Administration Items + +Project administration is accessible through the **Administration** menu of each project. + +Only project administrators can access project's settings (see [Authorization](/instance-administration/security/)). + +### Adding a Project + +A project is automatically added at its first analysis. Note that you can also [provision projects](/project-administration/project-existence/). + +### Analysis Report Processing + +A project-level Background Tasks page is available at **Administration > Background Tasks** to allow project administrators to check their projects' processing. It offers analysis report details and logs. + +### Deleting a Project + +You can delete a project through **Administration > Deletion**: + +Note also that projects can also be deleted in bulk. + +### Setting the New Code Period + +The new code period can be set on a per-project basis through **Administration > General Settings > New Code > New Code Period**. The default value is `previous_version`, which is most appropriate value for projects that version/release regularly. For other projects, a time period such as 30 days (enter "30", the "days" part is understood) may be more appropriate. + +Note that this can be set at the global level as well. + +### Updating Project Key + +The project key can be updated (without losing the history on the project) at **Administration > Update Key**. + +The new key must contain at least one non-digit character. Allowed characters are: 'a' through 'z', 'A' through 'Z', '-' (dash), '\_' (underscore), '.' (dot), ':' (colon) and digits '0' to '9'. + +### Default Issue Assignee + +When new issues are created during an analysis, they are assigned to the last committer where the issue was raised. When it is not possible to identify the last committer, issues can be assigned to a default assignee, at **Administration > General Settings > Issues**. + +### Setting Quality Gate and Quality Profiles + +Project administrators can select which ... + +* Quality profiles (go to **Administration > Quality Profiles**) +* Quality gate (go to **Administration > Quality Gate**) + +... to use on their project. + +### Setting Exclusions + +See [Narrowing the Focus](/project-administration/narrowing-the-focus/). + +### Customizing Links + +On top of standard links which may only be set as [Analysis Parameters](/analysis/analysis-parameters/), additional custom links can be added through the web interface (under **Administration > Links**). Those links will then be displayed in the [Project Page](/user-guide/project-page/). diff --git a/server/sonar-docs/src/pages/project-administration/webhooks.md b/server/sonar-docs/src/pages/project-administration/webhooks.md index 96050491720..43e9794eae9 100644 --- a/server/sonar-docs/src/pages/project-administration/webhooks.md +++ b/server/sonar-docs/src/pages/project-administration/webhooks.md @@ -101,7 +101,7 @@ The Payload is a JSON document which includes: A basic authentication mechanism is supported by providing user/password in the URL of the Webhook such as `https://myLogin:myPassword@my_server/foo`. -If you provide additional properties to your SonarQube Scanner using the pattern `sonar.analysis.*`, these properties will be automatically added to the section "properties" of the payload. +If you provide additional properties to your SonarScanner using the pattern `sonar.analysis.*`, these properties will be automatically added to the section "properties" of the payload. For example these additional parameters: diff --git a/server/sonar-docs/src/pages/requirements/benchmark.md b/server/sonar-docs/src/pages/requirements/benchmark.md new file mode 100644 index 00000000000..108b823bf51 --- /dev/null +++ b/server/sonar-docs/src/pages/requirements/benchmark.md @@ -0,0 +1,63 @@ +--- +title: Benchmark +url: /requirements/benchmark/ +--- +## Context +The following figures have been produced on common hardware available in most mid-size companies : + +| App ESXi Server Configuration | DB ESXi Server Configuration | +| ------------------------------------------------------- | ------------------------------------------------------- | +| 2* Intel(R) Xeon(R) CPU E5-2650 v2 @ 2.60GHz (32 VCPUs) | 2* Intel(R) Xeon(R) CPU E5-2650 v2 @ 2.60GHz (32 VCPUs) | +| 128GB RAM | 128GB RAM | +| 1.9 TB volume (RAID5 of 8 Hard Drives of 300GB SAS 15K) | 1.9TB volume (RAID5 of 8 hard drives of 300GB SAS 15k) | +| 2*1 GB NICs | 2*1 GB NICs | +| ESXi 6.0 | ESXi 6.0 | + +We created 2 VMs, one for SonarQube Server, one for SonarQube Database inside two ESXi 6.0 Servers : + +| App VM Server Configuration | DB VM Server Configuration | +| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | +| 8 VCPUs | 4 VCPUs | +| 16GB RAM | 8GB RAM | +| 20 GB storage for system + 200 GB storage for data (LVM) (RAID5 of 8 hard drives of 300GB SAS 15k) | 20 GB storage for system + 200 GB storage for data (LVM) | +| 1GB NIC | 1GB NIC | +| CentOS 7 64bits | CentOS 7 64bits | +| | MySQL 5.6.27 (Oracle Community Edition) | + +## Goals +From SonarQube 5.2+ Source Lines are no longer indexed by Elasticsearch, so quantity of code under analysis analyze will not affect the performance of the SearchServer. + +By running this benchmark, we wanted to validate the number of Millions of Issues a given hardware hosting SonarQube can support. +* can SonarQube digest millions of Issues and how many time does it take? +* can we still use the UI of SonarQube with these millions of Issues? + +## Results +### Indexation Throughput +Issues Indexation done by the Search Server is not linear: + +| Millions of issues | Indexation time (hours) | +| ------------------ | ----------------------- | +| 25 | 1 | +| 60 | 2-3 | +| 100 | 6-7 | + +### RAM to Allocate to Elasticsearch +RAM to allocate to ElastSearch is linear according to the number of Issues: + +| Millions of issues | SearchServer RAM in GB | +| ------------------ | ---------------------- | +| 25 | 4 | +| 60 | 7 | +| 100 | 12 | + +*Elasticsearch's RAM can be configured in _$SONARQUBE_HOME/conf/sonar.properties_ using: `sonar.search.javaOpts*` + +### CPU Allocation +With SonarQube 5.2+, Elasticsearch is configured to use 5 [ElasticSearch Primary Shards](https://www.elastic.co/guide/en/elasticsearch/reference/2.0/glossary.html#glossary-primary-shard). This allows SonarQube to handle by default 50 Millions of Issues on a server having at least 4 CPU Cores dedicated to the SearchServer. + +| Millions of issues | \#Shards | \# Cores | | +| ------------------ | -------- | -------- | --------------------- | +| 50 | 5 | 4 | default configuration | +| 30 | 3 | 2 | | + +Shard configuration must be adjusted according to the quantity of Issues you have to manage. The rule is to have 1 Shard by block of 10M Issues. So for 100M Issues, you need 10 Shards, so at least 9 Cores. diff --git a/server/sonar-docs/src/pages/requirements/hardware-recommendations.md b/server/sonar-docs/src/pages/requirements/hardware-recommendations.md new file mode 100644 index 00000000000..8e0009d9d68 --- /dev/null +++ b/server/sonar-docs/src/pages/requirements/hardware-recommendations.md @@ -0,0 +1,45 @@ +--- +title: Hardware Recommendations +url: /requirements/hardware-recommendations/ +--- +## Database +We recommend that for large instances, the database used by SonarQube is hosted on a machine which is physically separate from SonarQube Server but close to it on the network. + +### Oracle +In case your SonarQube Server is running on Linux and you are using Oracle, the Oracle JDBC Driver may be blocked due to /dev/random. See [this Oracle article](http://www.usn-it.de/index.php/2009/02/20/oracle-11g-jdbc-driver-hangs-blocked-by-devrandom-entropy-pool-empty/) for more details about this problem. + + To avoid it, you may want to add this JVM parameter to your SonarQube Web Server (`sonar.web.javaOpts`) configuration : + ``` + -Djava.security.egd=file:///dev/urandom + ``` + + ## Elasticsearch (aka ES) +* [Elasticsearch](https://www.elastic.co/) is used by SonarQube in the background in the SearchServer process. To ensure good performance of your SonarQube, you need to follow these recommendations that are linked to ES usage. + +## JVM +* It is recommended to set the min and max memory to the same value to prevent the heap from resizing at runtime, a very costly process. See -Xms and -Xmx of property `sonar.search.javaOpts`. + +## Disk +* Disk can easily become the bottleneck of ES. If you can afford SSDs, they are by far superior to any spinning media. SSD-backed nodes see boosts in both query and indexing performance. If you use spinning media, try to obtain the fastest disks possible (high performance server disks 15k RPM drives). +* Make sure to increase the number of open files descriptors on the machine (or for the user running SonarQube server). Setting it to 32k or even 64k is recommended. See [this ElasticSearch article](https://www.elastic.co/guide/en/elasticsearch/reference/current/file-descriptors.html). +* Using RAID 0 is an effective way to increase disk speed, for both spinning disks and SSD. There is no need to use mirroring or parity variants of RAID because of Elasticsearch replicas and database primary storage. +8 Do not use remote-mounted storage, such as NFS, SMB/CIFS or network-attached storages (NAS). They are often slower, display larger latencies with a wider deviation in average latency, and are a single point of failure. + +**Advanced** +* If you are using SSD, make sure your OS I/O Scheduler is configured correctly. When you write data to disk, the I/O Scheduler decides when that data is actually sent to the disk. The default under most *nix distributions is a scheduler called cfq (Completely Fair Queuing). This scheduler allocates "time slices" to each process, and then optimizes the delivery of these various queues to the disk. It is optimized for spinning media: the nature of rotating platters means it is more efficient to write data to disk based on physical layout. This is very inefficient for SSD, however, since there are no spinning platters involved. Instead, deadline or noop should be used instead. The deadline scheduler optimizes based on how long writes have been pending, while noop is just a simple FIFO queue. This simple change can have dramatic impacts. +* If SQ home directory is located on a slow disk, then the property `sonar.path.data` can be used to move data to a faster disk (RAID 0 local SSD for instance). + +## Memory +* Machine available memory for OS must be at least the Elasticsearch heap size. The reason is that Lucene (used by ES) is designed to leverage the underlying OS for caching in-memory data structures. That means that by default OS must have at least 1Gb of available memory. +* Don't allocate more than 32Gb. See [this ElasticSearch article](http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/heap-sizing.html) for more details. + +**Advanced** +* Elasticsearch uses a hybrid mmapfs / niofs directory by default to store its indices. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions. On Linux, you can increase the limits by running the following command as root : +``` +sysctl -w vm.max_map_count=262144 +``` +To set this value permanently, update the `vm.max_map_count` setting in `/etc/sysctl.conf`. + +## CPU +* If you need to choose between faster CPUs or more cores, then choose more cores. The extra concurrency that multiple cores offers will far outweigh a slightly faster clock-speed. +* By nature data are distributed on multiples nodes, so execution time depends on the slowest node. It's better to have multiple medium boxes than one fast + one slow. diff --git a/server/sonar-docs/src/pages/requirements/requirements.md b/server/sonar-docs/src/pages/requirements/requirements.md new file mode 100644 index 00000000000..a069109969e --- /dev/null +++ b/server/sonar-docs/src/pages/requirements/requirements.md @@ -0,0 +1,142 @@ +--- +title: Prerequisites and Overview +url: /requirements/requirements/ +--- +## Table of Contents + +## Prerequisite +The only prerequisite for running SonarQube is to have Java (Oracle JRE 8 or OpenJDK 8) installed on your machine. + + **Note:** _On Mac OS X it is highly recommended to install Oracle JDK 8 instead of the corresponding Oracle JRE since the JRE installation does not fully set up your Java environment properly. See [this post](http://stackoverflow.com/questions/15624667/mac-osx-java-terminal-version-incorrect) for more information._ + +## 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. +2. The amount of disk space you need will depend on how much code you analyze with SonarQube. As an example, [SonarCloud](https://sonarcloud.io) the public instance of SonarQube, has more than 350 million lines of code under analysis with 5 years of history. SonarCloud is currently running on clustered [Amazon EC2 m5.large](http://aws.amazon.com/ec2/instance-types/) instances with allocations of 50 Gb of drive space per node. It handles 19,000+ projects with roughly 14M open issues. SonarCloud runs on PostgreSQL 9.5 and it is using about 250Gb of disk space for the database. +3. SonarQube must be installed on hard drives that have excellent read & write performance. Most importantly, the "data" folder houses the Elasticsearch indices on which a huge amount of I/O will be done when the server is up and running. Great read & write hard drive performance will therefore have a great impact on the overall SonarQube server performance. + +### Enterprise Hardware Recommendations +For large teams or Enterprise-scale installations of SonarQube, additional hardware is required. At the Enterprise level, monitoring your SonarQube instance/instance-administration/java-process-memory is essential and should guide further hardware upgrades as your instance grows. A starting configuration should include at least: + +* 8 cores, to allow the main SonarQube platform to run with multiple Compute Engine workers +* 16GB of RAM +For additional requirements and recommendations relating to database and ElasticSearch, see Hardware Recommendations/requirements/hardware-recommendations. + +## Supported Platforms +### Java +The SonarQube Java analyzer is able to analyze any kind of Java source files regardless of the version of Java they comply to. But SonarQube analysis and the SonarQube Server require specific versions of the JVM. + +We recommend using the Critical Path Update (CPU) releases. + +| Java | | +| -------------- | ------------------------ | +| Oracle JRE |  9 | +| |  8 | +| |  7 | +| Open JDK |  9 | +| |  8 | +| |  7 | +| IBM JRE |  | +| GCJ |  | +| Oracle JRockit |  | + +| Database | | +| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [PostgreSQL](http://www.postgresql.org/) |  9.3 - 9.6 | +| |  10 | +| |  Must be configured to use UTF-8 charset | +| [Microsoft SQL Server](http://www.microsoft.com/sqlserver/) |  2012 (MSSQL Server 11.0) | +| |  2014 (MSSQL Server 12.0) with bundled Microsoft JDBC driver. Express Edition is supported. | +| |  2016 (MSSQL Server 13.0) with bundled Microsoft JDBC driver. Express Edition is supported. | +| |  Collation must be case-sensitive (CS) and accent-sensitive (AS) (example: Latin1_General_CS_AS) | +| |  READ_COMMITTED_SNAPSHOT must be set on the SonarQube database to avoid potential deadlocks under heavy load | +| |  Both Windows authentication (“Integrated Security”) and SQL Server authentication are supported. See the Microsoft SQL Server section in Installing/installation/installing-the-server page for instructions on configuring authentication. | +| [Oracle] (http://www.oracle.com/database/) |  10G | +| |  11G with [Oracle 11.2.x](http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-112010-090769.html) drivers | +| |  12C with [Oracle 12.2.x](http://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html) drivers | +| |  XE Editions are supported +| |  Must be configured to use a UTF8-family charset (see NLS_CHARACTERSET) | +| |  The driver ojdbc14.jar is not supported | +| |  Only the thin mode is supported, not OCI | +| [MySQL](http://www.mysql.com/) | Not recommended for large instances | +| |  5.6 | +| |  5.7 | +| |  Must be configured to use UTF8 charset and a case-sensitive (CS) collation | +| |  Only InnoDB storage engine is supported, but not MyISAM | +| | Only the bundled mysql-connector-java jar is supported | + +### Web Browser +To get the full experience SonarQube has to offer, you must enable JavaScript in your browser. + +| | | +| --------------------------- | --------------------------------------- | +| Microsoft Internet Explorer |  IE 9 | +| |  IE 10 | +| |  IE 11 | +| Microsoft Edge |  Latest | +| Mozilla Firefox |  Latest | +| Google Chrome |  Latest | +| Opera |  Not tested | +| Safari |  Latest | + +## Platform notes +### Linux +If you're running on Linux, you must ensure that: + +* `vm.max_map_count` is greater or equals to 262144 +* `fs.file-max` is greater or equals to 65536 +* the user running SonarQube can open at least 65536 file descriptors +* the user running SonarQube can open at least 2048 threads + +You can see the values with the following commands: +``` +sysctl vm.max_map_count +sysctl fs.file-max +ulimit -n +ulimit -u +``` + +You can set them dynamically for the current session by running the following commands as `root`: +``` +sysctl -w vm.max_map_count=262144 +sysctl -w fs.file-max=65536 +ulimit -n 65536 +ulimit -u 2048 +``` + +To set these values more permanently, you must update either _/etc/sysctl.d/99-sonarqube.conf_ (or _/etc/sysctl.conf_ as you wish) to reflect these values. + +If the user running SonarQube (`sonarqube` in this example) does not have the permission to have at least 65536 open descriptors, you must insert this line in _/etc/security/limits.d/99-sonarqube.conf_ (or _/etc/security/limits.conf_ as you wish): +``` +sonarqube - nofile 65536 +sonarqube - nproc 2048 +``` + +You can get more detail in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/system-config.html). + +If you are using `systemd` to start SonarQube, you must specify those limits inside your unit file in the section \[service\] : +``` +[Service] +... +LimitNOFILE=65536 +LimitNPROC=2048 +... +``` + +### seccomp filter +By default, Elasticsearch uses [seccomp filter](https://www.kernel.org/doc/Documentation/prctl/seccomp_filter.txt). On most distribution this feature is activated in the kernel, however on distributions like Red Hat Linux 6 this feature is deactivated. If you are using a distribution without this feature and you cannot upgrade to a newer version with seccomp activated, you have to explicitly deactivate this security layer by updating `sonar.search.javaAdditionalOpts` in _$SONARQUBE_HOME/conf/sonar.properties_: +``` +sonar.search.javaAdditionalOpts=-Dbootstrap.system_call_filter=false +``` + +You can check if seccomp is available on your kernel with: +``` +$ grep SECCOMP /boot/config-$(uname -r) +``` + +If your kernel has seccomp, you will see: +``` +CONFIG_HAVE_ARCH_SECCOMP_FILTER=y +CONFIG_SECCOMP_FILTER=y +CONFIG_SECCOMP=y +``` +For more detail, see the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/5.6/breaking-changes-5.6.html). diff --git a/server/sonar-docs/src/pages/setup/get-started-2-minutes.md b/server/sonar-docs/src/pages/setup/get-started-2-minutes.md new file mode 100644 index 00000000000..f6004324267 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/get-started-2-minutes.md @@ -0,0 +1,23 @@ +--- +title: Get Started in Two Minutes Guide +url: /setup/get-started-2-minutes/ +--- + +1. [Download](https://www.sonarqube.org/downloads/) the SonarQube Community Edition + +2. Unzip it, let's say in _C:\sonarqube_ or _/etc/sonarqube_ + +3. Start the SonarQube Server: + +``` +# On Windows, execute: +C:\sonarqube\bin\windows-x86-xx\StartSonar.bat + +# On other operating systems, execute: +/etc/sonarqube/bin/[OS]/sonar.sh console +``` + +4. Log in to [http://localhost:9000](http://localhost:9000) with System Administrator credentials (admin/admin) and follow the embedded tutorial to analyze your first project. + + + This play instance is suitable for demonstration purpose, when you are ready to move to production, take some time to read the [Install the Server](/setup/install-server/) documentation. diff --git a/server/sonar-docs/src/pages/setup/install-cluster.md b/server/sonar-docs/src/pages/setup/install-cluster.md new file mode 100644 index 00000000000..c1c5d0137a2 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/install-cluster.md @@ -0,0 +1,141 @@ +--- +title: Install the Server as a Cluster +url: /setup/install-cluster/ +--- + +<!-- sonarqube --> + +_Running SonarQube as a Cluster is only possible with a [Data Center Edition](https://www.sonarsource.com/plans-and-pricing/data-center/)_. + +The Data Center Edition allows SonarQube to run in a clustered configuration to make it resilient to failures. + +## Requirements + +### App Servers + +You need five servers dedicated to SonarQube. Servers can be VMs, it's not necessary to have physical machines. + +Servers must be co-located (geographical redundancy is not supported). + +You can find the operating system requirements for servers in the [Requirements](/requirements/requirements/) page. + + +### Database Server + +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. + +### 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: + +- 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 + +### License +You need a dedicated license to activate the DC Edition. If you don't have it yet, please contact the SonarSource Sales Team. + +### 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. + +## Cluster Topology +There are two types of nodes: + +- 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 + +_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._ + +Here is a schema for the supported topology: + + + +### Machines + +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. + +- 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 + +## Installation Details + +**Prepare your personalized SonarQube package:** + +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 + +**Deploy your SonarQube package on the 4 other nodes:** + +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. + +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 + + +## Configuration + +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. + +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 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: + +**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= +``` + +**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= +``` + +**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. + +Once this configuration is done, take a break and a coffee, then you can [Operate your Cluster](/setup/operate-cluster/). + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/setup/install-plugin.md b/server/sonar-docs/src/pages/setup/install-plugin.md new file mode 100644 index 00000000000..d48b7989e79 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/install-plugin.md @@ -0,0 +1,35 @@ +--- +title: Install a Plugin +url: /setup/install-plugin/ +--- + +<!-- sonarqube --> +There are two options to install a plugin into SonarQube: + +- Marketplace - Installs plugins automatically, from the SonarQube UI. +- Manual Installation - You'll use this method if your SonarQube instance doesn't have access to the Internet. + +## Marketplace + +If you have access to the Internet and you are connected with a SonarQube user having the Global Permission "Administer System", you can go to Administration > Marketplace. + +- Find the plugin you want to install +- Click on Install and wait for the download to be processed + +Once download is complete, a "Restart" button will be available to restart your instance. + +See [Marketplace](/instance-administration/marketplace/) for more details on how to configure your SonarQube Server to connect to the Internet. + +## Manual Installation + +In the page dedicated to the plugin you want to install (ex: for Python: SonarPython, click on the "Download" link of the version compatible with your SonarQube version. + +Put the downloaded jar in `$SONARQUBE_HOME/extensions/plugins`, removing any previous versions of the same plugins. + +Once done, you will need to restart your SonarQube Server. + +### License + +If you installed a Commercial Edition, you will need to set the License Key in Administration > Configuration > License Manager before being able to use it. + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/setup/install-server.md b/server/sonar-docs/src/pages/setup/install-server.md new file mode 100644 index 00000000000..013b54dd835 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/install-server.md @@ -0,0 +1,198 @@ +--- +title: Install the Server +url: /setup/install-server/ +--- + + +## Installing the Database + +Several [database engines](/requirements/requirements/) are supported. Be sure to follow the requirements listed for your database, they are real requirements not recommendations. + +Create an empty schema and a `sonarqube` user. Grant this `sonarqube` user permissions to `create`, `update`, and `delete` objects for this schema. + +### Microsoft SQL Server + + Collation **MUST** be case-sensitive (CS) and accent-sensitive (AS). + + `READ_COMMITED_SNAPSHOT` **MUST** be set on the SonarQube database. + +MS SQL database's shared lock strategy may impact SonarQube runtime. Making sure that `is_read_committed_snapshot_on` is set to `true` to prevent SonarQube from facing potential deadlocks under heavy loads. + +Example of query to check `is_read_committed_snapshot_on`: +``` +SELECT is_read_committed_snapshot_on FROM sys.databases WHERE name='YourSonarQubeDatabase'; +``` +Example of query to update `is_read_committed_snapshot_on`: +``` +ALTER DATABASE YourSonarQubeDatabase SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE; +``` + +If you want to use integrated security, you have to download the Microsoft SQL JDBC Driver 6.2 package from [https://www.microsoft.com/en-us/download/details.aspx?id=55539](https://www.microsoft.com/en-us/download/details.aspx?id=55539) and copy `sqljdbc_auth.dll` to any folder in your path. You should match the 32-bit or 64-bit version of the dll to the architecture of your server machine. If you are running the SonarQube as a windows service and want to use Integrated security, please make sure the Windows account under which the service is running has permission to connect your SQL Server. The account should have `db_owner` database role membership. Otherwise, if you are running the SonarQube server from a command prompt and want to use Integrated security, the user under which the command prompt is running should have `db_owner` database role membership. Also ensure that `sonar.jdbc.username` or `sonar.jdbc.password properties` are commented out, otherwise SonarQube will use SQL Authentication. + +``` +sonar.jdbc.url=jdbc:sqlserver://localhost;databaseName=sonar;integratedSecurity=true +``` + +If you want to use SQL Authentication, use the following connection string. Also ensure that `sonar.jdbc.username` and `sonar.jdbc.password` are set appropriately. + +``` +sonar.jdbc.url=jdbc:sqlserver://localhost;databaseName=sonar +sonar.jdbc.username=sonarqube +sonar.jdbc.password=mypassword +``` + +### Oracle + +If there are two SonarQube schemas on the same Oracle instance, especially if they are for two different versions, SonarQube gets confused and picks the first it finds. To avoid this issue: + +- Either privileges associated to the SonarQube Oracle user should be decreased +- Or a trigger should be defined on the Oracle side to automatically alter the SonarQube Oracle user session when establishing a new connection: + +[[warning]] +| Oracle JDBC driver versions 12.1.0.1 and 12.1.0.2 have major bugs, and are not recommended for use with the SonarQube ([see more details](https://groups.google.com/forum/#!msg/sonarqube/Ahqt1iarqJg/u0BVRJZnBQAJ)). + +### PostgreSQL + +If you want to use a custom schema and not the default "public" one, the PostgreSQL `search_path` property must be set: + +``` +ALTER USER mySonarUser SET search_path to mySonarQubeSchema +``` + +### MySQL (not recommended) + +[[warning]] +| MySQL is not supported for [Data Center Edition](https://www.sonarsource.com/plans-and-pricing/data-center/). + +There are two well-known engines that can be used in MySQL: MyISAM and InnoDB. MyISAM is the oldest of the two engines and is being progressively replaced by InnoDB. InnoDB is clearly faster and scales better with SonarQube as the number of projects under quality control increases. If you were an early adopter of SonarQube, you probably have a series of tables that are still using MyISAM. To improve performance, you should change the engine for all tables to InnoDB. + +Once all SonarQube tables are using the InnoDB engine, the first thing to do is allocate a maximum amount of RAM to your MySQL instance with the `innodb_buffer_pool_size` parameter and give at least 15Mb to the `query_cache_size` parameter. Read this article about [InnoDB Performance Optimization Basics](https://www.percona.com/blog/2007/11/01/innodb-performance-optimization-basics/) for more information. + +## Installing the Web Server + +First, check the [requirements](/requirements/requirements/). + +Then download and unzip the [distribution](http://www.sonarqube.org/downloads/) (do not unzip into a directory starting with a digit). + +_$SONARQUBE-HOME_ (below) refers to the path to the directory where the SonarQube distribution has been unzipped. + +### Setting the Access to the Database + +Edit _$SONARQUBE-HOME/conf/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: + +``` +Example for PostgreSQL +sonar.jdbc.username=sonarqube +sonar.jdbc.password=mypassword +sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube +``` + +### Adding the JDBC Driver + +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_. + +### Configuring the Elasticsearch storage path + +By default, Elasticsearch data is stored in _$SONARQUBE-HOME/data_, but this is not recommended for production instances. Instead, you should store this data elsewhere, ideally in a dedicated volume with fast I/O. Beyond maintaining acceptable performance, doing so will also ease the upgrade of SonarQube. + +Edit _$SONARQUBE-HOME/conf/sonar.properties_ to configure the following settings: + +``` +sonar.path.data=/var/sonarqube/data +sonar.path.temp=/var/sonarqube/temp +``` + +The user used to launch SonarQube must have read and write access to those directories. + +### Starting the Web Server + +The default port is "9000" and the context path is "/". These values can be changed in _$SONARQUBE-HOME/conf/sonar.properties_: + +``` +sonar.web.host=192.0.0.1 +sonar.web.port=80 +sonar.web.context=/sonarqube +``` + +Execute the following script to start the server: + +- On Linux/Mac OS: bin/<YOUR OS>/sonar.sh start +- On Windows: bin/windows-x86-XX/StartSonar.bat + +You can now browse SonarQube at _http://localhost:9000_ (the default System administrator credentials are `admin`/`admin`). + +### Tuning the Web Server + +By default, SonarQube is configured to run on any computer with a simple Java JRE. + +For better performance, the first thing to do when installing a production instance is to use a Java JDK and activate the server mode by uncommenting/setting the following line in _$SONARQUBE-HOME/conf/sonar.properties_: + +``` +sonar.web.javaOpts=-server +``` + +To change the Java JVM used by SonarQube, simply edit _$SONARQUBE-HOME/conf/wrapper.conf_ and update the following line: + +``` +wrapper.java.command=/path/to/my/jdk/bin/java +``` + +### Advanced Installation Features + +- Running SonarQube as a Service on [Windows](/setup/operate-server/) or [Linux](/setup/operate-server/) +- Running SonarQube [behind a Proxy](/setup/operate-server/) + +## Next Steps + +Once your server is installed and running, you may also want to [Install Plugins](/setup/install-plugin/). Then you're ready to begin [Analyzing Source Code](/analysis/overview/). + +## Troubleshooting/FAQ + +### Grant more memory to the web server / compute engine / elastic search + +To grant more memory to a server-side process, uncomment and edit the relevant javaOpts property in `$SONARQUBE_HOME/conf/sonar.properties`, specifically: + +- `sonar.web.javaOpts` (minimum values: `-server -Xmx768m`) +- `sonar.ce.javaOpts` +- `sonar.search.javaOpts` + +### Cannot connect to MySQL database + +By default, remote access to MySQL database server is disabled for security reasons. If you want to remotely access the database server, you need to follow this [quick guide](https://www.cyberciti.biz/tips/how-do-i-enable-remote-access-to-mysql-database-server.html). + +### Failed to start on Windows Vista + +SonarQube seems unable to start when installed under the `Program Files` directory on Windows Vista. It should therefore not be installed there. + +### Failed to start SonarQube with Oracle due to bad `USERS` table structure + +When other `USERS` tables exist in the Oracle DB, if the `sonarqube` user has read access on this other `USERS` table, the SonarQube web server can't start and an exception like the following one is thrown: + +``` +ActiveRecord::ActiveRecordError: ORA-00904: "TOTO": invalid identifier +: INSERT INTO users (login, name, email, crypted_password, salt, +created_at, updated_at, remember_token, remember_token_expires_at, toto, id) +VALUES('admin', 'Administrator', '', 'bba4c8a0f808f9798cf8b1c153a4bb4f9178cf59', '2519754f77ea67e5d7211cd1414698f465aacebb', +TIMESTAMP'2011-06-24 22:09:14', TIMESTAMP'2011-06-24 22:09:14', null, null, null, ?) +ActiveRecord::ActiveRecordError: ORA-00904: "TOTO": invalid identifier + +: INSERT INTO users (login, name, email, crypted_password, salt, +created_at, updated_at, remember_token, remember_token_expires_at, toto, id) +VALUES('admin', 'Administrator', '', 'bba4c8a0f808f9798cf8b1c153a4bb4f9178cf59', +'2519754f77ea67e5d7211cd1414698f465aacebb', TIMESTAMP'2011-06-24 22:09:14', TIMESTAMP'2011-06-24 22:09:14', null, null, null, ?) +``` + +To fix this issue, the rights of the `sonarqube` Oracle user must be decreased to remove read access on the other `USERS` table(s). + +### Failed to connect to the Marketplace via proxy + +Double check that settings for proxy are correctly set in `$SONARQUBE_HOME/conf/sonar.properties`. +Note that if your proxy username contains "\" (backslash), then it should be escaped - for example username "domain\user" in file should look like: + +``` +http.proxyUser=domain\\user +``` + +For some proxies, the exception "java.net.ProtocolException: Server redirected too many times" might mean an incorrect username or password has been configured. diff --git a/server/sonar-docs/src/pages/setup/operate-cluster.md b/server/sonar-docs/src/pages/setup/operate-cluster.md new file mode 100644 index 00000000000..a0f7439dcbb --- /dev/null +++ b/server/sonar-docs/src/pages/setup/operate-cluster.md @@ -0,0 +1,105 @@ +--- +title: Configure & Operate a Cluster +url: /setup/operate-cluster/ +--- + +_High Availability is a feature of the [Data Center Edition](https://redirect.sonarsource.com/editions/datacenter.html)._ + + + +## Table of Contents + +Once the the [SonarQube cluster is installed](/setup/operate-cluster/), you have a High Availability configuration that will allow your SonarQube instance to stay up and running even if there is a crash or failure in one of the nodes of the cluster. + +## Start/Stop/Upgrade the Cluster +### Start the Cluster +1. Start the search nodes +1. Start the application nodes + +### Stop the Cluster +1. Stop the application nodes +1. Stop the search nodes + +### Upgrade SonarQube +1. Stop the cluster +1. Upgrade SonarQube on all nodes (app part, plugins, JDBC driver if required) following the usual Upgrade procedure but without triggering the /setup phase +1. Once all nodes have the same binaries: start the cluster +1. At this point only one of the application nodes is up. Try to access `node_ip:port/setup` on each server, and trigger the setup operation on the one that responds. + +## Install/Upgrade a Plugin +1. Stop the cluster +1. Upgrade the plugin on all nodes +Start the cluster + +## Monitoring +CPU and RAM usage on each node have to be monitored separately with an APM. + +In addition, we provide a Web API _api/system/health_ you can use to validate that all of the nodes in your cluster are operational. + +* GREEN: SonarQube is fully operational +* YELLOW: SonarQube is usable, but it needs attention in order to be fully operational +* RED: SonarQube is not operational + +To call it from a monitoring system without having to give admin credentials, it is possible to setup a System Passcode through the property `sonar.web.systemPasscodez. This must be configured in _$SONARQUBE-HOME/conf/sonar.properties_. + +### Manually Check the Status of your SQ Cluster from the UI +In the System Info page, you can check whether your cluster is running safely (green) or has some nodes with problems (orange or red). + +## Compute Engine Workers +If you change the number of [Compute Engine workers](/instance-administration/compute-engine-performance/) in the UI, you must restart each application node to have the change take effect. + +## Project Move +When the [Project Move](/instance-administration/project-move/) feature is used in a DC installation: + +* Projects are exported on only one of the application nodes +* The archive of the exported projects must be copied to all the applications nodes in the target server + +## Configuration details +Start with the [default configuration](/setup/install-cluster/); it's good in most cases. The details below are only needed in specific cases. + +[Hazelcast](https://hazelcast.org/) is used to manage the communication between the nodes of the cluster. You don't need to install it yourself, it's provided out of the box. + +The following properties may be defined in the _$SONARQUBE-HOME/conf/sonar.properties_ file of each node in a cluster. When defining a property that contains a list of hosts (`*.hosts`) the port is not required if the default port was not overridden in the configuration. + +### All nodes +Property | Description | Default | Required | +---|---|---|---| +`sonar.cluster.enabled`|Set to `true` in each node to activate the cluster mode|`false`|yes +`sonar.cluster.name`|The name of the cluster. **Required if multiple clusters are present on the same network.** For example this prevents mixing Production and Preproduction clusters. This will be the name stored in the Hazelcast cluster and used as the name of the Elasticsearch cluster.|`sonarqube`|no +`sonar.cluster.hosts`|Comma-delimited list of all **application** hosts in the cluster. This value must contain **only application hosts**. Each item in the list must contain the port if the default `sonar.cluster.node.port` value is not used. Item format is `sonar.cluster.node.host` or `sonar.cluster.node.host:sonar.cluster.node.port`.| |yes +`sonar.cluster.search.hosts`|Comma-delimited list of search hosts in the cluster. Each item in the list must contain the port if the default `sonar.search.port` value is not used. Item format is `sonar.search.host` or `sonar.search.host:sonar.search.port`.| |yes +`sonar.cluster.node.name`|The name of the node that is used on Elasticsearch and stored in Hazelcast member attribute (NODE_NAME) for sonar-application|`sonarqube-{UUID}`|no +`sonar.cluster.node.type`|Type of node: either `application` or `search`| |yes +`sonar.cluster.node.host`|IP address of the network card that will be used by Hazelcast to communicate with the members of the cluster. If not specified, the first interface will be chosen (note that loopback interfaces won't be selected)| |no + + +### Application nodes +Property | Description | Required +---|---|---|--- +`sonar.cluster.node.port`|The Hazelcast port for communication with each application member of the cluster. Default: `9003`|no| +`sonar.cluster.node.web.port`|Hazelcast port for communication with the ComputeEngine process. Port must be accessible to all other search and application nodes. If not specified, a dynamic port will be chosen and all ports must be open among the nodes.|no +`sonar.cluster.node.ce.port`|Hazelcast port for communication with the WebServer process. Port must be accessible to all other search and application nodes. If not specified, a dynamic port will be chosen and all ports must be open among the nodes.|no +`sonar.auth.jwtBase64Hs256Secret`|Required for authentication with multiple web servers. It is used to keep user sessions opened when they are redirected from one web server to another by the load balancer. See _$SONARQUBE-HOME/conf/sonar.properties_) for details about how to generate this secret key.| yes + +### Search nodes +Property | Description | Default | Required +---|---|---|--- +`sonar.search.host`|Listening IP. IP must be accessible to all other search and application nodes.|`127.0.0.1`|yes +`sonar.search.port`|Listening port. Port must be accessible to all other search and application nodes.|`9001`|yes +`sonar.search.initialStateTimeout`|The timeout for the Elasticsearch nodes to elect a master node. The default value will be fine in most cases, but in a situation where startup is failing because of a timeout, this may need to be adjusted. The value must be set in the format: `{integer}{timeunit}`. Valid `{timeunit}` values are: `ms` (milliseconds); `s` (seconds); `m` (minutes); `h` (hours); `d` (days); `w` (weeks)|cluster: 120s; standalone: 30s|no + +## Limitations +* Cluster downtime is required for SonarQube upgrades or plugin installations. +* All application nodes must be stopped when installing, uninstalling or upgrading a plugin. +* Plugins are not shared, it means if you install/uninstall/upgrade a given plugin in one application node, you need to perform the same actions on the other application node. +* There is no way to perform actions on the cluster from a central app - all operations must be done manually on each node of the cluster. + + +## Frequently Asked Questions +### Does Elasticsearch discover automatically other ES nodes? +No. Multicast is disabled. All hosts (IP+port) must be listed. +### Can different nodes run on the same machine? +Yes, but the best is to have 5 machines to be really resilient to failures. +### Can the members of a cluster be discovered automatically? +No, all nodes must be configured in _$SONARQUBE-HOME/conf/sonar.properties_ + diff --git a/server/sonar-docs/src/pages/setup/operate-server.md b/server/sonar-docs/src/pages/setup/operate-server.md new file mode 100644 index 00000000000..7b9599cce26 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/operate-server.md @@ -0,0 +1,127 @@ +--- +title: Configure & Operate the Server +url: /setup/operate-server/ +--- + +<!-- sonarqube --> + +## Running SonarQube as a Service on Windows + +### Install/uninstall NT service (may have to run these files via Run As Administrator): + +``` +%SONARQUBE_HOME%/bin/windows-x86-32/InstallNTService.bat +%SONARQUBE_HOME%/bin/windows-x86-32/UninstallNTService.bat +``` + +### Start/stop the service: + +``` +%SONARQUBE_HOME%/bin/windows-x86-32/StartNTService.bat +%SONARQUBE_HOME%/bin/windows-x86-32/StopNTService.bat +``` + +## Running SonarQube as a Service on Linux + +The following has been tested on Ubuntu 8.10 and CentOS 6.2. + +Create the file /etc/init.d/sonar with this content: + +``` +#!/bin/sh +# +# rc file for SonarQube +# +# chkconfig: 345 96 10 +# description: SonarQube system (www.sonarsource.org) +# +### BEGIN INIT INFO +# Provides: sonar +# Required-Start: $network +# Required-Stop: $network +# Default-Start: 3 4 5 +# Default-Stop: 0 1 2 6 +# Short-Description: SonarQube system (www.sonarsource.org) +# Description: SonarQube system (www.sonarsource.org) +### END INIT INFO + +/usr/bin/sonar $* +``` + +Register SonarQube at boot time (Ubuntu, 32 bit): + +``` +sudo ln -s $SONAR_HOME/bin/linux-x86-32/sonar.sh /usr/bin/sonar +sudo chmod 755 /etc/init.d/sonar +sudo update-rc.d sonar defaults +``` + +Register SonarQube at boot time (RedHat, CentOS, 64 bit): + +``` +sudo ln -s $SONAR_HOME/bin/linux-x86-64/sonar.sh /usr/bin/sonar +sudo chmod 755 /etc/init.d/sonar +sudo chkconfig --add sonar +``` + +## Securing the Server Behind a Proxy + +This section helps you configure the SonarQube Server if you want to run it behind a proxy. This can be done for security concerns or to consolidate multiple disparate applications. + +### Server Configuration + +To run the SonarQube server over HTTPS, you must build a standard reverse proxy infrastructure. + +The reverse proxy must be configured to set the value `X_FORWARDED_PROTO: https` in each HTTP request header. Without this property, redirection initiated by the SonarQube server will fall back on HTTP. + +### Using an Apache Proxy + +We assume that you've already installed Apache 2 with module mod_proxy, that SonarQube is running and available on `http://private_sonar_host:sonar_port/` and that you want to configure a Virtual Host for `www.public_sonar.com`. + +At this point, edit the HTTPd configuration file for the `www.public_sonar.com` virtual host. Include the following to expose SonarQube via `mod_proxy` at `http://www.public_sonar.com/`: + +``` +ProxyRequests Off +ProxyPreserveHost On +<VirtualHost *:80> + ServerName www.public_sonar.com + ServerAdmin admin@somecompany.com + ProxyPass / http://private_sonar_host:sonar_port/ + ProxyPassReverse / http://www.public_sonar.com/ + ErrorLog logs/somecompany/sonar/error.log + CustomLog logs/somecompany/sonar/access.log common +</VirtualHost> +``` + +Apache configuration is going to vary based on your own application's requirements and the way you intend to expose SonarQube to the outside world. If you need more details about Apache HTTPd and mod_proxy, please see [http://httpd.apache.org](http://httpd.apache.org). + +### Using Nginx + +We assume that you've already installed Nginx, that you are using a Virtual Host for www.somecompany.com and that SonarQube is running and available on `http://sonarhost:sonarport/`. + +At this point, edit the Nginx configuration file. Include the following to expose SonarQube at http://www.somecompany.com/: + +``` +# the server directive is nginx's virtual host directive +server { + # port to listen on. Can also be set to an IP:PORT + listen 80; + + # sets the domain[s] that this vhost server requests for + server_name www.somecompany.com; + + location / { + proxy_pass http://sonarhost:sonarport; + } +} +``` + +Nginx configuration will vary based on your own application's requirements and the way you intend to expose SonarQube to the outside world. If you need more details about Nginx, please see [https://www.nginx.com/resources/admin-guide/reverse-proxy/](https://www.nginx.com/resources/admin-guide/reverse-proxy/). + +Note that you may need to increase the max URL length since SonarQube requests can have URLs longer than 2048. + +### Using IIS + +Please see: [http://blog.jessehouwing.nl/2016/02/configure-ssl-for-sonarqube-on-windows.html](http://blog.jessehouwing.nl/2016/02/configure-ssl-for-sonarqube-on-windows.html) + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/setup/overview.md b/server/sonar-docs/src/pages/setup/overview.md new file mode 100644 index 00000000000..5b3c8752f75 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/overview.md @@ -0,0 +1,19 @@ +--- +title: Overview +url: /setup/overview/ +--- + +<!-- sonarqube --> +### Get Started in Two Minutes +To give the SonarQube Platform a quick try, follow the [Get Started in Two Minutes Guide](/setup/get-started-2-minutes/). + +### Install a Production Instance +To install a production instance, read the [Requirements](/requirements/requirements/), and then follow the [Installation Guide](/setup/install-server/). + +### After the Installation +After your server is up and running, you'll need to install one or more [SonarScanners](https://docs.sonarqube.org/display/SCAN) on the machines where analysis will be performed. + +### Upgrade your Production Instance +To upgrade your production instance, read the [Upgrade Guide](/setup/upgrading/) and the relevant, version-specific upgrade notes. + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/setup/troubleshooting.md b/server/sonar-docs/src/pages/setup/troubleshooting.md new file mode 100644 index 00000000000..2c849fbb91b --- /dev/null +++ b/server/sonar-docs/src/pages/setup/troubleshooting.md @@ -0,0 +1,43 @@ +--- +title: Troubleshooting +url: /setup/troubleshooting/ +--- + +<!-- sonarqube --> + +## Checking the logs + +If you're having trouble starting your server for the first time (or any subsequent time!) the first thing to do is check your server logs. You'll find them in `$SONARQUBE_HOME/logs`: + +* sonar.log - Log for the main process. Holds general information about startup and shutdown. You'll get overall status here but not details. Look to the other logs for that. +* web.log - Information about initial connection to the database, database migration and reindexing, and the processing of HTTP requests. This includes database and search engine logs related to those requests. +* ce.log - Information about background task processing and the database and search engine logs related to those tasks. +* es.log - Ops information from the search engine, such as Elasticsearch startup, health status changes, cluster-, node- and index-level operations, etc. + +## Understanding the logs + +When there's an error, you'll very often find a stacktrace in the logs. If you're not familiar stacktraces, they can be intimidatingly tall walls of incomprehensible text. As a sample, here's a fairly short one: + +``` +java.lang.IllegalStateException: Unable to blame file **/**/foo.java + at org.sonarsource.scm.git.JGitBlameCommand.blame(JGitBlameCommand.java:128) + at org.sonarsource.scm.git.JGitBlameCommand.access$000(JGitBlameCommand.java:44) + at org.sonarsource.scm.git.JGitBlameCommand$1.call(JGitBlameCommand.java:112) + at org.sonarsource.scm.git.JGitBlameCommand$1.call(JGitBlameCommand.java:109) + at java.util.concurrent.FutureTask.run(Unknown Source) + at java.util.concurrent.ThreadPoolExecutor.runWorker(Unknown Source) + at java.util.concurrent.ThreadPoolExecutor$Worker.run(Unknown Source) + at java.lang.Thread.run(Unknown Source) +Caused by: java.lang.NullPointerException + at org.eclipse.jgit.treewalk.filter.PathFilter.create(PathFilter.java:77) + at org.eclipse.jgit.blame.BlameGenerator.<init>(BlameGenerator.java:161) + at org.eclipse.jgit.api.BlameCommand.call(BlameCommand.java:203) + at org.sonarsource.scm.git.JGitBlameCommand.blame(JGitBlameCommand.java:126) + ... 7 more +``` + +Unless you wrote the code that produced this error, you really only care about: +* the first line, which ought to have a human-readable message after the colon. In this case, it's Unable to blame file `**/**/foo.java` +* and any line that starts with `Caused by:`. There are often several `Caused by` lines, and indentation makes them easy to find as you scroll through the error. Be sure to read each of these lines. Very often one of them - the last one or next to last one - contains the real problem. + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/setup/upgrade-notes.md b/server/sonar-docs/src/pages/setup/upgrade-notes.md new file mode 100644 index 00000000000..f662cc10614 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/upgrade-notes.md @@ -0,0 +1,107 @@ +--- +title: Release Upgrade Notes +url: /setup/upgrade-notes/ +--- + +## Release 7.4 Upgrade Notes +**Analysis Failure on Invalid New Code Period** +Analysis will fail if the New Code Period (see below) is not set to one of: +* valid, in-the-past date +* positive integer (number of days) +* `previous_version` +* the version string of an existing snapshot + +For more, see [SONAR-10555](https://jira.sonarsource.com/browse/SONAR-10555) + +**New Create Portfolios and Create Applications permissions** +Two distinct new create permissions are added in this version. Users who have any creation permission will see a new "+" item giving access to these permissions in the top menu. For more, see the Global Permissions topic in [Security](/instance-administration/security/) + +**Issues from third party Roslyn analyzers** +Starting with this version, analyzing a C# / VB.NET solution automatically imports issues found by attached Roslyn analyzers into SonarQube, and no longer suppresses them from the MSBuild output. The Quality Gate status of projects may be impacted. + +**"Leak" replaced with "New Code"** +Wording has been updated throughout the interface to replace "Leak" and "Leak Period" with "New Code" and "New Code Period". + +## Release 7.3 Upgrade Notes + +**New "Administer Security Hotspots" Permission** +During the upgrade, the new "Administer Security Hotspots" permission is granted to all users/groups who already have the "Administer Issues" permission. + +**Expanded Compute Engine Logs** +Starting with this version, Compute Engine logs will be more verbose. These logs are rotated automatically, but on a daily basis, not based on file size. + +**PostgreSQL < 9.3 No Longer Supported** +SonarQube 7.3+ only supports PostgreSQL 9.3 to 10. SonarQube will not start if you are using a lower version of PostgreSQL. + +**Some 3rd-party Plugins Incompatible** +APIs deprecated before SonarQube 5.6 are dropped in this version, making some third-party plugins incompatible. It is always advised to check plugin compatibility in the Plugin Version Matrix with each new upgrade, and more so for this version. + + +## Release 7.2 Upgrade Notes + +**License Incompatibility** +**Users coming from 6.7.5 must not upgrade to this version.** Your license will be incompatible. Instead, if you seek an upgrade to an intermediate version before the next L.T.S. version, you must start from 7.3 or higher. + +**Pull Request Analysis** +Pull Requests are now a first class citizen feature in SonarQube for Developer, Enterprise and Data Center Edition users. + +If you are using GitHub, you need to be sure to NOT have the GitHub Plugin in your SONARQUBE_HOME/extensions/plugins directory. + +**New Edition Packaging** +SonarSource Commercial Editions are now distributed individually, so you directly get the features and functionalities that match your needs. This means that upgrade/downgrade from one edition to another is no longer possible within the SonarQube Marketplace. In order to use a different edition you must download its dedicated package, and have a license ready for using that edition. + +**Deprecated Features** +SonarQube 7.2 is the last version supporting PostgreSQL < 9.3. Starting from SonarQube 7.3 the minimal supported version of PostgreSQL will be 9.3: SONAR-10668 + + + +## Release 7.1 Upgrade Notes + +**License Incompatibility** +**Users coming from 6.7.5 must not upgrade to this version.** Your license will be incompatible. Instead, if you seek an upgrade to an intermediate version before the next L.T.S. version, you must start from 7.3 or higher. + +**Live Portfolios** +Portfolio measures are now updated without having to explicitly trigger recalculation. As a result, the "views" scanner task no longer has any effect, and will fail with a clear error message. + +**Deprecated Features** +Support for MySQL is deprecated for all editions below Data Center Edition (see below). + +**Dropped Features** +- Support for MySQL in Data Center Edition. +- The "accessors" metric, which was deprecated in SonarQube 5.0. + + +## Release 7.0 Upgrade Notes + +**License incompatibility** +**Users coming from 6.7.5 must not upgrade to this version.** Your license will be incompatible. Instead, if you seek an upgrade to an intermediate version before the next L.T.S. version, you must start from 7.3 or higher. + +**Measures: Live Update** +Project measures, including the Quality Gate status, are computed without having to trigger another code scan when issue changes may impact them. + +**Built-In Read-Only Quality Gate** +In order to make clear the default, minimum and recommended criteria Quality Gates, the "Sonar way" Quality Gate is now read-only, and the default if one is not already set. It may be updated automatically at each upgrade of SonarQube. + +**Dropped Features** +It's no longer possible to unset the default Quality Gate. + + +## Release 6.7.5 Upgrade Notes + +**Commercial Edition Must Be Upgraded** +Because a new server identifier will be generated at upgrade to this version, startup will fail unless you upgrade your commercial edition to the latest compatible version. I.E. don't just copy over your edition plugins from one instance to the next, but make sure to download the latest edition bundle. + +**SonarLint Must Be Upgraded** +Analyzers provided as part of a commercial package will be disabled in old versions of SonarLint. SonarLint users must upgrade to the latest available version: + +- SonarLint for Eclipse: 3.3+. +- SonarLint for IntelliJ: 3.1+ + +**Multi-Version Upgrade** +Don't forget to read all the intermediate upgrade notes if you're upgrading more than a single version. + + +## Release 6.7 Upgrade Notes + +**Drop of Issues Report** +The deprecated Issues Report feature has been removed. diff --git a/server/sonar-docs/src/pages/setup/upgrading.md b/server/sonar-docs/src/pages/setup/upgrading.md new file mode 100644 index 00000000000..88d862c30f7 --- /dev/null +++ b/server/sonar-docs/src/pages/setup/upgrading.md @@ -0,0 +1,60 @@ +--- +title: Upgrade the Server +url: /setup/upgrading/ +--- + +<!-- sonarqube --> +Upgrading across multiple versions is handled automatically. However, if in your migration path you have an LTS version, you must first migrate to this LTS and then migrate to your target version. + +Example 1 : 5.1 -> 7.0, migration path is 5.1 -> 5.6.7 LTS -> 6.7.x LTS -> 7.0 +Example 2 : 6.2 -> 6.7, migration path is 6.2 -> 6.7.x LTS (where x is the latest patch available for 6.7 - you don't need to install all the intermediary patches, just take the latest) + +## How to Upgrade? + +This is a generic upgrade guide, please read carefully the Upgrade Notes of your target version and of each intermediate version, if any (below). + + Planning to Upgrade to a Commercial Editions? +If you are targetting to move to 6.7 LTS and to install a commercial Edition, please read this [documentation](https://docs.sonarqube.org/display/SONARQUBE67/SonarSource+Editions). + +Before you start, backup your SonarQube Database. Upgrade problems are rare, but you'll want the backup if anything does happen. + +1. Download and unzip the SonarQube distribution of your edition in a fresh directory, let's say `$NEW_SONARQUBE_HOME` +2. Manually install the non-default plugins that are compatible with your version of SonarQube. Use the Compatibility Matrix to ensure that the versions you install are compatible with your server version. Note that the most recent versions of all SonarSource code analyzers available in your edition are installed by default. Simply copying plugins from the old server to the new is not recommended; incompatible or duplicate plugins could cause startup errors. +3. Update the contents of `sonar.properties` and `wrapper.conf` files (in `$NEW_SONARQUBE_HOME/conf`) with the settings of the related files in the `$OLD_SONARQUBE_HOME/conf` directory (web server URL, database, ldap settings, etc.). Do not copy-paste the old files. +If you are using the Oracle DB, copy its JDBC driver into `$NEW_SONARQUBE_HOME/extensions/jdbc-driver/oracle` +4. Stop your old SonarQube Server +5. Start your new SonarQube Server +6. Browse to `http://yourSonarQubeServerURL/setup` and follow the setup instructions +7. Analyze your projects (and compute your Views|Portofolios|Application if you own the Enterprise Edition product) to get fresh data + +## Anything Else? + +### Oracle Clean-up + +Starting with 6.6, there's an additional step you may want to perform if you're using Oracle. On Oracle the database columns to be dropped are now marked as UNUSED and are not physically dropped anymore. To reclaim disk space, Oracle administrators must drop these unused columns manually. The SQL request is `ALTER TABLE foo DROP UNUSED COLUMNS`. The relevant tables are listed in the system table `all_unused_col_tabs`. + +### Additional Database Maintenance + +Refreshing your database's statistics and rebuilding your database's indices are recommended once the technical upgrade is done (just before the very last step). + +For PostgreSQL, that means executing `VACUUM FULL`. According to the PostgreSQL documentation: + +``` +In normal PostgreSQL operation, tuples that are deleted or obsoleted by an update are not physically removed from their table; they remain present until a VACUUM is done. +``` + +### Scanner Update + +When upgrading SonarQube, you should also make sure you’re using the latest versions of the SonarQube scanners to take advantage of features and fixes on the scanner side. Please check the documentation pages of the Scanners you use for the most recent version compatible with SonarQube and your build tools. + +### SonarQube as a Linux or Windows Service + +If you use external configuration, such as a script or Windows Service to control your server, you'll need to update it to point to `$NEW_SONARQUBE_HOME`. + +In case you used the InstallNTService.bat to install SonarQube as a Windows Service, run the $OLD_SONARQUBE_HOME/bin/.../UninstallNTService.bat before running the InstallNTService.bat of the $NEW_SONARQUBE_HOME. + +## Release Upgrade Notes + +Usually SonarQube releases come with some specific recommendations for upgrading from the previous version. You should read the upgrade notes for each version between your current version and the target version. To upgrade from a version not listed in [Release Upgrade Notes](/setup/upgrade-notes/), see [Documentation for Previous Versions](https://docs.sonarqube.org/display/SONARNEXT/Documentation+for+previous+versions). + +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/sonarcloud/analyze-a-project.md b/server/sonar-docs/src/pages/sonarcloud/analyze-a-project.md deleted file mode 100644 index 113f8d502e8..00000000000 --- a/server/sonar-docs/src/pages/sonarcloud/analyze-a-project.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Analyze a Project -url: /analyze-a-project/ ---- - -## Prepare your organization - -A project must belong to an [organization](/organizations/overview/). Create one if you intend to collaborate with your team mates, or use your personal organization for test purposes. - -[[info]] -| ** Important note for private code:** Newly created organizations and personal organizations are under a free plan by default. This means projects analyzed on these organizations are public by default: the code will be browsable by anyone. If you want private projects, you should [upgrade your organization to a paid plan](/sonarcloud-pricing/) in the "Administration > Billing" page of your organization. - -Find the key of your organization, you will need it at later stages. It can be found on the top right corner of your organization's header. - -## Run analysis - -SonarCloud currently does not trigger analyses automatically - this feature will come in a near future. Currently, it's up to you to launch them inside your -existing CI scripts. - -Depending on which cloud solution you are using for your developments, you can rely on dedicated integrations to help you: - -* VSTS: [read our dedicated documentation](/integrations/vsts/) -* Bitbucket Cloud: [read our dedicated documentation](/integrations/bitbucketcloud/) -* GitHub: [read our dedicated documentation](/integrations/github/) - -If you are not using those solutions, you will have to find out what command to execute to run the analysis. Our [tutorial](/#sonarcloud#/onboarding) will help you on this. diff --git a/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md b/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md index 6006edcf435..669587ab3d9 100644 --- a/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md +++ b/server/sonar-docs/src/pages/sonarcloud/integrations/bitbucketcloud.md @@ -1,10 +1,8 @@ --- -title: Integration with Bitbucket Cloud +title: Bitbucket Cloud url: /integrations/bitbucketcloud/ --- -## Authentication - You can connect to SonarCloud using your Bitbucket Cloud account. On the [login page](/#sonarcloud#/sessions/new), just click on the "Log in with Bitbucket" button. ## Install SonarCloud add-on for Bitbucket Cloud @@ -47,7 +45,7 @@ If you haven't configured the analysis with Pipelines (maybe because you are usi 1. Go to the repository where you want to display the widget. On the "Overview" page, you should see an empty SonarCloud widget. Click on the link inside the empty widget or just go directly to your repository's "Settings > SonarCloud Settings". -2. If you're not already logged in on SonarCloud, do it by using the options provided there. You can log in with Bitbucket Cloud by clicking on the blue button, or click on "More options" to log in with GitHub or VSTS. +2. If you're not already logged in on SonarCloud, do it by using the options provided there. You can log in with Bitbucket Cloud by clicking on the blue button. 3. Once you're logged in on SonarCloud, you should see a dropdown allowing you to choose one of the projects you administer. Just choose the one you want to link to this Bitbucket repository and click "Save". diff --git a/server/sonar-docs/src/pages/sonarcloud/integrations/github.md b/server/sonar-docs/src/pages/sonarcloud/integrations/github.md index c283c9689c6..74b87569486 100644 --- a/server/sonar-docs/src/pages/sonarcloud/integrations/github.md +++ b/server/sonar-docs/src/pages/sonarcloud/integrations/github.md @@ -1,10 +1,8 @@ --- -title: Integration with GitHub +title: GitHub url: /integrations/github/ --- -## Authentication - You can connect to SonarCloud using your GitHub account. On the [login page](/#sonarcloud#/sessions/new), just click on the "Log in with GitHub" button. ## Trigger analyses diff --git a/server/sonar-docs/src/pages/sonarcloud/integrations/vsts.md b/server/sonar-docs/src/pages/sonarcloud/integrations/vsts.md index 448affcd709..ac14a957fdf 100644 --- a/server/sonar-docs/src/pages/sonarcloud/integrations/vsts.md +++ b/server/sonar-docs/src/pages/sonarcloud/integrations/vsts.md @@ -1,33 +1,33 @@ --- -title: Integration with VSTS +title: Azure DevOps url: /integrations/vsts/ --- +[[info]] +| This page is about Azure DevOps, formerly known as VSTS. -## Authentication - -You can connect to SonarCloud using your VSTS account. On the [login page](/#sonarcloud#/sessions/new), just click on the "Log in with VSTS" button. +You can connect to SonarCloud using your Azure DevOps account. On the [login page](/#sonarcloud#/sessions/new), just click on the "Log in with Azure DevOps" button. [[warning]] -| Only work and school VSTS accounts are authorized to login on SonarCloud. +|  Only work and school Azure DevOps accounts are authorized to login on SonarCloud. -## Install the SonarCloud VSTS extension +## Install the SonarCloud Azure DevOps extension -The SonarCloud VSTS extension brings everything you need to have your projects analyzed on SonarCloud +The SonarCloud Azure DevOps extension brings everything you need to have your projects analyzed on SonarCloud very quickly: * Integration with the Build definitions to easily trigger the analysis * Pull request decoration to get quick feedback on the code changes -* Widget to have the overview quality of your projects inside VSTS dashboards +* Widget to have the overview quality of your projects inside Azure DevOps dashboards -Install [SonarCloud extension for VSTS](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarcloud)by clicking on the "Get it free" button. +Install [SonarCloud extension for Azure DevOps](https://marketplace.visualstudio.com/items?itemName=SonarSource.sonarcloud)by clicking on the "Get it free" button. -Then follow the comprehensive [Microsoft lab on how to integrate VSTS with SonarCloud](https://aka.ms/sonarcloudlab). +Then follow the comprehensive [Microsoft lab on how to integrate Azure DevOps with SonarCloud](https://aka.ms/sonarcloudlab). ## Quality Gate Status widget -You can monitor the Quality Gate status of your projects directly in your VSTS dashboard. Follow these simple steps to configure your widget: +You can monitor the Quality Gate status of your projects directly in your Azure DevOps dashboard. Follow these simple steps to configure your widget: -1. Once the VSTS extension is installed and your project has been successfully analyzed, go to one of your VSTS dashboards (or create one). Click on the pen icon in the bottom right corner of the screen, and then on the "+" icon to add a widget. +1. Once the Azure DevOps extension is installed and your project has been successfully analyzed, go to one of your Azure DevOps dashboards (or create one). Click on the pen icon in the bottom right corner of the screen, and then on the "+" icon to add a widget. 2. In the list of widgets, select the "Code Quality" one and then click on the "Add" button. An empty widget is added to your dashboard. diff --git a/server/sonar-docs/src/pages/sonarcloud/organizations/manage-team.md b/server/sonar-docs/src/pages/sonarcloud/organizations/manage-team.md index 8cbb162bcc1..05b2c6e165c 100644 --- a/server/sonar-docs/src/pages/sonarcloud/organizations/manage-team.md +++ b/server/sonar-docs/src/pages/sonarcloud/organizations/manage-team.md @@ -30,5 +30,4 @@ project level for instance. ## Future evolutions Future versions of SonarCloud will make this onboarding process easier thanks to better integrations with GitHub, -Bitbucket Cloud and VSTS: users won't have to sign up prior to joining an organization, and their permissions will -be retrieved at best from the ones existing on the other systems. +Bitbucket Cloud and Azure DevOps: users won't have to sign up prior to joining an organization, and their permissions will be retrieved at best from the ones existing on the other systems. diff --git a/server/sonar-docs/src/pages/sonarcloud/privacy.md b/server/sonar-docs/src/pages/sonarcloud/privacy.md index a92e13c100a..624cf57851b 100644 --- a/server/sonar-docs/src/pages/sonarcloud/privacy.md +++ b/server/sonar-docs/src/pages/sonarcloud/privacy.md @@ -1,5 +1,5 @@ --- -title: Privacy +title: Privacy Policy url: /privacy/ --- diff --git a/server/sonar-docs/src/pages/sonarcloud/security.md b/server/sonar-docs/src/pages/sonarcloud/security.md index 89315038c6b..e9e203a17a6 100644 --- a/server/sonar-docs/src/pages/sonarcloud/security.md +++ b/server/sonar-docs/src/pages/sonarcloud/security.md @@ -1,5 +1,5 @@ --- -title: SonarCloud Security +title: Security Statement url: /security/ --- @@ -52,7 +52,7 @@ SonarCloud performs webhook calls from the following list of IPs: ## Authentication -Primary authentication on the system is available only through OAuth authentication with GitHub, Bitbucket Cloud and Microsoft VSTS. As a consequence, users don’t have a password on SonarCloud, and are as protected as what they expect (especially with 2FA activated on those systems). +Primary authentication on the system is available only through OAuth authentication with GitHub, Bitbucket Cloud and Microsoft Azure DevOps. As a consequence, users don’t have a password on SonarCloud, and are as protected as what they expect (especially with 2FA activated on those systems). For WS API calls or source code analysis triggered from CI services, only revocable user tokens are accepted. diff --git a/server/sonar-docs/src/pages/user-guide/activity-history.md b/server/sonar-docs/src/pages/user-guide/activity-history.md new file mode 100644 index 00000000000..f7de8a7b71e --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/activity-history.md @@ -0,0 +1,18 @@ +--- +title: Activity and History +url: /user-guide/activity-history/ +--- + +The Project Activity page offers a comprehensive list of the analyses on file for a project (subject to [Housekeeping](/instance-administration/housekeeping/)), and the ability to see the evolution of project measures over time. + +Graphs on the activity page help you understand the evolution of up to three measures of your choice against each other. Graph mouseovers show the measure values and events associated with particular analyses. + +## Events +There are four types of events: + +* Quality Gate - the status of the [quality gate](/user-guide/quality-gates/) changed. +* Profile - the [quality profile](/instance-administration/quality-profiles/) used to analyze the project changed - either the profile was edited, or a different profile was used to analyze the project. +* Version - the project's version changed. +* Other - an event was manually created on a snapshot. See [Managing History](/project-administration/managing-project-history/) + +Events are shown on the [project front page](/user-guide/project-page/) and in the project Activity page. diff --git a/server/sonar-docs/src/pages/user-guide/applications.md b/server/sonar-docs/src/pages/user-guide/applications.md new file mode 100644 index 00000000000..0f510d48957 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/applications.md @@ -0,0 +1,28 @@ +--- +title: Applications +url: /user-guide/applications/ +--- + +*Applications are available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html).* + +## Using Applications + +An Application is an aggregation of projects into a synthetic project. Assume you have a set of projects which has been split for technical reasons, but which shares a lifecycle; they interact directly in production and are always released together. With an Application, they can be treated as a single entity in {instance} with a unified Project Homepage, Issues list, Measures space, and most importantly: Quality Gate. + +### Applications vs. Portfolios + +Applications and Portfolios are both aggregations of projects, but they have different goals and therefore different presentations. A Portfolio is designed to be a very high-level, executive overview that shows how a package of projects that may only be tangentially related are doing quality-wise, and what the trends are. Applications allow you to see your set of projects as a larger, overall meta-project. For instance, because all the projects in an application ship together, if one of them isn't releasable then none of them are, and an Application's consolidated Quality Gate gives you an immediate summary of what must be fixed across all projects in order to allow you to release the set. + +## Application Setup + +Applications are created and edited in the global Portfolio administration interface: **Administration > Configuration > Portfolios**. For more, see [Configuring Portfolios and Applications](/project-administration/configuring-portfolios-and-applications/). Applications must be created initially by a user with global administration rights, but after set-up, administration of an individual Application can be delegated to other users. + +### Populating Application Data + +An Application is automatically re-calculated after each analysis of one of its projects. If you want immediate (re)calculation, a user with administration rights on the Application can use the **Recompute** button in the Application-level **Administration > Edit Definition** interface. The global Portfolio administration interface: **Administration > Configuration > Portfolios** offers the ability to queue re-computation of all Applications and Portfolios at once. + +## Applications and Branch Analysis + +Long-lived Branches are available for applications. They allow you to aggregate long-lived branches from the projects in an application. + +Once an Application has been set up, anyone with administration rights on the Application can manually create a new branch in the **Administration > Edit Definition** interface. Branches can also be managed from the global **Administration > Configuration > Portfolios** interface. For each Application branch you can choose which project branch should be included, or whether the project should be represented in the branch at all. diff --git a/server/sonar-docs/src/pages/user-guide/built-in-rule-tags.md b/server/sonar-docs/src/pages/user-guide/built-in-rule-tags.md new file mode 100644 index 00000000000..6ef0dedd6bb --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/built-in-rule-tags.md @@ -0,0 +1,25 @@ +--- +title: Built-in Rule Tags +url: /user-guide/built-in-rule-tags/ +--- +Tags are a way to categorize rules and issues. Issues inherit the tags on the rules that raised them. Some tags are language-specific, but many more appear across languages. Users can add tags to rules and issues, but most rules have some tags out of the box. Here is a non-comprehensive list of what some of those built-in tags mean: + +*NOTE : Links below to [rules.sonarsource.com](https://rules.sonarsource.com) will be initially filtered for Java language rules* + +* [brain-overload](https://rules.sonarsource.com/java/tag/brain-overload) - there is too much to keep in your head at one time +* [bad-practice](https://rules.sonarsource.com/java/tag/bad-practice) - the code likely works as designed, but the way it was designed is widely recognized as being a bad idea. +* [cert](https://rules.sonarsource.com/java/tag/cert) - relates to a rule in a [CERT](https://www.securecoding.cert.org/confluence/x/BgE) standard. There are currently three CERT standards: [C](https://www.securecoding.cert.org/confluence/x/HQE), [C++](https://www.securecoding.cert.org/confluence/x/fQI), and [Java](https://www.securecoding.cert.org/confluence/x/Ux). Many of these rules are not language-specific, but are good programming practices. That's why you'll see this tag on non-C/C++, Java rules. +* [clumsy](https://rules.sonarsource.com/java/tag/clumsy) - extra steps are used to accomplish something that could be done more clearly and concisely. (E.G. calling .toString() on a String). +* [confusing](https://rules.sonarsource.com/java/tag/confusing) - will take maintainers longer to understand than is really justified by what the code actually does +* [convention](https://rules.sonarsource.com/java/tag/convention) - coding convention - typically formatting, naming, whitespace... +* [cwe](https://rules.sonarsource.com/java/tag/cwe) - relates to a rule in the [Common Weakness Enumeration](http://cwe.mitre.org/). For more on CWE and on security-related rules in general, see [Security-related rules](/user-guide/security-rules/). +* [design](https://rules.sonarsource.com/java/tag/design) - there is something questionable about the design of the code +* [lock-in](https://rules.sonarsource.com/java/tag/lock-in) - environment-specific features are used +* [misra](https://rules.sonarsource.com/java/tag/misra) - relates to a rule in one of the [MISRA](http://www.misra.org.uk/) standards. While the MISRA rules are primarily about C and C++, many of them are not language-specific (E.G. don't use a float as a loop counter) but are simply good programming practices. That's why you'll see these tags on non-C/C++ rules. +* [owasp](https://rules.sonarsource.com/java/tag/owasp) - relates to a rule in the [OWASP Top Ten](https://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project) security standards. Note, that the OWASP Top Ten is a list of high-level vulnerabilities which translates to many, many potential rules. +* [pitfall](https://rules.sonarsource.com/java/tag/pitfall) - nothing is wrong yet, but something could go wrong in the future; a trap has been set for the next guy and he'll probably fall into it and screw up the code. +* [sans-top25](https://rules.sonarsource.com/java/tag/sans-top25) - relates to the [SANS Top 25 Coding Errors](http://www.sans.org/top25-software-errors/), which are security-related. Note that the SANS Top 25 list is pulled directly from the CWE. +* [suspicious](https://rules.sonarsource.com/java/tag/suspicious) - it's not guaranteed that this is a **bug**, but it looks suspiciously like one. At the very least, the code should be re-examined & likely refactored for clarity. +* [unpredictable](https://rules.sonarsource.com/java/tag/unpredictable) - the code may work fine under current conditions, but may fail erratically if conditions change. +* [unused](https://rules.sonarsource.com/java/tag/unused) - unused code, E.G. a private variable that is never used. +* [user-experience](https://rules.sonarsource.com/java/tag/user-experience) - there's nothing technically wrong with your code, but it may make some or all of your users hate you. diff --git a/server/sonar-docs/src/pages/user-guide/concepts.md b/server/sonar-docs/src/pages/user-guide/concepts.md new file mode 100644 index 00000000000..9e44a38bd7b --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/concepts.md @@ -0,0 +1,35 @@ +--- +title: Concepts +url: /user-guide/concepts/ +--- + + +<!-- sonarqube --> +## Architecture +| Concept | Definition | +| -------- | ------------------------------------------------------------------------------------- | +| Analyzer | A client application that analyzes the source code to compute **snapshots**. | +| Database | Stores configuration and **snapshots** | +| Server | Web interface that is used to browse **snapshot** data and make configuration changes | + +See also the [SonarQube Platform Overview](/architecture/architecture-integration/). +<!-- /sonarqube --> + +## Quality +| Concept | Definition | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Bug | An issue that represents something wrong in the code. If this has not broken yet, it will, and probably at the worst possible moment. This needs to be fixed. Yesterday. | +| Code Smell | A maintainability-related issue in the code. Leaving it as-is means that at best maintainers will have a harder time than they should making changes to the code. At worst, they'll be so confused by the state of the code that they'll introduce additional errors as they make changes. | +| Cost | See Remediation Cost | +| Debt | See Technical Debt | +| Issue | When a piece of code does not comply with a rule, an issue is logged on the **snapshot**. An issue can be logged on a source file or a unit test file. There are 3 types of issue: **Bugs**, **Code Smells** and **Vulnerabilities** | +| Measure | The value of a **metric** for a given file or project at a given time. For example, 125 lines of code on class MyClass or density of duplicated lines of 30.5% on project myProject | +| Metric | A type of measurement. Metrics can have varying values, or **measures**, over time. Examples: number of lines of code, complexity, etc. A metric may be either _qualitative_ (gives a quality indication on the component, E.G. density of duplicated lines, line coverage by tests, etc.) or _quantitative_ (does not give a quality indication on the component, E.G. number of lines of code, complexity, etc.) | +| New Code Period | The period for which you're keeping a close watch on the introduction of new problems in the code. Ideally this is since the `previous_version`, but if you don't use a Maven-like versioning scheme you may need to set a relatively arbitrary time period such as 21 days or since a specific date. | +| Quality Profile | A set of **rules**. Each **snapshot** is based on a single quality profile. See also [Quality Profiles](/instance-administration/quality-profiles/) | +| Rule | A coding standard or practice which should be followed. Not complying with coding rules leads to **Bugs**, **Vulnerabilities**, **Security Hotspots**, and **Code Smells**. Rules can check quality on code files or unit tests. | +| Remediation Cost | The estimated time required to fix Vulnerability and Reliability Issues. | +| Snapshot | A set of **measures** and **issues** on a given project at a given time. A snapshot is generated for each analysis. | +| Security Hotspot | A security-related issue highlighting a piece of code that uses a security-sensitive API (E.G. use of a weak algorithm, connection to a database without a password, ...). Security hotspots must be reviewed by a security auditor who may determine that the APIs are used in ways that introduce Vulnerabilities. | +| Technical Debt | The estimated time required to fix all Maintainability Issues / code smells | +| Vulnerability | A security-related issue which represents a backdoor for attackers. See also [Security-related rules](/user-guide/security-rules/). | diff --git a/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md b/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md index be0a6b446fd..150d7fed8ba 100644 --- a/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md +++ b/server/sonar-docs/src/pages/user-guide/fixing-the-water-leak.md @@ -9,7 +9,7 @@ Imagine you come home one day to find a puddle of water on the kitchen floor. As Do you reach for the mop? Or do you try to find the source and fix it? The choice is obvious, right? You find the source of the leak! -So why do anything different with code quality? When you analyze an application with <!-- sonarqube -->SonarQube<!-- /sonarqube --><!-- sonarcloud -->SonarCloud<!-- /sonarcloud --> and realize that it has a lot of technical debt, the knee-jerk reaction is generally to start remediating – either that or put together a remediation plan. This is like mopping the floor once a day while ignoring the source of the water. +So why do anything different with code quality? When you analyze an application with {instance} and realize that it has a lot of technical debt, the knee-jerk reaction is generally to start remediating – either that or put together a remediation plan. This is like mopping the floor once a day while ignoring the source of the water. Typically in this traditional approach, just before release a periodic code quality audit result in findings the developers should act on before releasing. This approach might work in the short term, especially with strong management backing, but it consistently fails in the mid to long run, because: diff --git a/server/sonar-docs/src/pages/user-guide/issues.md b/server/sonar-docs/src/pages/user-guide/issues.md new file mode 100644 index 00000000000..c1d6dfae1d9 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/issues.md @@ -0,0 +1,147 @@ +--- +title: Issues +url: /user-guide/issues/ +--- + +## Table of Contents + +While running an analysis, {instance} raises an issue every time a piece of code breaks a coding rule. The set of coding rules is defined through the associated [quality profile](/instance-administration/quality-profiles/) for each language in the project. + +Each issue has one of five severities: + +1. **BLOCKER** +Bug with a high probability to impact the behavior of the application in production: memory leak, unclosed JDBC connection, .... The code MUST be immediately fixed. +1. **CRITICAL** +Either a bug with a low probability to impact the behavior of the application in production or an issue which represents a security flaw: empty catch block, SQL injection, ... The code MUST be immediately reviewed. +1. **MAJOR** +Quality flaw which can highly impact the developer productivity: uncovered piece of code, duplicated blocks, unused parameters, ... +1. **MINOR** +Quality flaw which can slightly impact the developer productivity: lines should not be too long, "switch" statements should have at least 3 cases, ... +1. **INFO** +Neither a bug nor a quality flaw, just a finding. + +Ideally, the team wouldn't introduce any new issues (any new technical debt). [SonarLint](https://sonarlint.org) can help developers because it provides the ability to perform local analyses to check their code before pushing it back to the SCM. But in real life, it's not always possible to code without any new technical debt, and sometimes it's not worth it. + +So new issues get introduced. + +## Understanding issue context +Sometimes, issues are self-evident once they're pointed out. For instance, if your team has agreed to a init-lower, camelCase variable naming convention, and an issue is raised on `My_variable`, you don't need a lot of context to understand the problem. But in other situations context may be essential to understanding why an issue was raised. That's why {instance} supports not just the primary issue location, where the issue message is shown, but also secondary issue locations. For instance, secondary issues locations are used to mark the pieces of code in a method which add Cognitive Complexity to a method. + +But there are times when a simple laundry list of contributing locations isn't enough to understand an issue. For instance, when a null pointer can be dereferenced on some paths through the code, what you really need are issue flows. Each flow is a _set_ of secondary locations ordered to show the exact path through the code on which a problem can happen. And because there can be multiple paths through the code on which, for instance a resource is not released, {instance} supports multiple flows. + + +## Lifecycle of Code Smell, Bug, and Vulnerability Issues +### Statuses +After creation, issues flow through a lifecycle, taking one of five possible statuses: + +* **Open** - set by {instance} on new issues +* **Confirmed** - set manually to indicate that the issue is valid +* **Resolved** - set manually to indicate that the next analysis should Close the issue +* **Reopened** - set automatically by {instance} when a Resolved issue hasn't actually been corrected +* **Closed** - set automatically by {instance} for automatically created issues. + +### Resolutions +Closed issues will have one of two resolutions: + +* **Fixed** - set automatically when a subsequent analysis shows that the issue has been corrected +* **Removed** - set automatically when either the related coding rule or the file is no longer available. The rule may not be available either because it has been removed from the profile or because the underlying plugin has been uninstalled. The file could be unavailable because it has been removed from the project, moved to a different location or renamed. + +Resolved issues will have one of two resolutions: +* **False Positive** - set manually +* **Won't Fix** - set manually + +### Issue Workflow +Issues are automatically closed (status: Closed) when: +* an issue (of any status) has been properly fixed => Resolution: Fixed +* an issue no longer exists because the related coding rule has been deactived or is no longer available (ie: plugin has been removed) => Resolution: Removed + +Issues are automatically reopened (status: Reopened) when: +* an issue that was manually Resolved as Fixed(but Resolution is not False positive) is shown by a subsequent analysis to still exist + +### Security Hotspot Issue Lifecycle +Security Hotspot issues have a dedicated lifecycle. They aren't considered actionable, and must be reviewed by a user with the "Administer Security Hotspots" permission. + +## Lifecycle of Security Hotspot Issues +Security Hotspot issues have a dedicated lifecycle. They aren't considered actionable, and must be reviewed by a user with the "Administer Security Hotspots" permission. + +### Statuses +After creation, Security Hotspot issues flow through a dedicated lifecycle, taking one of four possible statuses: + +* **Open** - set by {instance} on new issues +* **Resolved** (Won't Fix) - set automatically by {instance} when a Security Auditor Accepts the fix done by a developer on a Manual Vulnerability or when an Open Hotspot or Manual Vulnerability is Cleared by a Security Auditor. +* **To Review** - set automatically when a developer requests a security auditor to Review the fix she has done on a Manual Vulnerability +* **Reopened** - set when a developer Dismisses an Open Manual Vulnerability or when a Security Auditor manually reopens issues in order to run a new audit on already Resolved issues + +Security Hotspot issues are only ever closed if the code containing the Security Hotspot is deleted. A Security Hotspot may also become Removed if the rule which identified the hotspot is removed from the project's Quality Profile. + +## Understanding which Issues are "New" +To determine the creation date of an issue, an algorithm is executed during each analysis to determine whether an issue is new or existed previously. This algorithm relies on line content hashes (excluding whitespace) the issue is reported on. For multi-line issues, the hash of the first line is used. For each file (after detection of file renaming), the algorithm takes the base list of issues from the previous analysis, and tries to match those issues with the raw issue list reported by the new analysis. The algorithm tries to first match using the strongest evidence, and then falls back to weaker heuristics. + +* if the issue is on the same rule, with the same line number and with the same line hash (but not necessarily with the same message) > MATCH +* detect block move inside file, then if the issue is on the same (moved) line and on the same rule (but not necessarily with the same message) > MATCH +* on the same rule, with the same message and with the same line hash (but not necessarily with the same line) > MATCH +* on the same rule, with the same message and with the same line number (but not necessarily with the same line hash) > MATCH +* on the same rule and with the same line hash (but not the same message and not the same line) > MATCH +* is there a matching **CLOSED** issue > MATCH and Reopen + +Unmatched "base" issues are closed as fixed. + +Unmatched "raw" issues are new. + +## Automatic Issue Assignment +### For Bug, Vulnerability and Code Smell +New issues are automatically assigned during analysis to the last committer on the issue line if the committer can be correlated to a {instance} user. Note that currently, issues on any level above a file, e.g. directory / project, cannot be automatically assigned. + +### For Security Hotspot +Issues are automatically assigned only when the Security Hotspot is transformed into a Vulnerability through the "Detect" action. + +### User Correlation +Login and email correlations are made automatically. I.e. if the user commits with her email address and that email address is part of her {instance} profile, then new issues raised on lines where she was the last committer will be automatically assigned to her. + +Additional correlations can be made manually in the user's profile (see "SCM accounts" in Authorization for more). + +### Known Limitation +If the SCM login associated with an issue is longer than 255 characters allowed for an issue author, the author will be left blank. + +## Issue edits +{instance}'s issues workflow can help you manage your issues. There are seven different things you can do to an issue (other than fixing it in the code!): Comment, Assign, Confirm, Change Severity, Resolve, Won't Fix, and False Positive. + +These actions break out into three different categories. First up is the "technical review" category. + +### Technical Review +The Confirm, False Positive, Won't Fix, Severity change, and Resolve actions all fall into this category, which presumes an initial review of an issue to verify its validity. Assume it's time to review the technical debt added in the last review period - whether that's a day, a week, or an entire sprint. You go through each new issue and do one: + +* **Confirm** - By confirming an issue, you're basically saying "Yep, that's a problem." Doing so moves it out of "Open" status to "Confirmed". +* **False Positive** - Looking at the issue in context, you realize that for whatever reason, this issue isn't actually a problem. So you mark it False Positive and move on. Requires Administer Issues permission on the project. +* **Won't Fix** - Looking at the issue in context, you realize that while it's a valid issue it's not one that actually needs fixing. In other words, it represents accepted technical debt. So you mark it Won't Fix and move on. Requires Administer Issues permission on the project. +* **Severity change** - This is the middle ground between the first two options. Yes, it's a problem, but it's not as bad a problem as the rule's default severity makes it out to be. Or perhaps it's actually far worse. Either way, you adjust the severity of the issue to bring it in line with what you feel it deserves. Requires Administer Issues permission on the project. +* **Resolve** - If you think you've fixed an open issue, you can Resolve it. If you're right, the next analysis will move it to closed status. If you're wrong, its status will go to re-opened. + +Additionally, Security Hotspots allow the following: + +* **Detect** - Confirms a Security Hotspot as a true issue and manually opens a Vulnerability. Requires Administer Security Hotspots on the project. +* **Clear** - Marks a Security Hotspot or manually opened Vulnerability as being without issue and shouldn't be fixed. Requires Administer Security Hotspots on the project. +* **Request Review** - Request that a Security Auditor review changes made to remediate a manually opened Vulnerability. +* **Reject** - After review ,reject the remediation for a manually opened Vulnerability and return it to an open issue. Requires Administer Security Hotspots on the project. + +If you tend to mark a lot of issues False Positive or Won't Fix, it means that some coding rules are not appropriate for your context. So, you can either completely deactivate them in the quality profile or use issue exclusions to narrow the focus of the rules so they are not used on specific parts (or types of object) of your application. Similarly, making a lot of severity changes should prompt you to consider updating the rule severities in your profiles. + +As you edit issues, the related metrics (e.g. New Bugs), will update automatically, as will the Quality Gate status if it's relevant. + +### Dispositioning +Once issues have been through technical review, it's time to decide who's going to deal them. By default they're assigned to the last committer on the issue line (at the time the issue is raised), but you can certainly reassign them to yourself or someone else. The assignee will receive email notification of the assignment if he signed up for notifications, and the assignment will show up everywhere the issue is displayed, including in the My Issues list in the My Account space. + +### General +At any time during the lifecycle of an issue, you can log a comment on it. Comments are displayed in the issue detail in a running log. You have the ability to edit or delete the comments you made. + +You can also edit an issue's tags. Issues inherit the tags of the rules that created them, but the tag set on an issue is fully editable. Tags can be created, added and removed at will for users with the Browse permission on the project. + +Although they are initially inherited from the relevant rule, the tags on an issue are not synchronized with the rule, so adding tags to a rule will not add those tags to the rule's issues. + +### Bulk Change +All of these changes and more can be made to multiple issues at once using the Bulk Change option in the issues search results pane. + + +## Purging Closed Issues +By default, Closed issues are kept for 30 days. For more details, see [Housekeeping](/instance-administration/housekeeping/). + diff --git a/server/sonar-docs/src/pages/user-guide/portfolios.md b/server/sonar-docs/src/pages/user-guide/portfolios.md new file mode 100644 index 00000000000..963392a39d1 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/portfolios.md @@ -0,0 +1,54 @@ +--- +title: Portfolios +url: /user-guide/portfolios/ +--- + +*Portfolios are available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html).* + +### Portfolios Home Page + +The Portfolio Home Page is the central place for managers and tech leads to keep an eye on the Releasability of the projects under their supervision. Releasability is based on the project's quality gate: green or orange (pass or warning) is releasable. Red (error) is not. Each Portfolio home page offers an aggregate view of the releasability of all the projects in the Portfolio. + +At the top of the page, you can easily see whether overall Portfolio is currently rated as releasable and if any projects in the Portfolio have failed their Quality Gate. And the Reliability, Security, and Maintainability ratings show the overall health of the Portfolio in these three domains, along with an indicator of the worst-performing project(s) in each domain. + +For each domain you see: + +* the rating (see [Metric Definitions](/user-guide/metric-definitions/) for more details about how they are computed) +* an indicator of when the rating last changed +* an indicator of the worst-performing project(s) in the domain + +### Releasability Rating + +The Releasability Rating tells you the ratio of projects in the Portfolio that do NOT have a **FAILED** Quality Gate (ie QG being **PASSED** or **WARNING**) : + +**A**: > 80% +**B**: > 60% +**C**: > 40% +**D**: > 20% +**E**: <= 20% + +### Reliability, Security and Maintainability Ratings + +Each of the Reliability, Security and Maintainability Ratings for a Portfolio is calculated as the average of the ratings for all projects included in the Portfolio. SonarQube converts the rating for each project to a number (see conversion table below), calculates an average for the portfolio and converts that average back to a rating. Averages that land exactly on the 0.5 mark are rounded up (i.e. the result is the "lower" of the two possible ratings, so an average of 2.5 would result in a "C" rating). + +This gives an “issue density" measure on the three axes of Reliability, Security and Maintainability for your Portfolio. + +Rating conversion: + +**E**: 5 +**D**: 4 +**C**: 3 +**B**: 2 +**A**: 1 + +*Note: the Portfolio Home Page is also available at Sub-Portfolio level* + +### Print as PDF or Subscribe + +On a Portfolio Home Page you can choose to download an overview of the Portfolio as a PDF. To do that, simply click on the "Print as PDF" button. This is really convenient, for example, if you're going into a meeting where you may not have access to your SonarQube instance. + +If you don't want to perform this action every time, you can subscribe to receive the PDF by email. The frequency of the mailing is decided by the administrator of the Portfolio. + +Please note you will receive the PDF only if the Portfolio is computed. + +Portfolios are created and edited in the global Portfolio administration interface: **Administration > Configuration > Portfolios**. For more information, see [Configuring Portfolios and Applications](/project-administration/configuring-portfolios-and-applications/). diff --git a/server/sonar-docs/src/pages/user-guide/project-page.md b/server/sonar-docs/src/pages/user-guide/project-page.md new file mode 100644 index 00000000000..53be937127a --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/project-page.md @@ -0,0 +1,56 @@ +--- +title: Project Page +url: /user-guide/project-page/ +--- + +## Table of Contents + + +The Project Hompepage is the entry point of any project showing: +* the releasability status of the project +* the current state of its quality +* the quality of what has been produced since the beginning of its [New Code Period](/user-guide/fixing-the-water-leak/). + + +The Project Page answers two questions: +* can I release my project today? +* if not, what should I improve to make the project pass the Quality Gate? + +## Can I release today? + +Since the [Quality Gate](/user-guide/quality-gates/) is your most powerful tool to enforce your quality policy, the page starts with the project's current Quality Gate status. If the project passes, a simple, green all-clear is shown. + +If not, details and drill-downs are immediately available to quickly identify what went wrong, with a section for each error or warning condition showing what the current project value is and what it should be. As usual, you'll be able to click through on current values to get to drilldowns. + +## What should I fix first? +Because the best way to improve a project's quality is to catch and fix new problems before they become entrenched, the first view of a project is centered around the New Code Period, which is highlighted in yellow on the right of the project homepage. The project space page shows a high-level summary of critical metrics, both current values and their New Code Period values. + +Just below the Quality Gate information, you have the numbers of old and new Issues in the Reliability and Security domains and then the Maintainability domain. Clicking on any figure on the page will take you to a detailed view, either in the Measures Page or the Issues Page. + +The most important thing a developer must do is to ensure the new Issues in the yellow part of the screen are acknowledged, reviewed and fixed and to make sure that new code is covered by tests to help prevent future regressions. Regardless of how many Issues were introduced in the past or how little test coverage there is overall, a focus on the newly added Issues will ensure that the situation won't degrade versus the version you previously released in production. + +So, which issues should you go after first: Bugs, Vulnerabilities or Code Smells? It depends, because the answer is dependent on the nature of your Issues. Let's say you have issues for a block of code that is duplicated 5 times, and inside this duplicated block of code, you have 3 Bugs and 5 Security Issues. The best approach is probably to fix the duplication first and then resolve the Bugs and Vulnerabilities in the newly centralized location, rather than fixing them 5 times. + +That's why you need to review your new Issues before jumping into resolving them. + +## How can I ... +### How can I see project measures at a lower level? +The project-level **Measures** menu item takes you to a dedicated sub-space where you see all project measures. Choose a measure for more details. Both list and tree views are available for each measure, and treemaps are available for percentages and ratings. + +### How can I see all the issues in a project? +The project-level **Issues** menu item takes you to a project-specific Issues page, where you can perform all the same actions you can at the higher level. +On this page, you can easily narrow the list to the New Issues introduced during the New Code Period, by selecting `New Code` in **Creation Date** facet. + +### How can I see the project structure and code? +The project-level **Code** menu item takes you to an outline of your project structure. Drill down to see files in a directory, and choose a file to see its code. + +If your project is too large for easy exploration via drilling, the search feature on this page will help. While the global search in the main menu returns results from throughout the {instance} instance, the localized search on the code page is restricted to files and directories in the current project. + +### How can I see the project activity / history? +The project-level **Activity** menu item takes you to the full list of code scans performed on your project since it was created in {instance}. By going there you can follow the evolution of the Quality Gate, see the changes of Quality Profiles and know when a given version of your code has been scanned. + +### How can I easily spot the risks in a project? +Visualizations allow you to compare project components and quickly spot the ones that represent the greatest risks. The **Activity** page offers several pre-defined visualizations, and you can also create Custom visualizations with the metrics of your choice. + +### How can I promote the health of my project to peers ? +If your project is publicly visible, then you can further promote its status in external tools and websites using native Project Badges. The **Get project badges** button on the homepage of a public project lets you choose/fine-tune your badge and gives you the URL for it. diff --git a/server/sonar-docs/src/pages/user-guide/quality-gates.md b/server/sonar-docs/src/pages/user-guide/quality-gates.md index 8d422fbc151..9dbb7a7b7c0 100644 --- a/server/sonar-docs/src/pages/user-guide/quality-gates.md +++ b/server/sonar-docs/src/pages/user-guide/quality-gates.md @@ -24,7 +24,7 @@ Which is why you can define as many quality gates as you wish. Quality Gates are ## Use the Best Quality Gate Configuration -The quality gate "Sonar way" is provided by SonarSource, activated by default and considered as built-in and so read-only. It represents our view of the best way to implement the [Fixing the Water Leak](/user-guide/fixing-the-water-leak/) concept. At each SonarQube release, we adjust automatically this default quality gate according to SonarQube's capabilities. +The quality gate "Sonar way" is provided by SonarSource, activated by default and considered as built-in and so read-only. It represents our view of the best way to implement the [Fixing the Water Leak](/user-guide/fixing-the-water-leak/) concept. <!-- sonarqube -->At each SonarQube release, we adjust automatically this default quality gate according to SonarQube's capabilities.<!-- /sonarqube --> Three metrics allow you to enforce a given Rating of Reliability, Security and Maintainability, not just overall but also on new code. These metrics are recommended and come as part of the default quality gate. We strongly advise you to adjust your own quality gates to use them to make feedback more clear to your developers looking at their quality gate on their project page. diff --git a/server/sonar-docs/src/pages/user-guide/rules.md b/server/sonar-docs/src/pages/user-guide/rules.md new file mode 100644 index 00000000000..0ce505b6d90 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/rules.md @@ -0,0 +1,138 @@ +--- +title: Rules +url: /user-guide/rules/ +--- +## Table of Contents + +## Overview +In {instance}, analyzers contribute rules which are executed on source code to generate issues. There are four types of rules: +* Code Smell (Maintainability domain) +* Bug (Reliability domain) +* Vulnerability (Security domain) +* Security Hotspot (Security domain) + +For Code Smells and Bugs, zero false-positives are expected. At least this is the target so that developers don't have to wonder if a fix is required. + +For Vulnerabilities, the target is to have more than 80% of the issues to be true-positives. + +Security Hotspot rules are purposefully designed to draw attention to code is security-sensitive. It is expected that more than 80% of the issues will be quickly resolved as "Won't Fix" after review by a Security Auditor. + +The Rules page is the entry point where you can discover all the existing rules or create new ones based on provided templates. + +## Rules + +By default, when entering the top menu item "Rules", you will see all the available rules brought by the analyzers <!-- sonarqube -->installed on your {instance} instance<!-- /sonarqube --><!-- sonarcloud -->available on SonarCloud<!-- /sonarcloud -->. You have the ability to narrow the selection based on search criteria in the left pane: + +* **Language**: the language to which a rule applies. +* **Type**: Bug, Vulnerability, Code Smell or Security Hotspot rules. +* **Tag**: it is possible to add tags to rules in order to classify them and to help discover them more easily. +* **Repository**: the engine/analyzer that contributes rules to {instance}. +* **Default Severity**: the original severity of the rule - as defined by the analyzer that contributes this rule. +* **Status**: rules can have 3 different statuses: + * **Beta**: The rule has been recently implemented and we haven't gotten enough feedback from users yet, so there may be false positives or false negatives. + * **Deprecated**: The rule should no longer be used because a similar, but more powerful and accurate rule exists. + * **Ready**: The rule is ready to be used in production. +* **Available Since**: date when a rule was first added on {instance}. This is useful to list all the new rules since the last upgrade of a plugin for instance. +* **Template**: display rule templates that allow to create custom rules (see later on this page). +* **Quality Profile**: inclusion in or exclusion from a specific profile + +If a quality profile is selected, it is also possible to check for its active severity and whether it is inherited or not. See the Quality Profile documentation for more. + +## Rule Details + +To see the details of a rule, either click on it, or use the right arrow key. Along with basic rule data, you'll also be able to see which, if any, profiles it's active in and how many open issues have been raised with it. + +The 2 following actions are available only if you have the right permissions ("Administer Quality Profiles and Gates"): + +* **Add/Remove Tags**: + * It is possible to add existing tags on a rule, or to create new ones (just enter a new name while typing in the text field). + * Note that some rules have built-in tags that you cannot remove - they are provided by the plugins which contribute the rules. +* **Extend Description**: + * Extending rule descriptions is useful to let users know how your organization is using a particular rule for instance or to give more insight on a rule. + * Note that the extension will be available to non-admin users as a normal part of the rule details. + +<!-- sonarqube --> +## Rule Templates and Custom Rules + +Rule Templates are provided by plugins to allow users to define their own rules in {instance}. For instance, the template "Architectural Constraint" can be used to create any kind of rule that checks forbidden access from a set of file to another set of files. + +Rule templates are like cookie cutters from which you can stamp out new, "custom rules". To find templates, use the template facet: + + + +To create a custom rule from a template, you will have to fill the following information: +* Name +* Key (auto-suggested) +* Description (Markdown format is supported) +* Default Severity +* Status +* The parameters specified by the template + +It's easy to navigate from a template to the custom rules defined from it: just click on the link in the "Custom Rules" section and you will end up on the details of the given rule. + + + +### Custom Rules +Custom Rules are considered like any other rule, except that they can be fully edited or even deleted: + + + +Note that when deleting a custom rule, it is not physically removed from the {instance} instance but rather its status is set to "REMOVED". This allows current or old issues related to this rule to be displayed properly in {instance} until they are fully removed. + +## Extending Coding Rules + +Custom coding rules can be added. See [Adding Coding Rules](https://docs.sonarqube.org/display/DEV/Adding+Coding+Rules) for detailed information and tutorials. +<!-- sonarqube --> + +## Rule Types and Severities + +### How are rules categorized? + +The {instance} Quality Model divides rules into four categories: Bugs, Vulnerabilities, Security Hotspots and Code Smells. Rules are assigned to categories based on the answers to these questions: + +**Is the rule about code that is demonstrably wrong, or more likely wrong than not?** +If the answer is "yes", then it's a Bug rule. +If not... + +**Is the rule about code that could be exploited by a hacker?** +If so, then it's a Vulnerability rule. +If not... + +**Is the rule about code that is security-sensitive?** +If so, then it's a Security Hotspot rule. +If not... + +**Is the rule neither a Bug nor a Vulnerability?** +If so, then it's a Code Smell rule. + +## How are severities assigned? +To assign severity to a rule, we ask a further series of questions. The first one is basically: + +**What's the worst thing that could happen?** + +In answering this question, we try to factor in Murphy's Law without predicting Armageddon. + +Then we assess whether the impact and likelihood of the Worst Thing (see _How are severity and likelihood decided?_, below) are high or low, and plug the answers into a truth table: + +| | Impact | Likelihood | +| -------- | ---------------------- | ---------------------- | +| Blocker |  |  | +| Critical |  |  | +| Major |  |  | +| Minor |  |  | + +## How are severity and likelihood decided? +To assess the severity of a rule, we start from the Worst Thing (see _How are severities assigned?_, above) and ask category-specific questions. + +### Bugs +Impact: **Could the Worst Thing cause the application to crash or to corrupt stored data?** + +Likelihood: **What's the probability that the Worst Thing will happen?** + +### Vulnerabilities +Impact: **Could the exploitation of the Worst Thing result in significant damage to your assets or your users?** + +Likelihood: **What is the probability that a hacker will be able to exploit the Worst Thing?** + +### Security Hotspots +Security Hotspots are not assigned severities as it is unknown whether there is truly an issue until review by a Security Auditor. When an auditor converts a Security Hotspot into a Vulnerability, severity is assigned based on the identified Vulnerability (see above). diff --git a/server/sonar-docs/src/pages/user-guide/security-reports.md b/server/sonar-docs/src/pages/user-guide/security-reports.md index f25d69c2aa1..e2ca757b20a 100644 --- a/server/sonar-docs/src/pages/user-guide/security-reports.md +++ b/server/sonar-docs/src/pages/user-guide/security-reports.md @@ -16,6 +16,9 @@ Security Hotspots are security-sensitive pieces of code that should be carefully The main goal of Security Hotspots is to help focus the efforts of the security auditors who manually review application source code. The second goal is to educate developers and to increase their security-awareness. Having a Hotspot in your application does not mean there is a problem. What it does mean is that a human, preferably a security auditor/expert should look over the code to see if the sensitive piece of code is being used in the safest manner. +## Why are some Hotspot and Vulnerability rules very similar? +They are overlapping on purpose. The Hotspot rule is supposed to include all matches of the Vulnerability rules, and cases where the taint analysis engine is not able to detect vulnerabilities. For example, switching from one language to another (XML, JNI, etc...) or using some third party libraries will prevent the taint analysis from finding vulnerabilities. A Vulnerability rule highlights security threats only when it has a high level of confidence, which means that it will always miss some of them. Whereas a Hotspot rule guides secure code reviews by showing code where those issues might lurk, even if it could not detect any vulnerability. + ## Why don't I see any Hotspots? They are three reasons you might not see any Hotspots: * it is possible you really have none of them because the code has been written without using any security-sensitive API. diff --git a/server/sonar-docs/src/pages/user-guide/security-rules.md b/server/sonar-docs/src/pages/user-guide/security-rules.md new file mode 100644 index 00000000000..b917bde76c7 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/security-rules.md @@ -0,0 +1,59 @@ +--- +title: Security-related Rules +url: /user-guide/security-rules/ +--- +The {instance} Quality Model has three different types of rules: Reliability (bug), Vulnerability (security), and Maintainability (code smell) rules. But divided another way, there are only two types: security rules, and all the rest. The distinction between these two groups is not so much in what they catch but in where they come from and in the standards imposed on them. + +## What to expect from security-related rules +To be clear, the standard for most rules implemented in {instance} language plugins is very strict: no false positives. For normal rules, you should be able to be confident that whatever is reported to you as an issue really is an issue. + +But for security-related rules, the story is a little different. For instance, a lot of security guidelines talk about how "sensitive" data should be handled (e.g. not logged, not stored un-encrypted, &etc.). But since it's not really possible in a rule to tell which data is sensitive and which isn't, the choice becomes: maintain the no-false-positives standard and don't implement security-related rules, or implement security-related rules with a different standard. + +That's why security-related rules cast a wider net than you may be used to seeing. The idea is that the rule will flag anything suspicious, and leave it to the human security auditor to cull the false positives and sent the real issues for remediation. + +Security Hotspots are a special type of issue that identify sensitive areas of code that should be reviewed by a Security Auditor to determine if they are truly Vulnerabilities. See Security Audits and Reports for detail on Security Hotspots and the audit process. + +## Where security-related rules come from +The vast majority of security-related rules originate from established standards: [CWE](http://cwe.mitre.org/), [SANS Top 25](http://www.sans.org/top25-software-errors/), and [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10). To find rules that relate to any of these standards, you can search rules either by tag or by text. The standards that a rule relates to will be listed in the **See** section at the bottom of the rule description. + +### CWE +CWE stands for Common Weakness Enumeration. According to the [CWE FAQ](http://cwe.mitre.org/about/faq.html#A.1): + +> Common Weakness Enumeration (CWE™) is a formal list or dictionary of common software weaknesses that can occur in software's architecture, design, code or implementation that can lead to exploitable security vulnerabilities. CWE was created to serve as a common language for describing software security weaknesses; serve as a standard measuring stick for software security tools targeting these weaknesses; and to provide a common baseline standard for weakness identification, mitigation, and prevention efforts. + +The CWE is a hierarchy of weakness descriptions. The lowest level in the hierarchy is a "Weakness Base", which describes a granular weakness. Above Weakness Bases, are Weakness Classes and Categories. In general, rules are linked to Weakness Bases or Classes. + +Tools which meet certain requirements can be certified as [CWE Compatible](http://cwe.mitre.org/compatible/). Those requirements are: + +* You must be able to search for CWE-related rules using a CWE identifier. To do so in the {instance} platform, simply drop the CWE identifier (e.g. CWE-595) in the search text input on the rules page and run the search. +* Rules must be accurately linked to their related CWE items. To see the CWE mapping for a {instance} rule, consult the rule's See section at the bottom of the rule description. +* You must be able to identify the relevant CWE from an Issue. To do so in the {instance} platform, consult the related rule. +* The product documentation must include a description of CWE and CWE Compatibility. +* The version of CWE supported must be listed. The {instance} langauge plugins support version 2.8. +* In addition to searching rules by CWE id's, you can also search by the "cwe" rule tag. + +To see which CWE items are covered for a language, consult the links below. + +* [C](https://rules.sonarsource.com/c/tag/cwe)/[C++](https://rules.sonarsource.com/cpp/tag/cwe) +* [Java](https://rules.sonarsource.com/java/tag/cwe) +* [Objective-C](https://rules.sonarsource.com/objective-c/tag/cwe) + + +### SANS Top 25 + +The [SANS Top 25](http://www.sans.org/top25-software-errors/) list is a collection of the 25-most dangerous errors listed in the CWE, as compiled by the [SANS organization](http://www.sans.org/). The current SANS list is divided into three categories: Insecure Interaction Between Components, Risky Resource Management, and Porous Defenses. + +The tags used for SANS correspond to its categories: sans-top25-insecure, sans-top25-risky, sans-top25-porous. + +To find rules relating to SANS Top 25, you can perform a text search for the category, or the relevant CWE item, or perform a rule tag search. + +### OWASP Top 10 +OWASP stands for Open Web Application Security Project. According to its site, it is: + +> A [501(c)(3)](http://www.irs.gov/Charities-&-Non-Profits/Charitable-Organizations/Exemption-Requirements-Section-501(c)(3)-Organizations) worldwide not-for-profit charitable organization focused on improving the security of software. Our mission is to make software security [visible](https://www.owasp.org/index.php/Category:OWASP_Video), so that [individuals and organizations](https://www.owasp.org/index.php/Industry:Citations) worldwide can make informed decisions about true software security risks. + +The [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10) is a list of broad categories of weaknesses, each of which can map to many individual rules. + +The tags used for OWASP correspond to the weakness categories: owasp-a1, owasp-a2, owasp-a3, owasp-a4, owasp-a5, owasp-a6, owasp-a7, owasp-a8, owasp-a9, owasp-a10. + +To find rules relating to OWASP Top 10, you can perform a text search for the category, or perform a rule tag search. diff --git a/server/sonar-docs/src/pages/user-guide/sonarlint-notifications.md b/server/sonar-docs/src/pages/user-guide/sonarlint-notifications.md new file mode 100644 index 00000000000..ae2437635c0 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/sonarlint-notifications.md @@ -0,0 +1,19 @@ +--- +title: SonarLint Smart Notifications +url: /user-guide/sonarlint-notifications/ +--- +<!-- sonarqube --> +_SonarLint Smart Notifications is available as part of the [Developer Edition](https://redirect.sonarsource.com/editions/developer.html)._ +<!-- /sonarqube --> + +Smart notifications allow developers using Connected Mode in SonarLint to receive in-IDE notifications from {instance} when: + +* the Quality Gate status (failed / success / warning) of a project /solution _open in the IDE_ changes +* a {instance} analysis raises new issues _introduced by this developer in a project /solution open in the IDE_ + +## Activate/deactivate Notifications +The activation or deactivation of notifications must be done individually, by each developer directly in SonarLint (on the IDE side). + +<!-- sonarqube --> +Receiving notifications is configurable on the SonarLint side on a {instance} server-by-server basis. +<!-- /sonarqube --> diff --git a/server/sonar-docs/src/pages/user-guide/user-account.md b/server/sonar-docs/src/pages/user-guide/user-account.md index 935823eda08..636279f7e60 100644 --- a/server/sonar-docs/src/pages/user-guide/user-account.md +++ b/server/sonar-docs/src/pages/user-guide/user-account.md @@ -14,7 +14,7 @@ It gives you a summary of: ## Security -In addition to being able to change your password, if your instance is not using a 3rd party authentication mechanism such as LDAP or any OAuth provider (GitHub, Google Account, ...), you can manage your own authentication tokens. +If <!-- sonarqube -->your instance is<!-- /sonarqube --> <!-- sonarcloud -->you are<!-- /sonarcloud --> not using a 3rd party authentication mechanism such as <!-- sonarqube -->LDAP or<!-- /sonarqube --> an OAuth provider (GitHub, Google Account, ...), you can change your password from here. Additionally, you can also manage your own authentication tokens. -You can create as many Token as you want. Once a Token is created, you can use it to publish analysis to a project where you have the execute analysis permission. +You can create as many Tokens as you want. Once a Token is created, you can use it to perform analysis on a project where you have the [Execute Analysis](/instance-administration/security/) permission. diff --git a/server/sonar-docs/src/pages/user-guide/user-token.md b/server/sonar-docs/src/pages/user-guide/user-token.md new file mode 100644 index 00000000000..a610837f7b4 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/user-token.md @@ -0,0 +1,21 @@ +--- +title: User Token +url: /user-guide/user-token/ +--- + +Each user has the ability to generate tokens that can be used to run analyses or invoke web services without access to the user's actual credentials. + +## How to Generate a Token + +To generate a token, to go **User > My Account > Security**. Your existing tokens are listed here, each with a Revoke button. + +The form at the bottom of the page allows you to generate new tokens. Once you click the **Generate** button, you will see the token value. Copy it immediately; once you dismiss the notification you will not be able to retrieve it. + +## How to Use a Token + +User tokens have to be used as a replacement of your usual login: + +* when running analyses on your code: replace your login by the token in the `sonar.login` property. +* when invoking web services: just pass the token instead of your login while doing the basic authentication. + +In both cases, you don't need to provide a password (so when running analyses on your code, the property `sonar.password` is optional). diff --git a/server/sonar-docs/src/pages/user-guide/visualizations.md b/server/sonar-docs/src/pages/user-guide/visualizations.md new file mode 100644 index 00000000000..db83f6570e5 --- /dev/null +++ b/server/sonar-docs/src/pages/user-guide/visualizations.md @@ -0,0 +1,23 @@ +--- +title: Visualizations +url: /user-guide/visualizations/ +--- +Visualizations are available to help you gain deeper insights into your projects' current statuses and histories. + +## How do I compare current state for multiple projects or project components? +The Projects space allows you to filter the projects in your instance by multiple, measure-based criteria. Once you've chosen your set, you don't have to stare at the raw numbers to identify the risks its projects face. Instead, several visualizations (**Projects > Perspective**) are available to help you understand each project's relative position in terms of each of the major axes: + +* Risk - Reliability and Security ratings, test coverage, technical debt, and lines of code +* Reliability - Reliability rating, Reliability remediation effort, lines of code, and Bug count +* Security - Security rating, Security remediation effort, lines of code, and Vulnerability count +* Maintainability - Maintainability rating, Technical debt, lines of code, and Code Smell count +* Coverage - Coverage, complexity, and uncovered lines +* Duplications - Duplicated Lines %, lines of code, and duplicated blocks +* At the project level these same visualizations are available in the Measures tab to help you compare project components. The Project Overview corresponds to the Risk visualization in the Projects space, For the other five graphs, choose the Overview option under the relevant domain. + +Additionally, treemaps are also available for percentage and rating metrics at the project level. Navigate to them in the Measures tab using the perspective selector in the right pane. + +## How do I visualize metric history? +At the project level, the Activity tab offers several canned line graphs of selected metrics across time, with convenient mouseovers to show graph details and the ability to easily narrow the graph to a slice of the project's history. Beyond the canned graphs, you also have the ability to map the metrics of your choice against each other in a Custom graph. + + diff --git a/server/sonar-docs/src/tooltips/branches/single-branch.md b/server/sonar-docs/src/tooltips/branches/single-branch.md index fc0398cc77e..b0da9b6f467 100644 --- a/server/sonar-docs/src/tooltips/branches/single-branch.md +++ b/server/sonar-docs/src/tooltips/branches/single-branch.md @@ -1,4 +1,4 @@ -**Learn how to analyze branches in SonarQube** +**Learn how to analyze branches in {instance}** Quickly setup branch analysis and get separate insights for each of your branches and pull requests. diff --git a/server/sonar-docs/static/SonarCloudNavigationTree.json b/server/sonar-docs/static/SonarCloudNavigationTree.json index 0b2a38005a1..5c29c5eaf0e 100644 --- a/server/sonar-docs/static/SonarCloudNavigationTree.json +++ b/server/sonar-docs/static/SonarCloudNavigationTree.json @@ -1,24 +1,24 @@ [ - "/privacy/", - "/security/", - "/sonarcloud-pricing/", - "/analyze-a-project/", + { + "title": "Get Started", + "children": [ + "/integrations/github/", + "/integrations/bitbucketcloud/", + "/integrations/vsts/" + ] + }, { "title": "Analyzing Source Code", "children": [ "/analysis/overview/", + "/analysis/analysis-parameters/", "/analysis/background-tasks/", "/analysis/generic-issue/", "/analysis/generic-test/", - "/analysis/pull-request/", - "/analysis/scm-integration/" + "/analysis/pull-request/" ] }, { - "title": "Integrations", - "children": ["/integrations/bitbucketcloud/", "/integrations/github/", "/integrations/vsts/"] - }, - { "title": "Branches", "children": [ "/branches/overview/", @@ -31,24 +31,45 @@ "title": "User Guide", "children": [ "/user-guide/fixing-the-water-leak/", - "/user-guide/keyboard-shortcuts/", + "/user-guide/project-page/", + "/user-guide/issues/", + "/user-guide/rules/", + "/user-guide/security-rules/", + "/user-guide/built-in-rule-tags/", "/user-guide/quality-gates/", "/instance-administration/quality-profiles/", "/user-guide/metric-definitions/", + "/user-guide/concepts/", + "/user-guide/activity-history/", + "/user-guide/visualizations/", + "/user-guide/sonarlint-notifications/", "/user-guide/security-reports/", - "/user-guide/user-account/" + "/user-guide/user-token/", + "/user-guide/keyboard-shortcuts/" ] }, { - "title": "Project Administration", - "children": ["/project-administration/webhooks/"] + "title": "Project Admin Guide", + "children": [ + "/project-administration/webhooks/", + "/project-administration/narrowing-the-focus/" + ] }, { - "title": "Organizations", + "title": "Organization Admin Guide", "children": [ "/organizations/overview/", "/organizations/manage-team/", "/organizations/organization-visibility/" ] + }, + { + "title": "Appendices", + "children": [ + "/sonarcloud-pricing/", + "/privacy/", + "/security/", + "/faq/" + ] } ] diff --git a/server/sonar-docs/static/SonarQubeNavigationTree.json b/server/sonar-docs/static/SonarQubeNavigationTree.json index 1d047f5936c..c1a53ae18ce 100644 --- a/server/sonar-docs/static/SonarQubeNavigationTree.json +++ b/server/sonar-docs/static/SonarQubeNavigationTree.json @@ -1,8 +1,17 @@ [ { + "title": "Requirements", + "children": [ + "/requirements/requirements/", + "/requirements/benchmark/", + "/requirements/hardware-recommendations/" + ] + }, + { "title": "Analyzing Source Code", "children": [ "/analysis/overview/", + "/analysis/analysis-parameters/", "/analysis/background-tasks/", "/analysis/generic-issue/", "/analysis/generic-test/", @@ -23,24 +32,55 @@ "title": "User Guide", "children": [ "/user-guide/fixing-the-water-leak/", - "/user-guide/keyboard-shortcuts/", + "/user-guide/project-page/", + "/user-guide/applications/", + "/user-guide/portfolios/", + "/user-guide/issues/", + "/user-guide/rules/", + "/user-guide/security-rules/", + "/user-guide/built-in-rule-tags/", "/user-guide/quality-gates/", "/user-guide/metric-definitions/", + "/user-guide/concepts/", + "/user-guide/activity-history/", + "/user-guide/visualizations/", + "/user-guide/sonarlint-notifications/", "/user-guide/security-reports/", - "/user-guide/user-account/" + "/user-guide/user-account/", + "/user-guide/user-token/", + "/user-guide/keyboard-shortcuts/" ] }, { "title": "Project Administration", - "children": ["/project-administration/webhooks/"] + "children": [ + "/project-administration/project-existence/", + "/project-administration/managing-project-history/", + "/project-administration/narrowing-the-focus/", + "/project-administration/configuring-portfolios-and-applications/", + "/project-administration/portfolio-pdf-configuration/", + "/project-administration/project-settings/", + "/project-administration/webhooks/" + ] }, { "title": "Instance Administration", "children": [ - "/instance-administration/custom-measures/", - "/instance-administration/housekeeping/", + "/instance-administration/quality-profiles/", + "/instance-administration/security/", + "/instance-administration/delegated-auth/", "/instance-administration/look-and-feel/", - "/instance-administration/quality-profiles/" + "/instance-administration/marketplace/", + "/instance-administration/housekeeping/", + "/instance-administration/notifications/", + "/instance-administration/system-info/", + "/instance-administration/monitoring/", + "/instance-administration/project-move/", + "/instance-administration/custom-measures/", + "/instance-administration/compute-engine-performance/", + "/instance-administration/db-copy/" ] - } + }, + "/faq/" + ] diff --git a/server/sonar-docs/static/StaticNavigationTree.json b/server/sonar-docs/static/StaticNavigationTree.json index ffbac954d82..887b04235eb 100644 --- a/server/sonar-docs/static/StaticNavigationTree.json +++ b/server/sonar-docs/static/StaticNavigationTree.json @@ -1,16 +1,33 @@ [ + "/architecture/architecture-integration/", { "title": "Requirements", - "children": [] + "children": [ + "/requirements/requirements/", + "/requirements/benchmark/", + "/requirements/hardware-recommendations/" + ] }, { "title": "Setup and Upgrade", - "children": [] + "children": [ + "/setup/overview/", + "/setup/get-started-2-minutes/", + "/setup/install-server/", + "/setup/operate-server/", + "/setup/install-plugin/", + "/setup/install-cluster/", + "/setup/operate-cluster/", + "/setup/upgrading/", + "/setup/upgrade-notes/", + "/setup/troubleshooting/" + ] }, { "title": "Analyzing Source Code", "children": [ "/analysis/overview/", + "/analysis/analysis-parameters/", "/analysis/background-tasks/", "/analysis/generic-issue/", "/analysis/generic-test/", @@ -31,24 +48,65 @@ "title": "User Guide", "children": [ "/user-guide/fixing-the-water-leak/", - "/user-guide/keyboard-shortcuts/", + "/user-guide/project-page/", + "/user-guide/applications/", + "/user-guide/portfolios/", + "/user-guide/issues/", + "/user-guide/rules/", + "/user-guide/security-rules/", + "/user-guide/built-in-rule-tags/", "/user-guide/quality-gates/", "/user-guide/metric-definitions/", + "/user-guide/concepts/", + "/user-guide/activity-history/", + "/user-guide/visualizations/", + "/user-guide/sonarlint-notifications/", "/user-guide/security-reports/", - "/user-guide/user-account/" + "/user-guide/user-account/", + "/user-guide/user-token/", + "/user-guide/keyboard-shortcuts/" ] }, { "title": "Project Administration", - "children": ["/project-administration/webhooks/"] + "children": [ + "/project-administration/project-existence/", + "/project-administration/managing-project-history/", + "/project-administration/narrowing-the-focus/", + "/project-administration/configuring-portfolios-and-applications/", + "/project-administration/portfolio-pdf-configuration/", + "/project-administration/project-settings/", + "/project-administration/webhooks/" + ] }, { "title": "Instance Administration", "children": [ - "/instance-administration/custom-measures/", - "/instance-administration/housekeeping/", + "/instance-administration/quality-profiles/", + "/instance-administration/security/", + "/instance-administration/delegated-auth/", "/instance-administration/look-and-feel/", - "/instance-administration/quality-profiles/" + "/instance-administration/marketplace/", + "/instance-administration/housekeeping/", + "/instance-administration/notifications/", + "/instance-administration/system-info/", + "/instance-administration/monitoring/", + "/instance-administration/project-move/", + "/instance-administration/custom-measures/", + "/instance-administration/compute-engine-performance/", + "/instance-administration/db-copy/" ] + }, + "/previous-versions/", + "/faq/", + { + "title": "Scanners", + "url": "https://docs.sonarqube.org/display/SCAN" + }, { + "title": "Plugins", + "url": "https://docs.sonarqube.org/display/PLUG" + }, { + "title": "Extension", + "url": "https://docs.sonarqube.org/display/DEV" } ] diff --git a/server/sonar-web/config/webpack.config.js b/server/sonar-web/config/webpack.config.js index c240dbd623c..1ccfb7e06ce 100644 --- a/server/sonar-web/config/webpack.config.js +++ b/server/sonar-web/config/webpack.config.js @@ -150,5 +150,12 @@ module.exports = ({ production = true }) => ({ optimization: { splitChunks: { chunks: 'all' } }, - performance: production ? { hints: 'error' } : undefined + performance: production + ? { + // ignore source maps and documentation chunk + assetFilter: assetFilename => + !assetFilename.endsWith('.map') && !assetFilename.startsWith('js/docs.'), + hints: 'error' + } + : undefined }); diff --git a/server/sonar-web/src/main/js/apps/documentation/routes.ts b/server/sonar-web/src/main/js/apps/documentation/routes.ts index 617422a5ce5..ac6fe7cbfc4 100644 --- a/server/sonar-web/src/main/js/apps/documentation/routes.ts +++ b/server/sonar-web/src/main/js/apps/documentation/routes.ts @@ -19,7 +19,7 @@ */ import { lazyLoad } from '../../components/lazyLoad'; -const App = lazyLoad(() => import('./components/App')); +const App = lazyLoad(() => import(/* webpackChunkName: "docs" */ './components/App')); const routes = [{ indexRoute: { component: App } }, { path: '**', indexRoute: { component: App } }]; |
