SonarQubeCE Setup

Quiet one-shot Linux installer for SonarQube Community Build with PostgreSQL, an advanced multi-format reporter (PDF / XLSX / JSON / HTML / CSV), and the official SonarQube MCP Server (Docker stdio) for AI agents.

All installer messages, helper commands, and report content are in English.

Author

Name	Cuma KURT
Email	[email protected]
GitHub	github.com/cumakurt/SonarQubeCE-setup
LinkedIn	linkedin.com/in/cuma-kurt-34414917

Requirements

• Linux host with root (sudo)
• About 4 GB+ RAM and 10 GB+ free disk (30 GB+ recommended)
• Outbound network for package/image pulls on first run

Install

sudo bash setup-sonarqube-community-universal.sh

The installer prints live step progress on the terminal (including wait status with elapsed time). Detailed package/Docker command output goes to /opt/sonarqube/setup.log.

sudo VERBOSE=1 bash setup-sonarqube-community-universal.sh

Use VERBOSE=1 when you want full command output on screen as well as in the log.

Default bind is 0.0.0.0 for published HTTP services: SonarQube 9000 and MCP 8080 (reachable from other machines). Postgres and the reporter stay on the internal Compose network (not published). Lock to localhost with SONAR_BIND=127.0.0.1 MCP_BIND=127.0.0.1 if needed. Ensure the host firewall / cloud security group allows TCP 9000 and 8080. After a confirmed clean install, admin / reporter / MCP secrets are newly generated (see /opt/sonarqube/credentials.txt). Postgres also gets a new password because volumes are recreated from scratch.

Clean install (remnant detection)

Before writing a new stack, the installer always scans for previous remnants:

• containers: sonarqube-ce, sonarqube-ce-db, sonarqube-ce-mcp, legacy names, …
• named volumes: sonarqube-stack_postgres_data, sonarqube-stack_sonarqube_data, sonarqube-stack_sonarqube_logs, sonarqube-stack_sonarqube_extensions
• compose networks
• install secrets/config under /opt/sonarqube (.env, .reporter.env, .mcp.env, credentials.txt, compose file, reporter + MCP client configs)

If anything is found, setup lists the items, asks for confirmation on the terminal (Destroy remnants and continue with a CLEAN install? [y/N]), and:

Answer	Behavior
y / yes	Removes containers, volumes (DB and Sonar data destroyed), networks, and stack secrets, then installs from scratch with a new Postgres password
anything else / no TTY without FORCE_CLEAN	Aborts and leaves remnants unchanged

Reports under /opt/sonarqube/reports/ are kept unless you delete them yourself.

Non-interactive wipe (CI / automation):

sudo FORCE_CLEAN=1 bash setup-sonarqube-community-universal.sh

To force a specific new admin password:

sudo SONAR_ADMIN_PASSWORD='your-strong-password' bash setup-sonarqube-community-universal.sh

If credentials were lost and rotation cannot authenticate:

sudo SONAR_PREVIOUS_ADMIN_PASSWORD='current-admin-password' bash setup-sonarqube-community-universal.sh

Screenshots

Sample views captured from a successful setup and from generated analysis reports (project key deneme).

Installer / helpers

Setup progress and final summary printed by the installer:

Stack health via sonar-status:

HTML report

Cover / executive summary:

Detailed findings:

PDF report

Cover page:

Executive summary:

Finding write-up:

Optional overrides

sudo SONAR_BIND=127.0.0.1 MCP_BIND=127.0.0.1 bash setup-sonarqube-community-universal.sh   # localhost only
sudo SONAR_BIND=0.0.0.0 MCP_BIND=0.0.0.0 bash setup-sonarqube-community-universal.sh       # all interfaces (default)
sudo SONAR_IMAGE=sonarqube:community bash setup-sonarqube-community-universal.sh
sudo ALLOW_LOW_RESOURCES=1 bash setup-sonarqube-community-universal.sh
sudo SONAR_MEM_LIMIT=4g bash setup-sonarqube-community-universal.sh
sudo INSTALL_CLIENT_SCANNERS=0 bash setup-sonarqube-community-universal.sh
sudo INSTALL_MCP=0 bash setup-sonarqube-community-universal.sh
sudo MCP_READ_ONLY=0 bash setup-sonarqube-community-universal.sh
sudo MCP_IMAGE=sonarsource/sonarqube-mcp:1.19.0.2785 bash setup-sonarqube-community-universal.sh
sudo FORCE_CLEAN=1 bash setup-sonarqube-community-universal.sh

After install

1. Open the Web UI: http://<server-ip>:9000 (or http://127.0.0.1:9000 on the host). MCP HTTP is at http://<server-ip>:8080/mcp. Allow TCP 9000 and 8080 in the host firewall if remote clients cannot connect.
2. Sign in as admin
3. Read the password:

sudo grep SONAR_ADMIN_PASSWORD /opt/sonarqube/credentials.txt

4. Check stack health:

sonar-status

Analyze code (client scanners)

Setup installs analysis toolchains and Sonar scanners (disable with INSTALL_CLIENT_SCANNERS=0):

Tool	Command	Notes
SonarScanner CLI	sonar-scanner	Generic / multi-language
Maven	mvn + sonar-mvn	sonar-mvn runs the Sonar Maven plugin goal
Gradle	gradle + sonar-gradle	Project needs org.sonarqube plugin; helper runs gradle sonar
npm / JS-TS	sonar-scanner-npm / sonar-npm	Global @sonar/scan
.NET	dotnet + dotnet-sonarscanner	begin → build → end
Python	pysonar	SonarScanner for Python (venv under /opt/sonar-tools/pysonar; needs python3-venv / python3-pip)

Defaults (override anytime with env vars):

Variable	Default
SONAR_HOST_URL	http://127.0.0.1:9000
SONAR_TOKEN	loaded from /opt/sonarqube/.reporter.env if unset

cd /path/to/your/project

# Generic
sonar-scanner -Dsonar.projectKey=my-app -Dsonar.sources=.

# Maven
sonar-mvn
# or: mvn org.sonarsource.scanner.maven:sonar-maven-plugin:sonar

# Gradle (plugin required in build.gradle)
sonar-gradle

# npm / JavaScript
sonar-scanner-npm
# alias: sonar-npm

# .NET
dotnet-sonarscanner begin /k:"my-app" /d:sonar.host.url="$SONAR_HOST_URL" /d:sonar.token="$SONAR_TOKEN"
dotnet build
dotnet-sonarscanner end /d:sonar.token="$SONAR_TOKEN"

# Python
pysonar -Dsonar.projectKey=my-app

# Explicit env always wins
SONAR_TOKEN=squ_xxx SONAR_HOST_URL=http://127.0.0.1:9000 sonar-scanner

Then export a report:

sonar-report my-app --out my-app-latest

Reports are produced by sonar-report. It calls the local SonarQube Web API with an auto-created token and writes selected formats under /opt/sonarqube/reports/.

Source code for the reporter lives in the repo under reporter/ and is copied to /opt/sonarqube/reporter/ during setup.

Prerequisites

1. A project must exist in SonarQube and have been analyzed at least once.
2. Know the project key (Project → Project Information → Project Key).

Generate reports

# Default: ALL formats (PDF + XLSX + JSON + HTML + CSV)
# HTML/PDF use a SonarQube code-analysis result layout
# (cover, exec summary, FIND-xxx, remediation).
sonar-report YOUR_PROJECT_KEY

# Stable basename (still all formats)
sonar-report YOUR_PROJECT_KEY --out my-app-latest

# Optional: subset of formats only
sonar-report YOUR_PROJECT_KEY --out my-app --format pdf,xlsx

# New Code period only (Clean as You Code)
sonar-report YOUR_PROJECT_KEY --new-code --out my-app-new

# Cap PDF/HTML issue tables (XLSX/JSON/CSV stay full)
sonar-report YOUR_PROJECT_KEY --max-issues 200 --out my-app

# Code evidence (default ON)
# SonarQube/MCP scrub secrets in /api/sources/raw — pass the original checkout
# for unredacted evidence (including hard-coded credentials findings):
sonar-report YOUR_PROJECT_KEY --source-root /path/to/project/checkout --out my-app
sonar-report YOUR_PROJECT_KEY --code-context 5 --out my-app
sonar-report YOUR_PROJECT_KEY --no-code-evidence --out my-app-fast

Every finding includes code evidence. SonarQube stores secret-scrubbed sources in its API/MCP (asterisks). For unredacted snippets, pass --source-root (or SOURCE_ROOT) to the analyzed project directory; the path is remembered in /opt/sonarqube/source-roots.conf. Evidence appears in PDF, XLSX, JSON (codeEvidence), HTML, and CSV.

Rebuild the reporter image after pulling reporter source changes (or re-run setup):

cd /opt/sonarqube
sudo docker compose --env-file .env --profile tools build reporter

Output files

File	Use
*.pdf	Printable evidence report with root cause, how-to-fix, colored severity, code snippets
*.xlsx	Full sheets including Root Cause / How To Fix / Effort / Code Evidence
*.json	Full API export + per-finding analysis and codeEvidence
*.html	Colored professional dashboard: KPI cards, distribution charts, finding cards
*.csv	Issues/hotspots with cause, remediation, and evidence columns

Typical workflow

1. Analyze code into SonarQube (scanner or CI)
2. Confirm the project in the Web UI
3. Run:  sonar-report my-project-key --out my-project-latest
4. Open: /opt/sonarqube/reports/my-project-latest.pdf
         /opt/sonarqube/reports/my-project-latest.xlsx
         /opt/sonarqube/reports/my-project-latest.html

Troubleshooting reports

Symptom	What to check
SONAR_TOKEN is required	Re-run the installer, or ensure /opt/sonarqube/.reporter.env exists
401 Unauthorized	Token revoked; re-run the installer to regenerate it
Project not found	Wrong project key, or project not analyzed yet
Truncation warning	Sonar issue/hotspot search soft-cap (~10000); narrow with --new-code or filters in UI
Empty New Code sheet	No new-code period / metrics for the project yet

SonarQube MCP (AI agents)

The official SonarQube MCP Server runs inside the same Compose project (sonarqube-stack) as service mcp (container sonarqube-ce-mcp).

Item	Path / value
Compose service	mcp (HTTP, always-on) + mcp-stdio (profile, for sonar-mcp)
HTTP endpoint	http://<server-ip>:8080/mcp (default bind 0.0.0.0; override with MCP_BIND / MCP_PORT)
Health	http://<server-ip>:8080/health (on-host: http://127.0.0.1:8080/health)
Stdio helper	sonar-mcp → docker compose --profile mcp-stdio run … mcp-stdio
Token env	/opt/sonarqube/.mcp.env
Ready configs	/opt/sonarqube/mcp/clients/ (Bearer token embedded for HTTP clients)
Skip	INSTALL_MCP=0

Generated client files

HTTP clients point at the stack MCP service with Authorization: Bearer <token>.

cd /opt/sonarqube && sudo docker compose --env-file .env ps mcp
curl -fsS http://127.0.0.1:8080/health

sonar-mcp-configs list
sonar-mcp-configs install          # Cursor, Claude Desktop, Windsurf, VS Code, …
sonar-mcp-configs install cursor
sudo sonar-mcp-configs regenerate

Agent	File
Cursor / Claude Desktop / Windsurf / Copilot CLI / Kiro	HTTP *.mcp.json / *.json
VS Code	vscode.mcp.json (type: http)
Codex / Claude Code / stdio	sonar-mcp (compose mcp-stdio)

These files contain secrets — do not commit them.

Free reporting options (evaluation)

SonarQube Community Build does not include official PDF/Excel reporting (those start in commercial editions).

Option	Formats	Notes for SonarQube 26 + MQR
Official Enterprise PDF	PDF subscription	Paid; not available on CE
CNES sonar-cnes-report	DOCX/XLSX/CSV/MD	Often breaks on 25+/26 (removed complexity metrics, version gates, MQR quirks). Not bundled.
npm/community exporters	PDF/Excel/HTML	Extra runtime; uneven maintenance for current CE. Not bundled.
This project's sonar-report	PDF/XLSX/JSON/HTML/CSV	MQR-aware, New Code, debt/coverage depth, Docker-integrated, zero-config after setup. Recommended.

Helper commands

sonar-status                 # compact health + container table
sonar-logs                   # follow SonarQube container logs
sonar-scanner                # generic analysis
sonar-mvn / sonar-gradle     # Maven / Gradle helpers
sonar-npm / pysonar          # npm / Python scanners
dotnet-sonarscanner          # .NET begin/end
sonar-report PROJECT_KEY     # export multi-format report
sonar-mcp                    # SonarQube MCP Server (stdio / Docker)
sonar-mcp-configs            # list / install / regenerate agent mcp.json files

Stack layout

Path	Purpose
/opt/sonarqube/compose.yaml	Docker Compose stack (db, sonarqube, mcp, reporter, mcp-stdio)
/opt/sonarqube/.env	Stack secrets and image tags
/opt/sonarqube/.reporter.env	Reporter API token
/opt/sonarqube/.mcp.env	MCP Server API token + URL
/opt/sonarqube/mcp/clients/	Ready-to-run agent MCP configs (token embedded)
/opt/sonarqube/mcp/INSTALL-TARGETS.txt	Per-agent install paths
/opt/sonarqube/credentials.txt	Admin credentials (token paths, not secret values)
/opt/sonarqube/setup.log	Verbose installer log (quiet mode)
/opt/sonarqube/reports/	Generated report files
/opt/sonar-scanner/	SonarScanner CLI install
/usr/local/bin/sonar-scanner	PATH wrapper (honors SONAR_HOST_URL / SONAR_TOKEN)
/usr/local/bin/sonar-mcp	MCP stdio via compose mcp-stdio
/usr/local/bin/sonar-mcp-configs	Generate/install agent MCP configs
/opt/sonarqube/reporter/	Deployed reporter build context
reporter/ (repo)	Source of truth for the reporter

Containers use unique names (sonarqube-ce, sonarqube-ce-db, sonarqube-ce-reporter, sonarqube-ce-mcp) to avoid host name collisions.

License / project home

This project is licensed under the GNU General Public License v3.0.

Maintained by Cuma KURT — [email protected] · GitHub · LinkedIn