What SonarQube does
SonarQube is a static analysis platform: it reads code without running it and flags what is likely to break, leak or be expensive to maintain. Each issue is classified — bug, vulnerability, security hotspot to review, code smell — and links to a documented rule, with a fix example.
The Community Build edition is published by SonarSource under the LGPL-3.0 licence. It covers about twenty languages, including Java, JavaScript and TypeScript, Python, PHP, C#, Go and Kotlin, as well as infrastructure as code (Terraform, Kubernetes, Dockerfile). It analyses each project's main branch; branch analysis, pull request analysis and the C and C++ languages belong to the commercial editions.
What SonarQube gives you
- A quality gate — a clear verdict on every analysis, which your pipeline can wait for before deploying.
- Security in the loop — injections, plaintext secrets and weak configurations flagged at commit time.
- Explained rules — every issue carries its rationale and a fix example.
- Tracking over time — technical debt, duplicated code and test coverage, version after version.
- Your code stays with you — nothing leaves your VPS, neither the code nor the results.
- A complete API — projects, tokens, quality gates and webhooks, all scriptable.
Manual review alone or SonarQube on your VPS
Scroll the table
| Manual review alone | With SonarQube on your VPS | |
|---|---|---|
| Repetitive defects | Depends on the reviewer's attention | Caught on every analysis |
| Known flaws | Spotted if someone knows them | Security rules applied everywhere |
| Decision to deploy | Gut feeling | Explicit quality gate |
| Debt over time | General impression | Measurements per version |
| Where the code lives | On your forge | On your forge and your VPS |
Prepare the server
Plan an Ubuntu 24.04 VPS with at least 4 GB of RAM and 2 vCPUs: SonarQube runs three Java processes — the web server, the compute engine that processes analyses and an embedded Elasticsearch. Install Docker and the Compose plugin.
Two system settings matter. Elasticsearch wants vm.max_map_count set to at least 524288: set it on the host with sysctl -w vm.max_map_count=524288 and make it permanent in /etc/sysctl.d/99-sonarqube.conf. And SonarQube refuses to start when less than 10% of the disk is free: keep some headroom.
Install SonarQube with Docker Compose
Prepare the folder and the .env file
The file holds the PostgreSQL database password.
mkdir -p /opt/sonarqube && cd /opt/sonarqube cat > .env <<EOF DB_PASSWORD=$(openssl rand -hex 16) EOF chmod 600 .envWrite the docker-compose.yml file
Two services: PostgreSQL and SonarQube. The port is published on the loopback interface only: nginx alone will face the Internet.
services: db: image: postgres:17.12-alpine restart: unless-stopped environment: POSTGRES_DB: sonar POSTGRES_USER: sonar POSTGRES_PASSWORD: "${DB_PASSWORD}" volumes: - sonarqube-db:/var/lib/postgresql/data sonarqube: image: sonarqube:26.11.0.134175-community restart: unless-stopped depends_on: [db] environment: SONAR_JDBC_URL: "jdbc:postgresql://db:5432/sonar" SONAR_JDBC_USERNAME: sonar SONAR_JDBC_PASSWORD: "${DB_PASSWORD}" SONAR_TELEMETRY_ENABLE: "false" SONAR_ES_BOOTSTRAP_CHECKS_DISABLE: "true" ulimits: nofile: { soft: 131072, hard: 131072 } nproc: { soft: 8192, hard: 8192 } ports: - "127.0.0.1:9000:9000" volumes: - sonarqube-data:/opt/sonarqube/data - sonarqube-extensions:/opt/sonarqube/extensions - sonarqube-logs:/opt/sonarqube/logs volumes: sonarqube-db: {} sonarqube-data: {} sonarqube-extensions: {} sonarqube-logs: {}Start and check
The first start creates the database schema and the search indexes: allow two to five minutes. The status must reach
UP.docker compose up -d docker compose logs -f sonarqube # wait for "SonarQube is operational" curl -s http://127.0.0.1:9000/api/system/statusReplace the factory password
The
adminaccount is created with the passwordadmin. Replace it before publishing the instance. SonarQube requires at least 12 characters with an uppercase letter, a lowercase letter, a digit and a special character.NEW='<your-password>' curl -fsS -u admin:admin -X POST http://127.0.0.1:9000/api/users/change_password \ --data-urlencode login=admin --data-urlencode previousPassword=admin \ --data-urlencode "password=$NEW" curl -s -u admin:admin http://127.0.0.1:9000/api/authentication/validate # {"valid":false}
Never publish an instance on admin/admin
As long as the factory password is active, anyone who finds your address becomes administrator and reads all your code. Replace it before opening the reverse proxy, then create one named account per developer under Administration, Security, Users. Login is required by default to see anything: keep that setting on.
Publish SonarQube over HTTPS behind nginx
Get a certificate with certbot, then declare a server block that forwards the X-Forwarded-Proto header:
server {
listen 443 ssl;
server_name sonarqube.example.com;
ssl_certificate /etc/letsencrypt/live/sonarqube.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/sonarqube.example.com/privkey.pem;
client_max_body_size 50m;
location / {
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}Then, under Administration, Configuration, General, fill in the server base URL (https://sonarqube.example.com): SonarQube writes it into its links, notifications and webhooks.
Analyse a first project
Under My Account, Security, generate a token of type Global Analysis Token. From the root of a project, run the official scanner in a container, with nothing to install on your workstation:
docker run --rm \
-e SONAR_HOST_URL=https://sonarqube.example.com \
-e SONAR_TOKEN=<token> \
-v "$PWD:/usr/src" \
sonarsource/sonar-scanner-cli \
-Dsonar.projectKey=my-project -Dsonar.sources=.The project appears in SonarQube with its issues, its debt and the quality gate verdict. For a Java project built with Maven or Gradle, use the build plugin instead, which reads the compiled classes.
Block a pipeline on the quality gate
Store SONAR_HOST_URL and SONAR_TOKEN in the repository secrets. With sonar.qualitygate.wait=true, the scanner waits for the verdict and fails if the quality gate is red: the deployment step that follows does not run.
# .github/workflows/sonarqube.yml
name: sonarqube
on:
push:
branches: [main]
jobs:
analyse:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Analyse SonarQube
run: |
docker run --rm -e SONAR_HOST_URL -e SONAR_TOKEN -v "$PWD:/usr/src" \
sonarsource/sonar-scanner-cli \
-Dsonar.projectKey=${{ github.event.repository.name }} \
-Dsonar.qualitygate.wait=true
env:
SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}The principle is the same on GitLab CI, Jenkins or Woodpecker: one step that runs the scanner with these two variables.
Backup and upgrade
Results live in PostgreSQL; added plugins live in the sonarqube-extensions volume. The search indexes rebuild themselves at start-up and do not need a backup.
cd /opt/sonarqube
docker compose exec -T db pg_dump -U sonar sonar | gzip > sonar-$(date +%F).sql.gz
docker run --rm -v sonarqube_sonarqube-extensions:/src -v "$PWD:/dst" alpine \
tar czf /dst/extensions-$(date +%F).tar.gz -C /src .To upgrade, back up first, change the image tag, then run docker compose pull && docker compose up -d. If SonarQube asks for a database migration, open https://your-domain/setup and start it.
SonarQube in one click on ServOrbit
The ServOrbit Marketplace installs exactly this stack: the official SonarQube Community Build image and PostgreSQL, port published on 127.0.0.1 only, the admin account's factory password replaced on first start, server base URL declared and HTTPS configured on your domain or on the VPS's free subdomain. The administrator password is shown in your client area.
servorbit.com/ma-en/blog/self-host-sonarqube-vps-code-quality
