Installation Prerequisites, Database Planning, and First Server: Core Concepts and Mental Model

1. Current baseline: installation is a compatibility contract

For this chapter, the executable baseline is SonarQube Community Build 26.9.0.129388, the current Community Build release at the time of authoring. For a ZIP installation, the current host requirements call for a JDK running Java 21 or 25. That is deliberately different from many older tutorials that mention a JRE, Java 17, or older database ranges.

A healthy startup therefore begins before you unzip anything. You need a supported host, enough CPU/RAM/disk, a suitable JDK, a database choice appropriate to the environment, local filesystem semantics compatible with embedded search, a non-privileged service identity, and a network exposure plan.

2. Mental model: prerequisites become three cooperating server processes

Think of a first SonarQube server as a chain of ownership. The distribution is only one input. At runtime, SonarQube coordinates a Web process, a Compute Engine process, and an embedded search process. The database carries durable application state while the search engine maintains query/index structures needed by the application.

flowchart TD
H[Supported host
CPU RAM disk limits] --> J[Supported JDK]
J --> D[SonarQube distribution]
DB[Database choice
H2 lab or supported external DB] --> P[sonar.properties / env]
D --> P
FS[Filesystem + service identity
local writable data/log/temp] --> P
P --> W[Web process]
P --> C[Compute Engine]
P --> E[Embedded search]
DB --> W
DB --> C
E --> W
W --> U[UI / Web API :9000]
C --> R[Background-task results]
R --> DB

The Web process serves the UI and API and coordinates requests. The Compute Engine processes uploaded analysis reports asynchronously. The embedded search subsystem indexes/query-supports application data. The database is the primary durable application store. If one layer is unhealthy, “port 9000 opened” is not enough to claim the instance is healthy.

3. State stores: what survives, what can be rebuilt, what must stay local

Operational mistakes often begin by calling every directory “SonarQube data.” The stores have different recovery and performance roles.

4. Host prerequisites are part of the application architecture

On Linux, the embedded search engine inherits host kernel and user limits. Current Community Build guidance requires vm.max_map_count of at least 524288, system fs.file-max of at least 131072, at least 131072 file descriptors for the SonarQube user, and at least 8192 threads. These are not tuning folklore; they are startup/reliability prerequisites for the search subsystem.

# Read-only inspection on Linux
java -version
sysctl vm.max_map_count
sysctl fs.file-max
ulimit -n
ulimit -u
id
ss -ltn | grep ':9000' || true
df -h .

Do not run these checks and immediately write system settings. First record the observed values, compare them with the current release documentation, and decide whether the host is an appropriate lab or production candidate. Host-level mutations belong to an authorized administrator and should be reversible.

5. Database planning: H2 is a trial convenience, not a production design

Community Build starts with an embedded H2 database by default. Current documentation is explicit that H2 is recommended for tests/trials and not for production. A production-shaped design uses a supported external database such as PostgreSQL, Microsoft SQL Server, or Oracle, with exact supported versions rechecked for the target SonarQube release.

For this chapter’s mandatory lab, H2 is acceptable because the goal is to learn process startup and evidence on a disposable local instance. That does not make the H2 directory a production backup strategy. Later chapters will address durable database administration and recovery in depth.

6. Service identity, directories, ports, and initial administrator state

On Unix-like systems, SonarQube must run as a non-root user. A dedicated service identity makes filesystem ownership and process accountability explicit. For a ZIP install, that identity needs the required access to the installation and configured data/log/temp paths—but it should not receive unrelated root privileges.

The default web endpoint is http://localhost:9000. Localhost is a safe lab boundary because it avoids unintentionally publishing the fresh administrator surface. The initial administrator credentials are admin/admin; they are a bootstrap state, not a credential policy. Change them immediately when the instance is anything beyond a throwaway lab.

7. Read-only preflight before installation

Create an evidence card before changing the machine. On Windows PowerShell, record Java, free disk, port occupancy, and the current user:

$ErrorActionPreference = 'Stop'
java -version
[Environment]::UserName
Get-PSDrive -PSProvider FileSystem | Select-Object Name,Used,Free
Get-NetTCPConnection -State Listen -LocalPort 9000 -ErrorAction SilentlyContinue
Get-Command java | Select-Object Source

On Linux/macOS, record the equivalent state with java -version, id, df -h, and a port check. The preflight output belongs in the installation evidence packet. If it already reveals an unsupported runtime, exhausted disk, occupied port, or an unsuitable privilege model, stop before unzipping the server.

8. Foundation mistakes to reject early

• “The ZIP contains everything.” ZIP installs depend on an external supported JDK and host prerequisites.
• “If the browser loads, all server components are healthy.” Read process-specific logs and health/task evidence.
• “H2 worked in my lab, so it is fine for production.” The current docs explicitly reject that conclusion.
• “Search is the database.” Embedded search and the application database have different durability/recovery roles.
• “Running as root avoids permissions problems.” It violates the supported Unix operating model and masks ownership mistakes.
• “A NAS is safer because it is remote.” Embedded search has strong local-disk latency/semantics requirements; network-mounted storage is not a general solution.

9. Why this matters in DevOps

A DevOps platform should be reproducible from evidence, not from “it started on my laptop.” The installation record should answer: which SonarQube build, which JDK, which host limits, which database, which service identity, which paths, which ports, and which logs proved health. Those facts later become the inputs to service management, containers, Kubernetes, upgrades, backups, and CI availability.

Knowledge check

Official references and version notes

• SonarQube Community Build downloads — current Community Build release identity and download entry point.
• Server host requirements — current JDK, OS, CPU/RAM/disk, and embedded-search requirements.
• Installing database — supported databases and the H2 non-production boundary.
• Linux pre-installation — current vm.max_map_count, file-descriptor, thread, and seccomp prerequisites.
• ZIP installation overview — required installation sequence and initial login baseline.
• Basic ZIP installation — database, data/temp paths, web connection, and healthy startup guidance.
• Starting and stopping from ZIP — current platform start/stop commands and graceful-stop semantics.
• Running as a service — Windows service and Linux service-account guidance.