Installation Prerequisites, Database Planning, and First Server: Diagnostics, Failure Modes, and Production Practices

1. “SonarQube will not start” is a symptom, not a root cause

A first-server startup crosses multiple independently failing layers. The correct response is not “restart until it works.” Preserve the first failure, identify the owning layer, make one minimal correction, and rerun the smallest equivalent startup.

1. Record exact SonarQube edition/version and JDK.
2. Preserve sonar.log, web.log, ce.log, and es.log.
3. Record service user, paths, permissions, free disk, host limits, and listening ports.
4. Record database engine/version/JDBC target without printing secrets.
5. Classify: runtime → host/search → filesystem/identity → database → web/network → application policy.
6. Apply one least-destructive correction and rerun.

2. Broken example: legacy Java tutorial copied into a current install

Scenario: the lab machine still has Java 17 first on PATH. A legacy tutorial says that is sufficient.

$ java -version
openjdk version "17.0.x" ...

# startup fails early / current host requirement mismatch

The correct diagnosis is runtime compatibility. Do not edit SonarQube internals, change database settings, or download a different Community Build release merely to fit an obsolete runtime assumption.

Repair: install/select a current supported JDK (21 or 25 for this baseline), prove Get-Command java/which java, record the new java -version, then rerun the same untouched SonarQube distribution.

3. Broken example: embedded search bootstrap failure

Scenario: Linux es.log reports a bootstrap-check failure and preflight shows vm.max_map_count below the documented minimum.

sysctl vm.max_map_count
sysctl fs.file-max
ulimit -n
ulimit -u

Preserve the log first. Then correct the authorized host setting using the current SonarSource guidance. Do not normalize a “disable bootstrap checks” workaround. The failure is intentionally protecting the reliability of the embedded search layer.

4. Broken example: H2 promoted to production

Scenario: a team runs the default H2 database for months because “the trial never crashed.” The defect is architectural even if startup is green. The current documentation states H2 is for tests/trials, not production.

The correction is a planned move to a supported external database using the current migration/update guidance—not copying an H2 file into a database server or editing tables manually. Preserve project/configuration history and follow supported migration boundaries.

5. Broken example: running as root to avoid permissions errors

Scenario: a Unix startup initially fails to write a directory, so an operator runs the whole server as root. That hides the filesystem design error and broadens the blast radius.

Repair by identifying the intended service user and the exact directories it must read/write, correcting ownership/permissions narrowly, and restarting as the non-root identity. Preserve the original permission error because it tells you which path needed attention.

6. Broken example: embedded-search data moved to network storage

Scenario: someone places the search data path on NFS/SMB/NAS because remote storage “sounds durable.” Query/index latency becomes unstable and search can become unreliable.

Current host guidance warns against remote-mounted storage for embedded search. Move the search data path to supported fast local/block storage according to the documented operating model; keep durable recovery centered on the database and supported backup procedures rather than treating a copied search directory as a backup.

7. Broken example: default port exposed broadly

Scenario: a fresh instance is launched on an externally reachable interface with bootstrap administrator credentials unchanged. The server may be technically healthy while the trust boundary is unacceptable.

First restrict the listener/firewall to the authorized network, then establish authentication, reverse proxy/TLS, and permission policy deliberately. Do not solve certificate issues by disabling TLS verification. A network/security failure can coexist with perfect SonarQube process health.

8. Read the right log before changing the wrong layer

9. Troubleshooting shortcuts that destroy evidence or safety

• Do not delete logs before preserving them.
• Do not grant administrator/root rights “to see if it works.”
• Do not disable TLS verification or firewall controls as a normal fix.
• Do not edit SonarQube database tables or embedded-search files directly.
• Do not lower quality policy or change project keys to disguise an installation failure.
• Do not downgrade binaries against migrated state without a supported restore path.

10. Production incident packet

A useful first-server incident packet contains: timestamp; exact product/edition/version; JDK path/version; host OS/architecture; memory/disk; relevant Linux limits; service identity; installation/data/temp/log paths; web bind/port; database engine/version/host identity with secrets redacted; process-specific logs; change that preceded failure; and the one correction tested.

This packet lets another engineer reproduce the diagnostic reasoning without access to your shell history or guesses.

11. Why this matters in DevOps

SonarQube will eventually become a delivery control. If the platform itself is diagnosed by trial-and-error restarts, broad privileges, and lost logs, every downstream quality signal inherits operational uncertainty. Evidence-first platform operations protect both availability and auditability.

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.