Checkpoint Lab — Installation Prerequisites, Database Planning, and First Server

1. Scenario

You are the platform engineer responsible for proving that a clean workstation or disposable VM can host a first Community Build 26.9.0.129388 instance. The team wants more than screenshots: it wants a runbook that another engineer can audit and reproduce.

Your checkpoint must follow one path from host preflight → JDK → distribution → H2 lab database → Web/Compute/search startup → local endpoint → graceful stop/restart. Then you must introduce one reversible prerequisite failure and diagnose it from evidence.

2. Preflight and hard boundaries

• Use only a disposable/local authorized host and synthetic data.
• Use a supported current JDK; record the exact executable path and version.
• Keep the lab web endpoint on loopback unless an explicitly authorized private network is required.
• Use H2 only for this disposable checkpoint; do not claim it is production-ready.
• On Unix-like systems, run SonarQube as a non-root user.
• Do not disable TLS/authentication/search bootstrap checks or host security controls.
• Do not delete logs before the failure drill is complete.

3. Required assumptions manifest

product=SonarQube Community Build
version=26.9.0.129388
install_mode=ZIP
java=JDK 21 or 25; exact vendor/build recorded at execution time
database=H2 embedded; checkpoint only, NOT production
endpoint=http://127.0.0.1:9000
service_identity=non-root / non-elevated lab user
source_code=none required for this installation checkpoint
commercial_features=not required
failure_drill=one reversible prerequisite/configuration fault
cleanup=graceful stop + preserve evidence + guarded lab-directory removal

4. Make predictions before mutation

Write at least two predictions before starting:

1. Port prediction: before startup, nothing owned by this lab listens on 9000; after healthy startup, a SonarQube Web listener is reachable on the configured local port.
2. Process/log prediction: after startup, process-specific logs show Web, Compute Engine, and embedded-search initialization; after graceful stop, the listener disappears and the shutdown is recorded.
3. Failure prediction: when the chosen prerequisite is intentionally made invalid, startup fails in the owning layer and the relevant log contains evidence consistent with that prediction.

5. Execute the clean baseline run

Follow Lesson 2’s pinned download, preflight, extraction, startup, log inspection, endpoint verification, and graceful shutdown. Capture evidence as files rather than relying on terminal scrollback alone.

# Example evidence directory on Windows
$Evidence = 'C:\sq-lab\evidence\baseline'
New-Item -ItemType Directory -Force -Path $Evidence | Out-Null
java -version 2>&1 | Out-File "$Evidence\java-version.txt"
Get-Command java | Format-List * | Out-File "$Evidence\java-command.txt"
Get-NetTCPConnection -State Listen -LocalPort 9000 -ErrorAction SilentlyContinue |
  Format-List * | Out-File "$Evidence\port-before-or-after.txt"

Copy only the lab’s SonarQube log files into the evidence directory. Do not copy unrelated system logs or secrets.

6. Failure drill: choose one reversible prerequisite fault

Use one of the following safe drills. Do not stack failures.

7. Diagnose before repairing

For the chosen failure, record: the intended configuration; the observed symptom; the first relevant log line; the owning layer; one alternative hypothesis you ruled out; and the least-destructive correction.

Example for occupied port: prove the listener existed before SonarQube started; identify the disposable listener process; preserve the SonarQube bind error; stop only that owned listener; rerun unchanged SonarQube configuration; prove the listener now belongs to SonarQube.

8. Verification checklist

• Exact Community Build release recorded.
• Exact JDK executable/vendor/version recorded.
• Host OS/architecture, disk, and relevant Linux limits recorded.
• Installation directory and service user recorded.
• Database explicitly labeled H2 lab-only.
• Pre-start and post-start port evidence retained.
• sonar.log, web.log, ce.log, and es.log preserved where produced.
• Healthy endpoint verified only after startup evidence.
• Failure drill preserves the original error before repair.
• Same pinned server starts successfully again after repair.

9. Required evidence packet

Deliver a small dossier with these files or sections:

1. assumptions.txt — product/version/JDK/database/network boundary.
2. preflight.txt — runtime, user, host limits/disk/port state.
3. artifact.txt — ZIP URL, size, SHA-256, extraction path.
4. baseline-logs/ — process-specific startup evidence.
5. baseline-health.txt — local endpoint and listener proof.
6. failure/ — original failure evidence and classification.
7. recovery.txt — one correction and verified healthy rerun.
8. production-delta.md — external DB, service management, secrets, proxy/TLS, backups, monitoring, upgrades still required.

10. Production delta: what this checkpoint deliberately does not implement

The lab does not prove a production architecture. A production deployment still needs: a currently supported external database and backup plan; durable service identity; supported data/temp paths; secrets handling; reverse proxy/TLS/network rules; monitoring; capacity and disk planning; update/rollback procedures; plugin governance; tested recovery; and any commercial-edition requirements.

Write this limitation explicitly. A strong checkpoint distinguishes what evidence supports from what the learner has not tested.

11. Cleanup and rollback

Gracefully stop the lab instance and verify port 9000 is no longer owned by SonarQube. Preserve the evidence dossier. Then delete only the exact disposable lab path you created, after printing/confirming that path. If the failure drill changed a permission or shell PATH, restore it to the recorded baseline. Do not run broad recursive deletion commands against ambiguous paths.

12. What this chapter adds to the operating model

You now have an installation contract: exact release, exact runtime, host/search prerequisites, durable-database boundary, service identity, filesystem/network boundary, process-specific logs, and a reproducible health/failure procedure. Chapter 04 builds on this by moving the same state model into Docker, persistent volumes, container identity, and production deployment patterns—without pretending containers erase these prerequisites.

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.