Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Concepts and Setup

Installing SonarQube with Docker

Run SonarQube locally with Docker and Docker Compose: system limits, a PostgreSQL database, volumes, first login, and a generator and checker for the config.

Docker is the quickest way to get a working SonarQube server on your own machine. You can start a throwaway instance with one command, or build a durable setup with Docker Compose and a PostgreSQL database. This lesson shows both, explains the system limits that trip people up, and provides stand-ins that generate and check the configuration.

Image names and tags change between releases (for example sonarqube:community or a version-specific tag). Look up the current tag in the official image page before you copy a command. The commands below are read-only examples: this site cannot run Docker, so nothing here was executed on the page.

The one-command trial

Terminal
docker run -d --name sonarqube -p 9000:9000 sonarqube:community

This starts a server with the embedded database. Open http://localhost:9000 after a minute or two (the first start initializes the search index). It is perfect for a first try and wrong for anything you want to keep: data lives inside the container, and the embedded database cannot be upgraded.

System limits

SonarQube embeds a search server that memory-maps files. On Linux hosts the kernel must allow it:

  • vm.max_map_count at least 524288
  • fs.file-max at least 131072
  • open files (nofile) at least 131072 and processes (nproc) at least 8192 for the user running it

Set the first on the Docker host with sysctl -w vm.max_map_count=524288 and persist it in /etc/sysctl.conf. With Docker Desktop on Windows, set it inside the WSL 2 distribution. If the container exits straight after start, check docker logs sonarqube for a message about a too-low limit.

The server also needs RAM: plan for roughly 2 GB free for a small instance, and more for large codebases. Check the requirements for your version.

A durable setup with Compose

A production-like local setup uses PostgreSQL and named volumes so that data survives container restarts and upgrades.

YAML
services:
  sonarqube:
    image: sonarqube:community
    depends_on:
      - db
    environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: change-me
    ports:
      - "9000:9000"
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_extensions:/opt/sonarqube/extensions
      - sonarqube_logs:/opt/sonarqube/logs
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: sonar
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: sonar
    volumes:
      - postgresql_data:/var/lib/postgresql/data
volumes:
  sonarqube_data:
  sonarqube_extensions:
  sonarqube_logs:
  postgresql_data:

Start it with docker compose up -d and watch docker compose logs -f sonarqube until you see that the server is operational. If you need to read more about volumes see the Docker tutorial.

Generating the Compose file

Writing the same YAML repeatedly invites typos. The stand-in generates it from a few settings, and refuses obviously unsafe passwords.

Python Generate a docker-compose.yml (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A pre-flight check

The most common install failure is a host limit that is too low. This stand-in compares your numbers with the minimums listed above and tells you what to change. Replace the sample values with the output of sysctl vm.max_map_count, sysctl fs.file-max and ulimit -n.

Python Check host limits (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

First login and hardening

  • Log in as admin with password admin and change it immediately when prompted.
  • Put a reverse proxy (nginx, Traefik) in front with HTTPS before sharing it with a team, and set sonar.core.serverBaseURL or the Server base URL setting to the public address so links in notifications work.
  • Back up the database; that is where your data lives. Keep the volumes for plugins and the search index, but the index can be rebuilt.
  • To upgrade, pin the image tag, back up the database, stop the old container, start the new image against the same database and open the migration page /setup when asked. Do not skip supported upgrade paths; read the release notes.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why is the one-command docker run unsuitable for long-term use?

    The embedded database is meant for evaluation only; real use needs PostgreSQL or another supported database.
  2. 2. What should vm.max_map_count be set to, at minimum?

    The embedded search server needs at least 524288 memory map areas; otherwise it will not start.
  3. 3. What should you back up first before an upgrade?

    The database holds all projects, issues and settings; the index can be rebuilt.
  4. 4. What does a named volume for /opt/sonarqube/data protect?

    Volumes keep data outside the container, so removing and re-creating the container does not lose it.

Summary

  • docker run gives a quick trial; Compose with PostgreSQL and volumes gives a durable local server.
  • Raise vm.max_map_count (524288), file and process limits before the first start.
  • Change the default admin password and put HTTPS in front before sharing.
  • Back up the database and pin image tags for upgrades.

Next: Projects, Branches and Pull Requests