Set up and start your container

How to set up and start your SonarQube Server container with the Developer or Enterprise edition.

You can set up and start the SonarQube container either from the command line (docker run) or from a configuration file (docker compose). Installation setup relies on system properties, which are preferably configured via environment variables in a Docker environment.

Using docker run

Run the image as illustrated in the docker run command below. You can define your system properties by using the -e environment variable flag in the command. See Mandatory and relevant settings below for information about the properties to be set.

$> docker run -d --name sonarqube \
    -p 9000:9000 \
    -e SONAR_JDBC_URL=... \
    -e SONAR_JDBC_USERNAME=... \
    -e SONAR_JDBC_PASSWORD=... \
    -v sonarqube_data:/opt/sonarqube/data \
    -v sonarqube_extensions:/opt/sonarqube/extensions \
    -v sonarqube_logs:/opt/sonarqube/logs \
    <image_name>

Note that:

• By default, the server running within the container will listen on port 9000. The -p 9000:9000 argument is used to expose the container port 9000 to the host port 9000: -p port1:port2 maps container’s port port1 as port2 on the host.

• For <image_name>, check the tags currently available on the DockerHub page.

Using Docker compose

If you’re using Docker Compose, use this yml file example as a reference when configuring your .yml file. You can define the system properties by setting the corresponding environment variables in the environment section of the .yml file. See Mandatory and relevant settings below for information about the properties to be set.

Note that:

• By default, the server running within the container will listen on port 9000. The following code is used to expose the container port 9000 to the host port 9000 ("port1:port2" maps container’s port port1 as port2 on the host):

ports:
      - "9000:9000"

• In the image tag, use the tag value corresponding to the SonarQube Server version you want to use. Check the SonarQube Server image tags currently available on the DockerHub page. For example, to use the LTA version of the Developer Edition:

  image:  sonarqube:2025-lta-developer

Unless you intend to delete the database and start new when running your image, be careful not to use -v to docker-compose down and, be careful when running commands like docker system prune or docker volume prune; regardless if you use an external: true parameter, your database volumes will not persist beyond the initial startup and shutdown of SonarQube.

Mandatory and relevant settings

You must set the access to your database and you should check the web server connection parameters. This section explains also other settings that are optional.

Set access to the database

You must configure the access to your database (except if you want to use SonarQube for test purposes and want to use the embedded database H2). To do so, set the system properties (environment variables) related to database access:

• SONAR_JDBC_USERNAME

• SONAR_JDBC_PASSWORD

• SONAR_JDBC_URL

For more information, see General.

Check the web server connection parameters

Check the default values of the following system properties and change their values if necessary:

• SONAR_WEB_HOST

• SONAR_WEB_PORT

• SONAR_WEB_CONTEXT

To do so, see Web server connection.

Enabling IPv6

When you run your Docker container:

• Enable IPv6 in the JVM by setting the JAVA_TOOL_OPTIONS environment variable to -Djava.net.preferIPv6Addresses=true.

• Enable IPv6 in SonarQube by setting the SONAR_WEB_JAVAADDITIONALOPTS environment variable (system property) to -Djava.net.preferIPv6Addresses=true.

See below for instructions depending on the Docker tool used.

With docker-run

Set the environment variables in the docker run command as illustrated below.

docker run -d --name sonarqube \
    -p 9000:9000 \
    -e JAVA_TOOL_OPTIONS="-Djava.net.preferIPv6Addresses=true" \
    -e SONAR_WEB_JAVAADDITIONALOPTS="-Djava.net.preferIPv6Addresses=true" \
    ...  \
    <image_name>

With docker-compose

Set the environment variables in the environment section of the .yml file as illustrated below.

...
environment:
      SONAR_JDBC_URL: jdbc:postgresql://db:5432/sonar
      SONAR_JDBC_USERNAME: sonar
      SONAR_JDBC_PASSWORD: sonar
      JAVA_TOOL_OPTIONS: ‘-Djava.net.preferIPv6Addresses=true’
      SONAR_WEB_JAVAADDITIONALOPTS: ‘-Djava.net.preferIPv6Addresses=true’

...

IPv6 is not officially supported for the Docker images of the Data Center Edition.

Keeping user sessions alive on server restart

To maintain your user sessions accross server restarts:

• Store the JWT token you generated during pre-installation in the SONAR_AUTH_JWTBASE64HS256SECRET system property.

See also Defining a JWT token.

Related pages

• Installation overview

• Prepare the Docker installation

• Advanced setup

• Setting system properties

• Configuring network security features:

  • Securing behind a proxy

  • Network rules