Self-hosting

SonarQube on a VPS: self-hosted code quality and security

A human code review sees the intent; it lets the concatenated SQL query, the unused variable or the block copied three times slip through. SonarQube rereads every analysis against thousands of rules and decides with a quality gate: new code passes or it does not. This guide installs the open-source edition, SonarQube Community Build, on a VPS with Docker Compose, replaces the factory password, publishes it over HTTPS behind nginx and connects it to your CI.

Deploy on a VPS Cloud →
6 min read4 steps

Orbi AI agentThe contents follow the article; related articles wait at the bottom.

Contents· What SonarQube does1/11
  1. 01What SonarQube does
  2. 02What SonarQube gives you
  3. 03Manual review alone or SonarQube on your VPS
  4. 04Prepare the server
  5. 05Install SonarQube with Docker Compose
  6. 06Never publish an instance on admin/admin
  7. 07Publish SonarQube over HTTPS behind nginx
  8. 08Analyse a first project
  9. 09Block a pipeline on the quality gate
  10. 10Backup and upgrade
  11. 11SonarQube in one click on ServOrbit

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 aloneWith SonarQube on your VPS
Repetitive defectsDepends on the reviewer's attentionCaught on every analysis
Known flawsSpotted if someone knows themSecurity rules applied everywhere
Decision to deployGut feelingExplicit quality gate
Debt over timeGeneral impressionMeasurements per version
Where the code livesOn your forgeOn 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

  1. 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 .env
  2. Write 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: {}
  3. 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/status
  4. Replace the factory password

    The admin account is created with the password admin. 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.

Share this articleservorbit.com/ma-en/blog/self-host-sonarqube-vps-code-quality

Your code analysis on your VPS

Prices shown excluding VAT, with their renewal price.