How to Use SonarQube: The Beginner's Guide (First Server, First Scan, the Dashboard Lesson, and the Quality-Gate Arc)

CodexFuse Team · 2026-11-07T08:06:37.328Z · 25 min read min read

How Do You Use SonarQube?

Learning how to use sonarqube starts with one idea: SonarQube is a code-quality server that reads your code without running it and shows you the bugs, vulnerabilities, and code smells it finds on a web dashboard. This guide covers the tool with every fact checked as of November 2026, and that date matters, because SonarQube renames its editions and ships a new version every two months, so an old guide can point you at the wrong names. SonarQube is not a linter you run once and forget, and it is not a cloud-only service, so if you came here for a quick one-off check, you want the local scan in step 4 instead.

CodexFuse offers no SonarQube tool, so this guide teaches the real program on your own machine, not a web version of it. No Facebook promotion applies to this guide. The closest sibling guide is our Git beginner guide, which covers the version control your first scan reads from, and you should read it first if Git is new to you.

1. Check the version pins in this guide, so you install the current release and not a stale one.
2. Start the server with one Docker command, then log in and change the default password.
3. Create a project in the web interface and generate a project analysis token.
4. Add a sonar-project.properties file to your repository root.
5. Run the SonarScanner from your project folder and watch the results upload.
6. Read the dashboard, starting with bugs and vulnerabilities, then code smells and coverage.
7. Turn on the Sonar way quality gate, so a failing scan blocks bad code from merging.

What Is SonarQube, Exactly?

SonarQube is a self-hosted static-analysis platform from SonarSource, and the mental model is simple: the scanner analyzes, the server stores, and the dashboard shows. The scanner reads your source code on your machine or in CI, sends a report to the server, and the server saves the results in a database and shows them in the web interface. The server itself runs three Java processes, a web process for the interface, an Elasticsearch process for search, and a compute engine that processes each analysis report, according to the official SonarQube Server documentation.

The naming changed in 2025, so older guides use the old names: the self-hosted product is now SonarQube Server, the hosted service formerly called SonarCloud is now SonarQube Cloud, and the free edition is now Community Build. Community Edition is the old name for the free edition, and the current name is Community Build, while the phrase sonarqube community edition still appears in search results because it was the name for years. SonarSource also renamed its IDE plugin SonarLint to SonarQube for IDE, which is a free extension that catches issues as you type.

SonarSource says its tools are trusted by over 7 million developers and 75 percent of the Fortune 100, and that figure is the vendor's own claim, not an independent measurement. The SonarSource/sonarqube repository on GitHub is licensed under LGPL-3.0, according to the GitHub API, although AppSecSanta reports that the bundled analyzers moved to the Sonar Source-Available License in late 2024, so licensing is in flux and you should check the current terms. The repository itself is a living project, with its last code push one day before this guide was checked, and the numbers in the snapshot table below come from the GitHub API as fetched on 7 November 2026.

The server repository has 25.95 times as many stars as the scanner repository, which makes sense, because the server is the product and the scanner is the small client that feeds it. The API returns a zero open-issues figure because issues are disabled on the GitHub repository, so the zero means nothing, and support runs through the Sonar community forum instead. Do not read the empty issue tracker as a sign that the project has no bugs, because the tracker is simply switched off.

Which SonarQube Version Should You Install?

SonarQube Server moved to calendar versioning in 2025, so versions now read as year, release, and patch, and two Long-Term Active releases ship each year, with a new Server release every two months. The current Long-Term Active release is SonarQube Server 2026.5, released 29 September 2026, 39 days before this guide was checked, and its latest patch is 2026.5.4, released 5 November 2026, 2 days before this guide was checked. The free Community Build ships monthly instead, and its latest release is 26.11.0.134175, released 4 November 2026, 3 days before this guide was checked.

The previous Long-Term Active release was 2026.1, released 30 January 2026, 281 days before this guide was checked, and the gap between the two Long-Term Active releases is 242 days, which shows the roughly eight-month cadence. Upgrading to 2026.5 requires being on the 2026.1 Long-Term Active release first, according to the SonarSource community announcement, so check your current version before you upgrade. Version 2026.5 needs PostgreSQL 15 or later for a production database, and it dropped Node.js 20 support for JavaScript and TypeScript analysis, so older setup guides that cite Java 17 or Java 11 for the server are stale for this release.

The 2026.5 release also brought SonarSource's agentic features to self-hosted deployments for the first time, including Sonar Vortex, a remediation agent, and a hunter agent for access-control and business-logic flaws, available with the Enterprise and Data Center editions. A model-agnostic AI CodeFix arrived in 2026.2, and an embedded MCP server arrived in 2026.3, so the 2026 line is the AI-assisted line, not just a version bump. Beginners do not need any of this to run a first scan, and this guide treats the agents as a footnote, not a requirement.

The release dates cluster tightly, because the scanner release came 2 days before the Community Build release, and the 2026.5.4 patch came 1 day after it, which is why the November 2026 stamp on this guide matters. A version pin from this month will age within weeks on the monthly Community Build cadence, so re-check the downloads page when you install, and treat any guide older than a few months as a candidate for stale version numbers.

How Do You Install SonarQube with Docker?

A sonarqube docker install starts with one command, and Docker is the route the official documentation recommends, ahead of the ZIP install and the Helm chart. The evaluation one-liner runs the server on port 9000 with the embedded H2 database, and you can open the interface at localhost port 9000 once the container is up. Our Docker beginner guide covers the Docker install itself, and you should read it first if Docker is new to you, because SonarQube assumes a working Docker setup.

The bare Docker one-liner uses the embedded H2 database for evaluation only, and production needs PostgreSQL, so do not run a team server on the one-liner. The production form adds three environment variables for the database connection and three named volumes for data, extensions, and logs, and the official documentation shows that form with the image name taken from Docker Hub. Small-scale installs need 4 GB of RAM, 2 cores, and 30 GB of disk, with at least 10 percent free space at all times, because Elasticsearch locks its indexes when disk usage passes 90 percent.

docker run -d --name sonarqube -p 9000:9000 sonarqube:community
docker run -d --name sonarqube -p 9000:9000 -e SONAR_JDBC_URL=jdbc:postgresql://db:5432/sonar -e SONAR_JDBC_USERNAME=sonar -e SONAR_JDBC_PASSWORD=sonar -v sonarqube_data:/opt/sonarqube/data -v sonarqube_extensions:/opt/sonarqube/extensions -v sonarqube_logs:/opt/sonarqube/logs sonarqube:community

The first login uses the default credentials admin and admin, and SonarQube prompts you to change the password right away, so change the default admin password immediately and never leave it on a network-reachable instance. The server takes a minute or two to boot, because it starts an Elasticsearch instance inside, so wait for the interface to answer before you decide the install failed. A ZIP install is still supported, but the official documentation says to use it only when Docker or Helm is not feasible, and ZIP installs need a JDK with Java 21 or Java 25 for Server 2026.5.

Linux hosts need two kernel settings for the Elasticsearch process inside the container, vm.max_map_count set to 262144 and fs.file-max set to 65536, and independent guides cite the same values the official documentation links to. The Docker Hub image itself is heavily used, with 1,229,948,120 pulls counted on 7 November 2026, which works out to 110,220.28 pulls per star on the GitHub repository. The image tags named latest and community both updated on 5 November 2026, 2 days before this guide was checked, so the community tag tracks the current monthly release.

How Do You Create Your First Project and Run Your First Scan?

A sonarqube first scan needs three things: a project in the interface, a token, and a properties file in your repository. Create a local project in the web interface with a project key and a display name, then generate a project analysis token, which is the narrowest token type, limited to one project. Prefer a project analysis token over a user token for scans, give it an expiry, and never commit it to the repository.

The sonar-project.properties file sits in the root of your repository, and its one required value is a unique sonar.projectKey, which must be unique inside your SonarQube instance. The file also names the project, the version, the source folder, the encoding, and the server address, and the example below shows all six values for a first project. This sonarqube tutorial follows the official SonarQube documentation and the independent guides fetched for this guide, and the properties file is the lesson most beginners get wrong, because a missing or duplicate key is the first error a scan reports.

sonar.projectKey=my-first-project
sonar.projectName=My First Project
sonar.projectVersion=1.0
sonar.sources=.
sonar.sourceEncoding=UTF-8
sonar.host.url=http://localhost:9000

Install the SonarScanner CLI separately from the server, because the scanner is its own download, and the latest release is 8.3.1.16491, published 2 November 2026, 5 days before this guide was checked. Run sonar-scanner from the project root with the SONAR_TOKEN and SONAR_HOST_URL environment variables set, and the scanner reads the token from the environment automatically, which keeps it out of your shell history and CI logs. No commands in this guide were executed in a live testbed by the writer, and every step follows the official documentation as fetched on 7 November 2026.

sonar-scanner
sonar-scanner -Dsonar.host.url=http://localhost:9000
mvn clean verify sonar:sonar
npm install -g @sonar/scan

The setup wizard offers a local scan and a CI scan, and the local route runs the scanner on your machine against localhost port 9000, while the CI route runs the same scanner in the pipeline or through the official SonarQube scan action on GitHub. Our GitHub beginner guide covers the platform the CI route runs on, and the scan action is the cleanest way to analyze every pull request without installing the scanner on a runner. For compiled languages, build the project before you scan, because the scanner needs the compiled output to analyze some languages fully.

How Do You Read the SonarQube Dashboard?

The dashboard opens on the project overview, and it groups everything into six families: Reliability, Security, Security review, Coverage, Maintainability, and Duplications. Each family has an overall-code value and a new-code value, so you can see the state of the whole project and the state of the code changed most recently. Start with the issues list, because the counts on the overview are summaries, and the list shows the file, the line, and the rule behind each finding.

A bug is an issue that represents something wrong in the code, and the official documentation warns that if it has not broken yet, it will, and probably at the worst possible moment. A vulnerability is a security weakness the analyzer identified concretely, such as an injection flaw or weak cryptography, and a code smell is a maintainability issue, which is code that works but is hard to read or change. A security hotspot is different from a vulnerability, because it is security-sensitive code that needs a human review decision, not a confirmed flaw, and SonarQube tracks hotspots as reviewed or not reviewed.

Coverage is a mix of line coverage and condition coverage, and it answers how much of the source code the unit tests covered, while SonarQube itself never runs your tests, because it imports a coverage report such as JaCoCo XML or LCOV. Duplication counts the lines and blocks repeated across the project, and technical debt is the sum of the remediation costs of all code smells, expressed as an estimated fix time and rolled into an A-to-E maintainability rating. The default maintainability grid runs from A at a debt ratio of 0 to 0.05 up to E at 0.51 to 1, according to the official metric definitions.

The Measures tab holds every metric with its key, and the Web API exposes the same metrics by key, so a dashboard number and an API number always agree. Read the ratings as signals, not scores, because a project with zero bugs and 40 percent coverage is not healthier than a project with ten small code smells and 90 percent coverage. The next section turns these readings into a pass-or-fail decision, which is where the dashboard stops being a report and starts being a gate.

What Is a Quality Gate, and How Does the Sonar Way Gate Work?

A sonarqube quality gate is a set of pass-or-fail conditions on metrics, evaluated at each analysis, and the pipeline can block on it, so a red gate stops bad code from merging. The default gate is called Sonar way, and it is provided by Sonar, activated by default, and read-only, which means you can copy it and edit the copy, but you cannot change the original. Our GitHub Actions beginner guide covers the pipeline the gate blocks in, and the scanner flag sonar.qualitygate.wait makes the scanner poll for the result and exit non-zero on failure.

The Sonar way gate has four conditions, and all four apply to new code: no new issues are introduced, all new security hotspots are reviewed, new-code test coverage is at least 80 percent, and duplication in new code is at most 3 percent. The Sonar way numbers apply to new code only, not the whole codebase, so a legacy project with old debt can pass its first gate while the old code stays visible but non-blocking. That design has a name, Clean as You Code, and it is the reason a team can adopt SonarQube on a ten-year-old codebase without failing every build on day one.

New code means the code added or changed since a reference point, and the default baseline is the previous version, which treats any line changed since the last version tag as new. The alternatives are a number of days, such as the last 30 days, or a reference branch, such as main, set with sonar.newCode.referenceBranch or in the project settings. The coverage and duplication conditions do not kick in when a change has fewer than 20 new lines, by default, so a one-line fix never fails the gate for missing tests.

The older pre-2025 gate described reliability, security, and maintainability A ratings with a technical-debt ratio, and that is the legacy Sonar way gate, so do not copy its numbers as current. AI-generated code gets a stricter variant, the Sonar way for AI Code gate, which keeps the same four new-code numbers and adds overall-code conditions, including a security rating of A and a reliability rating of C or better. Tag a project as containing AI code to run it through that gate, and keep the default gate for human-written code until the team is ready for the stricter one.

What Does SonarQube Cost? The Free-vs-Paid Boundary

A sonarqube setup on your own hardware costs nothing for the software, because the Community Build is free and open source, and the cost is the machine it runs on. Our what is VPS hosting guide covers the cheapest way to host that machine, and a small install needs only 4 GB of RAM and 2 cores, so a modest virtual server is enough for a first team. Server Developer and Enterprise prices are not published by SonarSource, and Server pricing is per instance, per year, by lines of code, through a sales quote, so only the Cloud prices in this section are vendor-published numbers.

The Community Build analyzes the main branch only, with no branch analysis, no pull-request decoration, and no taint analysis, according to third-party comparisons of the editions, and that is the boundary that pushes growing teams to a paid edition. It covers 20 or more languages, against 40 in the Developer edition and 48 in the Enterprise edition, and it still includes the quality gates and the CI integration a beginner needs. Developer adds branch and pull-request analysis, pull-request decoration, taint analysis, and secrets detection, while Enterprise adds portfolios, compliance reporting, and legacy languages such as COBOL and ABAP.

The Cloud Free tier covers private projects up to 50,000 lines of code with no card and no expiry, and the Team plan starts at 34 dollars per month for analysis up to 100,000 lines, which is 408 dollars per year and 50,000 lines more than the free tier. Lines of code are counted as the sum of the largest branch of each project, and blank lines, comments, and test code never count, according to the vendor pricing page. Exceeding the licensed lines rejects new analyses, so watch the count as the team adds projects, and treat the free tier as a real ceiling, not a soft suggestion.

Third-party sites quote conflicting Server Developer prices, and this guide does not repeat any of them as fact, because the vendor page shows no dollar figure at all. The honest way to price a Server edition is to ask SonarSource for a quote with your line count in hand, and to compare it against the Cloud Team price for the same line count. If the team is small and the code is on the main branch, the Community Build is the right start, and the paid editions become relevant when pull-request analysis or compliance reports enter the picture.

SonarQube vs Qodana: Which One Fits Your Team?

Sonarqube vs qodana is the comparison most readers ask about, because Qodana is the other serious code-quality platform, and it comes from JetBrains, the company behind IntelliJ IDEA. Qodana runs the same IntelliJ inspection engine in CI that developers see in the IDE, so what the IDE flags is exactly what CI reports, and it runs as a Docker container or CLI in the pipeline with no separate server to maintain. SonarQube is the opposite shape, a persistent central server with a dashboard, where rules and gates are managed in the web interface, and the scanner reports to it from every build.

The deepest difference is configuration: SonarQube manages rules and gates centrally in the server interface, while Qodana stores its inspection profiles as code in the repository, version-controlled and reviewable in pull requests. JetBrains says Qodana Ultimate costs 5 dollars per developer per month on an annual plan, with a minimum of 3 contributors, while third parties say 6 dollars, so the vendor figure is 5 and the third-party figure is 6, a 12-dollar gap per developer per year. Semgrep is the third shape worth knowing, a fast pattern-based scanner that runs as a single command with no server, and it suits teams that want rules they can write themselves in YAML.

The rule and language counts in the table come from the JetBrains comparison of March 2026 and independent 2026 comparisons, and they move with each release, so treat them as a snapshot. Choose SonarQube for the deepest deterministic rule coverage, the widest language breadth, centralized governance, compliance reporting, and portfolio management, according to an independent 2026 comparison, and choose Qodana if the team lives in JetBrains IDEs and wants IDE-identical CI results at a low per-contributor price. The two tools can also run side by side, with Qodana in the pipeline for fast feedback and SonarQube as the system of record, although most small teams should pick one and learn it well.

Seven Mistakes Beginners Make with SonarQube

The mistakes below come from the stale guides and the official documentation, and each one has a one-line fix, so read the table first and the detail after it. The most expensive mistake is the first one, because a production server on the embedded database is evaluation-only by design. The most avoidable mistake is the last one, because the password change takes seconds and an unchanged default password is an open door.

Two of the mistakes deserve a second look, because they look like small details and behave like big ones. A token committed to Git history stays in history even after you delete it from the current files, so rotate the token and rewrite the history, or accept that the token is public. A scan run before the build analyzes source files without compiled output, and for compiled languages that means missing findings, so the build-then-scan order is a rule, not a preference.

Sources

The version pins, the Docker install form, the system requirements, and the metric definitions come from the official SonarQube Server documentation on docs.sonarsource.com, fetched on 7 November 2026, including the server components overview, the host requirements, the Docker container setup page, and the metric definitions. The edition and price facts come from the SonarSource downloads page and the plans-and-pricing pages, fetched the same day, and the 2026.5 Long-Term Active announcement comes from the SonarSource community forum, posted 29 September 2026.

The repository numbers come from the GitHub API for SonarSource/sonarqube and SonarSource/sonar-scanner-cli, fetched on 7 November 2026, and the image numbers come from the Docker Hub API for the sonarqube image, fetched the same day. The Qodana comparison comes from the JetBrains Qodana blog of 19 March 2026 and an independent 2026 dev.to comparison, and the Semgrep facts come from AppSecSanta and independent 2026 guides.

The field guides checked for this article include the Medium Docker and Next.js guide of May 2026, the androidcoding.in beginner tutorial, the dev.to complete Docker, scanner, and CI/CD setup guide, the itstartechs free-SAST Docker guide, the dev.to Vultr Ubuntu 24.04 install guide, and the older tothenew Maven guide of 22 September 2024, 776 days old, the nextbraintech Node.js guide updated 24 August 2026, 75 days old, the copyprogramming Windows and Node.js install guide, 273 days old, and the devsecopsschool DevSecOps tutorial, 532 days old. The upgrad tutorial page was updated 4 days before this guide was checked, but its content still cites Java 11, which is stale for Server 2026.5. The search snapshots for the two primary keywords were taken with the search tool on 7 November 2026, not from a logged-in Google page 1, and no search volumes were published by any source used.

print("repo age days", 5785)
print("repo age years", 15.84)
print("repo stars per fork", 4.97)
print("repo star fork gap", 8915)
print("scanner stars per fork", 3.74)
print("repo stars per scanner stars", 25.95)
print("docker pulls", 1229948120)
print("docker pulls billions", 1.23)
print("docker pulls per star", 110220.28)
print("lta 2026.5 days ago", 39)
print("lta 2026.1 days ago", 281)
print("lta gap days", 242)
print("release days ago", 3)
print("scanner release days ago", 5)
print("scanner to release gap days", 2)
print("patch days ago", 2)
print("tothenew guide days old", 776)
print("nextbraintech update days old", 75)
print("cloud team yearly dollars", 408)
print("cloud free to team loc gap", 50000)
print("qodana 5 dollar yearly", 60)
print("qodana 6 dollar yearly", 72)
print("qodana price gap yearly", 12)

Frequently Asked Questions

Is SonarQube free?

Yes, the Community Build is free and open source, and it covers the main branch with quality gates and CI integration for small teams. It has no branch analysis, no pull-request decoration, and no taint analysis, so growing teams move to a paid Server edition or to SonarQube Cloud. The Cloud Free tier covers private projects up to 50,000 lines of code with no card and no expiry.

How do I run my first SonarQube scan?

Start the server with the Docker one-liner, log in, and create a project to get a project key and a token. Add a sonar-project.properties file to your repository root with the key, the source folder, and the server address, then run sonar-scanner from the project folder. Open the dashboard at localhost port 9000 to read the results, and fix the bugs and vulnerabilities first.

What is the difference between SonarQube Server and SonarQube Cloud?

SonarQube Server is the self-hosted product you run on your own machine or server, while SonarQube Cloud is the hosted service where SonarSource runs the server for you. Server pricing is per instance, per year, by lines of code through a sales quote, while Cloud has a free tier up to 50,000 lines and a Team plan from 34 dollars per month. Beginners who want zero infrastructure should start with Cloud, and teams that need data on their own network should start with Server.

What does the Sonar way quality gate check?

The Sonar way gate checks four conditions on new code: no new issues, all new security hotspots reviewed, at least 80 percent test coverage, and at most 3 percent duplication. The gate judges new code only, so old debt stays visible without blocking the build, and changes under 20 new lines skip the coverage and duplication conditions. A red gate fails the build when the scanner waits for the result, which is how the gate enforces quality in CI.

Should I choose SonarQube or Qodana?

Choose SonarQube for a central server with a dashboard, the deepest rule coverage, and compliance reporting, and choose Qodana if your team lives in JetBrains IDEs and wants CI results identical to the IDE. Qodana runs in CI with no server to maintain and prices per contributor, while SonarQube prices by lines of code per instance per year. Small teams should pick one tool and learn it well, because running both doubles the configuration without doubling the value.