Docker Compose Reference: SonarQube

TL;DR

• Bottom line: SonarQube runs as two Docker services (SonarQube + PostgreSQL) with named volumes for persistence, requiring host kernel tuning (vm.max_map_count >= 524288) before startup.
• Key tool/command: docker compose up -d with a compose file defining sonarqube:community (or developer/enterprise) and postgres:17 services.
• Watch out for: Using bind mounts instead of named volumes breaks plugin installation, and forgetting to set vm.max_map_count on the Docker host causes Elasticsearch to crash on startup.
• Works with: Docker Engine 20.10+, amd64/arm64. PostgreSQL 15-17. SonarQube Community (free), Developer, Enterprise, Data Center editions.

Constraints

• Host kernel MUST have vm.max_map_count >= 524288 and fs.file-max >= 131072 -- SonarQube's embedded Elasticsearch will fail to start otherwise
• Use Docker named volumes, NOT bind mounts -- bind mounts prevent plugins from populating correctly
• PostgreSQL is the only supported production database -- H2 is for evaluation only and does not support upgrading
• SonarQube Community Edition is free; Developer, Enterprise, and Data Center editions require a commercial license
• Default admin credentials (admin/admin) MUST be changed immediately after first login
• Docker Engine 20.10+ is required; amd64 and arm64 architectures are supported

Quick Reference

Service Configuration

Edition Comparison

Decision Tree

START: What SonarQube Docker setup do you need?
├── Need quick local evaluation?
│   ├── YES → Use sonarqube:community with embedded H2
│   └── NO (production) ↓
├── Single instance or high availability?
│   ├── Single instance ↓
│   │   ├── Need branch analysis / PR decoration?
│   │   │   ├── YES → Use sonarqube:developer + PostgreSQL
│   │   │   └── NO → Use sonarqube:community + PostgreSQL
│   │   └── Resource sizing:
│   │       ├── < 50 projects → 4 GB RAM, 2 CPU cores
│   │       ├── 50-200 projects → 8 GB RAM, 4 CPU cores
│   │       └── > 200 projects → Consider Enterprise edition
│   └── High availability → Data Center edition
└── CI/CD integration?
    ├── GitHub Actions → SonarSource/sonarqube-scan-action
    ├── GitLab CI → sonarsource/sonar-scanner-cli:11 image
    ├── Jenkins → SonarQube Scanner for Jenkins plugin
    └── CLI/Manual → sonar-scanner CLI or Docker image

Step-by-Step Guide

1. Configure host kernel parameters

SonarQube embeds Elasticsearch, which requires specific Linux kernel settings on the Docker host. [src5]

# Set temporarily (resets on reboot)
sudo sysctl -w vm.max_map_count=524288
sudo sysctl -w fs.file-max=131072

# Set permanently (survives reboot)
echo "vm.max_map_count=524288" | sudo tee -a /etc/sysctl.d/99-sonarqube.conf
echo "fs.file-max=131072" | sudo tee -a /etc/sysctl.d/99-sonarqube.conf
sudo sysctl --system

Verify: sysctl vm.max_map_count → expected: vm.max_map_count = 524288

2. Create docker-compose.yml

Create the compose file with SonarQube and PostgreSQL. Use named volumes, not bind mounts. [src1] [src2]

services:
  sonarqube:
    image: sonarqube:community
    read_only: true
    depends_on:
      db:
        condition: service_healthy
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: ${SONAR_DB_PASSWORD:-sonar}
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_temp:/opt/sonarqube/temp
    tmpfs:
      - /tmp:size=256m
    ports:
      - "9000:9000"
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: ${SONAR_DB_PASSWORD:-sonar}
      POSTGRES_DB: sonar
    volumes:
      - postgresql_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sonar -d sonar"]
      interval: 10s
      timeout: 5s
      retries: 5
volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  sonarqube_temp:
  postgresql_data:

Verify: docker compose config → no errors in output

3. Start the services

Launch SonarQube and wait for it to become healthy. First startup takes 1-3 minutes. [src1]

docker compose up -d
docker compose logs -f sonarqube
# Wait for "SonarQube is operational" message

Verify: curl -s http://localhost:9000/api/system/status | jq .status → expected: "UP"

4. Change default admin password

Change the default admin/admin credentials immediately. [src1]

curl -u admin:admin -X POST \
  "http://localhost:9000/api/users/change_password" \
  -d "login=admin&previousPassword=admin&password=YOUR_SECURE_PASSWORD"

Verify: curl -u admin:YOUR_SECURE_PASSWORD http://localhost:9000/api/system/status → returns 200 OK

5. Generate a scanner token

Create an authentication token for the scanner to use in CI/CD. [src4]

curl -u admin:YOUR_SECURE_PASSWORD -X POST \
  "http://localhost:9000/api/user_tokens/generate" \
  -d "name=ci-scanner&type=GLOBAL_ANALYSIS_TOKEN"

Verify: Navigate to http://localhost:9000/account/security → token appears in list

6. Configure sonar-project.properties

Place this file in your project root. [src1]

sonar.projectKey=my-project
sonar.projectName=My Project
sonar.sources=src
sonar.tests=test
sonar.sourceEncoding=UTF-8
sonar.qualitygate.wait=true
sonar.qualitygate.timeout=300

7. Run SonarScanner

Run the scanner against your project using Docker. [src6]

docker run --rm \
  --network=sonarnet \
  -e SONAR_HOST_URL="http://sonarqube:9000" \
  -e SONAR_TOKEN="your_generated_token" \
  -v "$(pwd):/usr/src" \
  sonarsource/sonar-scanner-cli:11

Verify: Check http://localhost:9000/dashboard?id=my-project → analysis results appear

Code Examples

GitHub Actions: SonarQube Analysis

# .github/workflows/sonarqube.yml
name: SonarQube Analysis
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  sonarqube:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: SonarQube Scan
        uses: SonarSource/sonarqube-scan-action@v4
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
      - name: Quality Gate
        uses: SonarSource/sonarqube-quality-gate-action@v1
        timeout-minutes: 5
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

GitLab CI: SonarQube Analysis

# .gitlab-ci.yml
sonarqube-check:
  image:
    name: sonarsource/sonar-scanner-cli:11
    entrypoint: [""]
  variables:
    SONAR_USER_HOME: "${CI_PROJECT_DIR}/.sonar"
    GIT_DEPTH: "0"
  cache:
    key: "${CI_JOB_NAME}"
    paths:
      - .sonar/cache
  script:
    - sonar-scanner
      -Dsonar.host.url=${SONAR_HOST_URL}
      -Dsonar.token=${SONAR_TOKEN}
      -Dsonar.projectKey=${CI_PROJECT_PATH_SLUG}
      -Dsonar.qualitygate.wait=true

Docker Compose: Production Hardened Setup

Full script: docker-compose-production.yml (62 lines)

# Production-hardened docker-compose.yml with resource limits,
# health checks, restart policies, and reverse proxy readiness.
services:
  sonarqube:
    image: sonarqube:developer
    read_only: true
    deploy:
      resources:
        limits: { memory: 4g, cpus: "2.0" }
        reservations: { memory: 2g }
    # ... (see full script)

Bash: Backup SonarQube Data

#!/bin/bash
BACKUP_DIR="./backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"
docker compose exec -T db pg_dump -U sonar sonar \
  | gzip > "$BACKUP_DIR/sonar_db.sql.gz"
docker run --rm \
  -v sonarqube_extensions:/data \
  -v "$(pwd)/$BACKUP_DIR":/backup \
  alpine tar czf /backup/extensions.tar.gz -C /data .
echo "Backup saved to $BACKUP_DIR"

Anti-Patterns

Wrong: Using bind mounts for SonarQube volumes

# BAD -- bind mounts prevent plugins from populating correctly
services:
  sonarqube:
    image: sonarqube:community
    volumes:
      - ./sonarqube/data:/opt/sonarqube/data
      - ./sonarqube/extensions:/opt/sonarqube/extensions

Correct: Using named Docker volumes

# GOOD -- named volumes let SonarQube populate directories correctly
services:
  sonarqube:
    image: sonarqube:community
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
volumes:
  sonarqube_data:
  sonarqube_extensions:

Wrong: Skipping PostgreSQL health check

# BAD -- SonarQube starts before DB is ready, causes JDBC errors
services:
  sonarqube:
    depends_on:
      - db  # only waits for container start, not readiness

Correct: Using health check with condition

# GOOD -- waits until PostgreSQL is actually ready
services:
  sonarqube:
    depends_on:
      db:
        condition: service_healthy
  db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sonar -d sonar"]
      interval: 10s
      timeout: 5s
      retries: 5

Wrong: Using H2 database in production

# BAD -- H2 is for evaluation only, no upgrade path
services:
  sonarqube:
    image: sonarqube:community
    # No SONAR_JDBC_URL = uses embedded H2

Correct: Always use PostgreSQL for production

# GOOD -- PostgreSQL provides durability and upgradability
services:
  sonarqube:
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: ${SONAR_DB_PASSWORD}

Wrong: Hardcoding secrets in docker-compose.yml

# BAD -- secrets committed to version control
services:
  sonarqube:
    environment:
      SONAR_JDBC_PASSWORD: my_secret_password_123

Correct: Using environment variables or Docker secrets

# GOOD -- use .env file (not committed to git)
services:
  sonarqube:
    environment:
      SONAR_JDBC_PASSWORD: ${SONAR_DB_PASSWORD}

Common Pitfalls

• vm.max_map_count not set: SonarQube crashes with max virtual memory areas vm.max_map_count [65530] is too low. Fix: sudo sysctl -w vm.max_map_count=524288 on the Docker host. [src5]
• Elasticsearch bootstrap checks fail: Container exits immediately. Fix: Set vm.max_map_count, fs.file-max, and ulimits on the host system. [src5]
• Plugins not loading after restart: Using bind mounts prevents SonarQube from populating extensions. Fix: Switch to named volumes. [src1]
• JDBC connection refused on startup: SonarQube starts before PostgreSQL is ready. Fix: Add healthcheck and depends_on: { condition: service_healthy }. [src2]
• Quality gate timeout in CI: sonar.qualitygate.wait=true hangs. Fix: Add sonar.qualitygate.timeout=300. [src4]
• Scanner cannot reach SonarQube in Docker: Scanner on host uses localhost but SonarQube is on bridge network. Fix: Attach scanner to same Docker network. [src6]
• Data lost after docker compose down -v: The -v flag removes named volumes. Fix: Use docker compose down without -v; create regular backups. [src1]
• Out of memory on large projects: Default JVM heap insufficient. Fix: Set SONAR_WEB_JAVAOPTS=-Xmx2g and SONAR_CE_JAVAOPTS=-Xmx2g. [src3]

Diagnostic Commands

# Check SonarQube service status
curl -s http://localhost:9000/api/system/status | jq .

# View SonarQube logs
docker compose logs sonarqube --tail=100

# Check PostgreSQL readiness
docker compose exec db pg_isready -U sonar -d sonar

# Check host kernel parameters
sysctl vm.max_map_count fs.file-max

# Verify volumes exist
docker volume ls | grep sonar

# Check resource usage
docker compose stats --no-stream

# List installed plugins
curl -s http://localhost:9000/api/plugins/installed -u admin:password | jq '.plugins[].key'

# Check quality gate status for a project
curl -s "http://localhost:9000/api/qualitygates/project_status?projectKey=my-project" \
  -u admin:password | jq .projectStatus.status

Version History & Compatibility

PostgreSQL Compatibility

When to Use / When Not to Use

Important Caveats

• SonarQube Community Edition is licensed under LGPL v3; Developer/Enterprise/Data Center require commercial licenses from SonarSource
• The embedded Elasticsearch instance means SonarQube has significant memory requirements (minimum 2 GB RAM, 4+ GB recommended)
• Docker Desktop on macOS/Windows handles vm.max_map_count automatically; native Linux Docker hosts require manual configuration
• SonarQube does not support downgrades -- always backup before upgrading and test in staging first
• The sonar-scanner-cli Docker image expects code at /usr/src; GitLab CI mounts at $CI_PROJECT_DIR, so set SONAR_PROJECT_BASE_DIR accordingly
• Quality gate results are only available after the Compute Engine background task completes, which may take minutes on large projects