Capstone: Operate a Governed Production SonarQube Quality Platform: Configuration, Design Patterns, and Trade-Offs
Choose production patterns deliberately across editions, automation, availability, disaster recovery, release strategy and bounded governance exceptions.
Learning objectives
- Choose between a minimum viable governed platform and commercial/enterprise expansion using evidence rather than prestige.
- Compare manual administration with policy-as-code while preserving least privilege, API versioning and rollback.
- Separate availability from disaster recovery and choose release/LTA strategies using supported compatibility paths.
- Balance centralized standards with bounded exceptions without letting variation become unmanaged drift.
- Produce a decision record that names prerequisites, affected state, observable evidence and rollback for each choice.
1. Design from control objectives, not product tiers
The Chapter 2 product model and Chapters 25/30 commercial features are inputs to architecture, not the architecture itself. Start with required controls: reproducible analysis, governed standards, least privilege, CI reliability, recoverability, upgradeability, capacity and auditability. Only then ask whether an edition or topology materially improves a control you actually need.
Generation date: 2026-09-08. Mandatory executable
work uses
SonarQube Community Build 26.9.0.129388 and the
official sonarqube:26.9.0.129388-community image. The
recorded scanner baseline is
SonarScanner CLI 8.1.0.6389. When scanner JRE
auto-provisioning is unavailable or disabled, use Java 21 or
newer. The local database family is PostgreSQL 17.x; the 2026.1
Server LTA documentation supports PostgreSQL 14–18. Commercial
references are SonarQube Server 2026 Release 4.1 and 2026.1.5 LTA.
Record the exact image digest, scanner output and database image
digest you actually run.
2. Decision table: prerequisites, evidence and rollback
A design choice is incomplete until its prerequisites and rollback are explicit.
| Choice | Prefer when | Affected state / evidence | Edition or prerequisite | Rollback / reversibility |
|---|---|---|---|---|
| Minimum governed Community platform | Single-instance availability is acceptable and core analysis/governance controls are the need. | One server + supported DB + scanner/CI configs + backup/restore proof. | Community Build; local/free. | Restore configuration/data or recreate disposable instance from recorded assets. |
| Commercial add-ons | Branch/PR analysis, enterprise reporting/security/identity or higher-scale workflows are justified. | License/edition + feature config + provider/identity evidence. | Verify current edition matrix. | Document free/local fallback for core control; do not make governance unknowable without license. |
| Manual admin | Rare, reviewable changes where UI evidence is sufficient and automation risk is higher than benefit. | Change record + before/after export/screens/API read. | Any edition supporting the setting. | Explicit prior state and owner. |
| Policy as code / API | Repeated provisioning or drift control needs deterministic, reviewable automation. | Desired-state file + API request/response + idempotence guard. | Documented API and least-privilege token. | Versioned config revert plus guarded re-apply. |
| Availability design | Reduce interruption from component/process failure. | Health, restart/failover behavior, topology evidence. | Single-node ops or DCE for licensed multi-node HA. | Return to known topology; do not conflate with data restore. |
| Disaster recovery | Recover from data/site loss or destructive change. | Database backup/replica, restore/reindex drill, RTO/RPO measurement. | Supported DB and documented recovery process. | Recovery plan itself is the rollback path; arbitrary software downgrade is not. |
| Current commercial release | Need newer capabilities and can absorb faster change cadence. | Compatibility matrix + update notes + staging evidence. | Commercial release train. | Restore/supported update recovery, not unsupported downgrade. |
| LTA strategy | Stability window and planned maintenance outweigh newest capability. | LTA version, maintenance release, compatibility/update roadmap. | Commercial Server LTA; current active line 2026.1. | Supported backup/restore and documented update path. |
| Central standard | Comparable risk context and common engineering policy. | Profile/gate/New Code desired state + assignments. | Core governance. | Versioned standard previous revision. |
| Bounded exception | Real contextual incompatibility or migration need. | Owner + rationale + narrow scope + expiry + compensating control. | Governance process, not a license feature. | Expiry/review returns project to standard or renews with evidence. |
3. Manual administration versus policy as code
Policy-as-code is valuable only if it remains supported, least-privileged and observable. A YAML file is merely desired state; it becomes an operational control only when a reconciler can safely read current state, show a diff, guard the exact target, apply a documented API and verify the result.
schema: sq34-governance-v1
platform:
baseline: community-26.9.0.129388
project_key: sq34:capstone
standard:
quality_profile_owner: quality-platform-team
quality_gate: SQ34 Lab Gate
new_code_policy: recorded-in-instance-and-evidence
access:
analysis_token_owner: sq34-local-operator
privileges: project-analysis-and-required-reads-only
operations:
backup_owner: platform-operations
restore_test_frequency: every-controlled-review-cycle
capacity_review: after-workload-or-topology-change
exceptions:
- id: SQ34-EX-001
scope: example-only
owner: sample-team
rationale: migration rehearsal
expires: 2026-09-30
compensating_control: manual-review# Desired state is not self-executing. Compare before mutation.
sha256sum governance.yaml > evidence/governance/governance.sha256
curl -fsS -H "Authorization: Bearer $SONAR_TOKEN" \
"http://localhost:9000/api/qualitygates/project_status?projectKey=sq34%3Acapstone" \
> evidence/api/current-gate.json
# A real reconciler would parse desired/current state, print a diff, require a guarded
# target identity and apply only documented endpoints. This capstone keeps mutation manual
# unless the exact endpoint and permission model are verified in the running instance.The Web API V2 migration is ongoing. Pin or detect the endpoint contract you depend on, test deprecation before upgrades, and never build a critical reconciler on undocumented internal routes.
4. Availability is not disaster recovery
High availability answers “how do we keep serving during component failure?” Disaster recovery answers “how do we reconstruct trustworthy service after loss/corruption/site failure?” Buying a cluster does not replace database backup/restore; having a dump file does not provide live failover.
| Failure | Availability response | DR response | Evidence |
|---|---|---|---|
| SonarQube process crash | restart/service/container health action | usually none if durable DB is intact | first-failure logs + health + restart reason |
| Host loss | redeploy single-node service or DCE failover where licensed | restore if durable state/site is lost | deployment manifest + DB reachability + recovery time |
| Database corruption/loss | availability alone cannot fix durable state | restore supported backup/replica and reindex | backup checksum + restore log + fresh analysis |
| Search/index corruption | restart/reindex via documented path | rebuild search from durable state; do not restore arbitrary copied index | ES evidence + reindex + result verification |
| Regional disaster | requires redundant architecture if business needs continuous service | secondary site/DB recovery plan | RTO/RPO drill and DNS/traffic plan |
5. Current release versus LTA strategy
Community Build and commercial Server use different release identities. Do not call Community 26.9 “the LTA,” and do not assume a commercial 2026.1 compatibility statement applies unchanged to every monthly Community build. Maintain a compatibility worksheet per platform you actually run.
| Strategy | Advantages | Costs/risks | Evidence before adoption |
|---|---|---|---|
| Community monthly baseline | Free, current core capabilities. | Faster cadence; no commercial LTA contract. | Pinned image/tag+digest, scanner compatibility, release notes, restore plan. |
| Commercial current release | Newest commercial capabilities. | More frequent compatibility/change review. | Staging update, plugins/integrations/database matrix, API deprecation check. |
| Commercial 2026.1 LTA | Longer active maintenance line; operational stability focus. | May lag newest feature train. | Latest maintenance release, Java 21/25, PostgreSQL 14–18 compatibility, supported path. |
Current 2026.1 LTA documentation requires a JDK for the server runtime, supports Java 21 or 25, removes Java 17, supports PostgreSQL 14–18 and includes Elasticsearch 8.x. Scanner runtime requirements are a separate contract; scanners with JRE auto-provisioning can manage their runtime, while non-provisioned paths should use Java 21+.
6. Central standards versus bounded exceptions
Centralization means common control intent, ownership and review—not identical bytes everywhere. Profiles may differ by language; CI wrappers may differ by build system; exception handling should preserve intent while avoiding metric gaming.
| Variation request | Decision | Why |
|---|---|---|
| Team dislikes a gate failure but risk context is unchanged | No exception; remediate code/evidence. | Preferences are not a control rationale. |
| Legacy migration cannot meet one New Code target for 14 days | Bounded exception with owner/expiry/compensating review. | Narrow, time-limited and reviewable. |
| Different language needs a different quality profile | Use language-appropriate profile under the same program standard. | Profiles are language/rule sets; “one profile everywhere” can be technically invalid. |
| Provider integration is commercial-only but core server gate is available | Use local/free server gate and simulate provider decoration boundary. | Core governance must remain learnable without paid provider feature. |
7. Worked reference patterns
A reference architecture is a hypothesis about workload and risk. Keep the measured evidence that justifies it.
| Reference pattern | Use case | Key controls | Deliberate non-goals |
|---|---|---|---|
| MVP governed single node | Small/medium team learning or modest availability requirement. | Supported DB, backup/restore test, scanner/gate CI, least privilege, logs/capacity, governance ledger. | No claim of HA; no enterprise report dependency. |
| Regulated-enterprise extension | Need audit/reporting/identity/portfolio aggregation. | Enterprise features plus external governance rationale, recovery and least privilege. | Reports do not prove secure code or replace source/CI evidence. |
| Data Center extension | Measured need for HA/horizontal scale. | Licensed topology, load balancing, shared DB, search cluster, version/plugin consistency, capacity tests. | Not a workaround for scanner/configuration/database bottlenecks. |
8. Knowledge check
When is policy-as-code worse than a manual UI change?
When the automation depends on undocumented endpoints, uses over-broad credentials, cannot show current-state diff/target guard, or creates more blast radius than the rare manual change. Auditability and reversibility matter more than automation for its own sake.
Does Data Center Edition satisfy disaster recovery by itself?
No. HA/topology resilience and DR are different controls. Durable database recovery, reindexing and tested restore/site procedures remain necessary.
Why can two teams use different quality profiles without abandoning a central standard?
Profiles are language/rule configurations. A central program can define common risk intent while assigning appropriate language profiles, as long as ownership, rationale and policy outcome remain governed.
What is the safest reaction to a failed update?
Preserve first-failure evidence and use the documented recovery/update path with a tested backup. Do not assume an arbitrary software downgrade is supported rollback.
What evidence justifies a commercial add-on?
A documented control or scale requirement that the add-on materially addresses, with edition/version prerequisites, observable success criteria, cost/operational impact and a fallback for core governance where practical.
9. Summary and bridge
You can now justify architecture and governance choices in terms of controls, prerequisites, evidence and rollback. Lesson 4 stress-tests the operating model against realistic failures: secret leakage, scan/gate confusion, missing first-failure evidence, backup/upgrade mistakes, vanity metrics and undocumented commercial dependencies.
Official references and version notes
Further reading
Verify version-sensitive behavior against primary documentation before using these patterns outside the disposable lab.
- SonarQube downloads — current Community Build, commercial release and LTA identities
- SonarQube Server documentation — server, administration, security and operations
- SonarQube Community Build documentation — free/local product behavior
- Web API — authentication and the ongoing Web API V2 migration
- Backup and restore — database backup/restore and reindex guidance
- Official SonarQube Docker image — current image tags and deployment notes
- LTA to LTA release notes — 2026.1 Java/database/scanner/runtime compatibility changes
SonarQube product names, editions, release trains, scanner runtimes, APIs, authentication options, and platform prerequisites can change independently. Re-check the linked SonarSource primary documentation for the exact target release before applying version-sensitive commands or operational guidance outside the disposable course environment.
Keep the academy open
Support free, practical DevOps education.
Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this
address.