Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Concepts and Setup

SonarQube Architecture and Components

Understand the parts of a SonarQube server (web server, compute engine, search engine, database) and what happens to an analysis report from upload to dashboard.

When you run sonar-scanner, a surprising amount happens after the command exits. Knowing the moving parts helps you size a server, read logs and understand why a result sometimes appears a few seconds late. This lesson describes the architecture of a self-managed SonarQube Server; the cloud service hides it but works on the same principles.

The four parts of the server

A single SonarQube server runs several cooperating processes:

  • Web server: serves the user interface and the Web API (/api/...). It receives uploaded reports and answers every browser and CI request.
  • Compute Engine (CE): the worker. It takes uploaded reports from a queue, processes them one after another (or a few in parallel in higher editions) and writes the results.
  • Search server: an embedded search index (Elasticsearch-based) that makes issue and measure queries fast. It lives in its own process and keeps files in the data directory.
  • Database: the system of record for projects, issues, measures, users and settings. Production installs use PostgreSQL; the embedded database exists only for quick evaluations and cannot be upgraded or scaled.
flowchart LR
  S["Scanner (CI or laptop)"] -->|upload report| W["Web server"]
  W --> Q["CE queue"]
  Q --> C["Compute Engine"]
  C --> DB[("Database")]
  C --> ES[("Search index")]
  U["Browser / API client"] --> W
  W --> DB
  W --> ES

The scanner talks only to the web server. Everything after that happens inside the server.

What the scanner does and does not do

The scanner is a client, and the heavy lifting of language analysis happens in the scanner process on your build machine: it downloads the active rules and settings from the server, runs the analyzers on your files and produces a report (a compressed bundle of issues, measures, source and coverage data). The server then only needs to process the report, which is why a server can serve many CI machines.

Because the analyzers run where the scanner runs, the scanner needs access to your compiled classes (for Java) or installed dependencies for the best results. The server never needs access to your repository.

Life of a report

  1. The scanner posts the report to the web server and prints a task ID and a link.
  2. The web server stores the report and adds a CE task to the queue with status Pending.
  3. The Compute Engine picks the task up (In progress), compares the report with the previous analysis (to see which issues are new, closed or unchanged), computes measures and ratings, evaluates the quality gate, and stores everything.
  4. The task ends as Success, Failed or Canceled. Only after Success does the dashboard update.

A project can have only one CE task running at a time; later reports wait in the queue. During a busy morning, many CI jobs can queue up, which is why a slow server shows "analysis in progress".

Python Simulate the Compute Engine queue (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Quality gate timing

The gate is evaluated by the Compute Engine, after the scan, not by the scanner. That has a practical consequence for CI: the scanner exits as soon as it has uploaded the report (unless you ask it to wait). To fail a pipeline on a failed gate you either set the scanner option sonar.qualitygate.wait=true or call the Web API for the project status. Both approaches are shown in the CI chapter of this track.

Directories, ports and logs

A typical install has these locations under the SonarQube home:

  • conf/sonar.properties holds settings such as the database URL, the web port (default 9000) and the Java options for each process.
  • data/ holds the search index.
  • extensions/ holds plugins and JDBC drivers.
  • logs/ holds sonar.log (startup), web.log, ce.log (compute engine) and es.log (search). When an analysis fails on the server, ce.log is the first place to look.

The search server listens only on localhost by default, and you should not expose it. Only the web port is meant to be reachable, ideally behind a reverse proxy with HTTPS.

Reading status from the API

The web server exposes the task state, which is how scripts wait for processing. The stand-in below mimics reading a JSON status document and deciding what to do.

Python Interpret a task status document (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which component processes uploaded reports?

    The Compute Engine takes tasks from the queue, compares results and stores measures and issues.
  2. 2. Where does the language analysis (running the rules on your files) happen?

    The scanner runs the analyzers locally and uploads a report; the server only processes it.
  3. 3. Which database is recommended for production use?

    The embedded database is only for evaluation; production needs an external database such as PostgreSQL.
  4. 4. Which log is the first place to check when server-side processing of a report fails?

    ce.log records Compute Engine processing, including task failures.

Summary

  • A server has a web server, a Compute Engine, a search index and a database.
  • The scanner analyzes locally and uploads a report; the Compute Engine queues and processes it.
  • The quality gate is evaluated after processing, so CI must wait or poll.
  • Know the directories (conf, data, extensions, logs) and the default port 9000.

Next: Installing with Docker