How to Install SonarQube on Ubuntu from Scratch

Introduction

SonarQube is a powerful tool for code quality analysis and continuous inspection. This guide explains how to install SonarQube on Ubuntu step by step, including the installation of Java, SonarQube, and the Sonar Scanner.

By the end, you’ll have a fully functional SonarQube server ready to analyze your code.

Prerequisites

• A clean Ubuntu server (20.04 or later).
• Minimum 2GB RAM (4GB recommended).
• A non-root user with sudo privileges.
• Internet access.

Step 1: Update the System

Before starting, update the system packages:

sudo apt update && sudo apt upgrade -y

Step 2: Install Java (OpenJDK 11)

SonarQube requires Java to run. Install OpenJDK 11:

sudo apt install openjdk-11-jdk -y

Verify the installation:

java -version

You should see output similar to:

openjdk version "11.0.x"

Step 2–1: Install PostgreSQL Database

SonarQube uses a database to store its configuration and analysis data. We will install PostgreSQL and set up a dedicated database and user.

Install PostgreSQL

If PostgreSQL is not already installed, you can install it using:

sudo apt install postgresql postgresql-contrib -y

Create a Database and User for SonarQube

1. Switch to the PostgreSQL user:

• sudo -i -u postgres

2. Open the PostgreSQL interactive terminal:

psql

3. Create the sonarqube database:

CREATE DATABASE sonarqube;

4. Create a user for SonarQube with a password (P@ssw0rd):

CREATE USER sonar WITH ENCRYPTED PASSWORD 'P@ssw0rd';

5. Grant the sonar user access to the sonarqube database:

GRANT ALL PRIVILEGES ON DATABASE sonarqube TO sonar;

6. Exit the PostgreSQL terminal:

\q

7. Exit the PostgreSQL user session:

exit

Step 3: Download and Install SonarQube

1. Download the Latest SonarQube Version: Visit the SonarQube Downloads page to get the latest version URL, or use the example below:

wget https://binaries.sonarsource.com/Distribution/sonarqube/sonarqube-10.7.0.96327.zip 

if above link no longer work, visit https://www.sonarsource.com/ to get the url.

2. Install Unzip and Extract the Files:

sudo apt install unzip -y 
unzip sonarqube-<version>.zip

3. Move SonarQube to /opt:

sudo mv sonarqube-<version> /opt/sonarqube

Step 4: Create a Dedicated User for SonarQube

For security, create a sonarqube user:

sudo useradd -m -d /opt/sonarqube -r -s /bin/bash sonar

Change ownership of the SonarQube directory:

sudo chown -R sonar:sonar /opt/sonarqube

Step 5: Configure SonarQube

1. Open the configuration file:

sudo nano /opt/sonarqube/conf/sonar.properties

2. Update the following settings:

• Database Configuration (if using PostgreSQL, ensure it’s set up):

sonar.jdbc.username=sonar
sonar.jdbc.password=P@ssw0rd
sonar.jdbc.url=jdbc:postgresql://localhost/sonarqube

• Bind SonarQube to the server IP:

sonar.web.host=0.0.0.0
sonar.web.port=9000

Save and exit (Ctrl + X, then Y).

Step 6: Run SonarQube

1. login as sonar user:

su sonar

2. Run the service

cd /opt/sonarqube/bin/linux-x86-64/
./sonar.sh start

3. check the service run

./sonar.sh status

Step 6–1: Troubleshoot VMMax Error (Optional)

If you found the error message indicates that Elasticsearch is failing to start because the vm.max_map_count setting, which controls the maximum number of virtual memory areas a process can use, is too low. This is a common issue when running Elasticsearch on Linux systems. Elasticsearch requires vm.max_map_count to be set to at least 262144 for optimal performance.

Steps to Resolve the Error

Step 1: Check the Current Setting

You can check the current vm.max_map_count value with the following command:

sysctl vm.max_map_count

Step 2: Increase the vm.max_map_count Value

To fix the issue, you need to increase this value.

1. Temporarily change the value (until the next reboot): Run the following command to immediately set vm.max_map_count to 262144:

sudo sysctl -w vm.max_map_count=262144

2. Make the change permanent: To ensure that the change persists across reboots, edit the /etc/sysctl.conf file:

sudo nano /etc/sysctl.conf

3. Add the following line at the end of the file:

vm.max_map_count=262144

4. After saving and closing the file, apply the changes:

sudo sysctl -p

Step 7: Install Sonar Scanner

Sonar Scanner is a client-side tool responsible for:

1. Analyzing Source Code: It scans the source code of your project, identifies issues, and generates a detailed analysis report.
2. Sending Reports to SonarQube: The report created by Sonar Scanner is uploaded to the SonarQube server for visualization and deeper insights.

Sonar Scanner is effectively the bridge between your codebase and the SonarQube server.

Please follow the following step:

1. Download the Latest Sonar Scanner:

sudo wget  https://binaries.sonarsource.com/Distribution/sonar-scanner-cli/sonar-scanner-cli-6.2.1.4610-linux-x64.zip 

2. Extract and Move to /opt:

sudo unzip  sonar-scanner-cli-6.2.1.4610-linux-x64.zip
sudo mv sonar-scanner-6.2.1.4610-linux-x64 /opt/sonar-scannermv sonar-scanner-cli-6.2.1.4610-linux-x64 /opt/sonar-scanner

Set permisson and owner

sudo chown -R sonar:sonar /opt/sonar-scanner

Create the .scannerwork Directory

If the .scannerwork directory is missing, create it manually and ensure the correct permissions are set.

sudo mkdir -p /opt/sonar-scanner/.scannerwork
sudo chown -R sonar:sonar /opt/sonar-scanner/.scannerwork
sudo chmod 755 /opt/sonar-scanner/.scannerwork

3. Add to PATH:

echo 'export PATH=$PATH:/opt/sonar-scanner/bin' >> ~/.bashrc
source ~/.bashrc

4. Verify Installation:

sonar-scanner --version

Step 8: Access SonarQube

1. Open your browser and navigate to:

http://<server-ip>:9000

2. Log in with the default credentials:

• Username: admin
• Password: admin

2. Change the default password for security.

Step 9: Create Sample Project on SonarQube

Choose global setting and Create Project

Get the Project key as above

Step 9–1: Generate a Token

1. Once logged in, click on your user profile icon in the top right corner of the SonarQube interface.
2. In the dropdown menu, select “My Account”.
3. On the “My Account” page, navigate to the “Security” tab.
4. Under the “Tokens” section, click on the “Generate Tokens” button.
5. Enter a name for the token (e.g., “jenkins_token”) and click Generate.
6. Copy the generated token immediately because this is the only time the token will be displayed. You won’t be able to see it again after you leave the page.

Step 10: Analyze Code with Sonar Scanner

1. Navigate to your project directory.
2. Run Sonar Scanner:

You will need to get the projecr key and token by creating on sonarqube dashoard.

sonar-scanner \
  -Dsonar.projectKey=<your_project_key> \
  -Dsonar.sources=. \
  -Dsonar.host.url=http://<server-ip>:9000 \
  -Dsonar.login=<your_generated_token>bash

for example

sonar-scanner \
  -Dsonar.projectKey=sqa_c4443ef931842f00b42751bf938e3b64306e1493 \
  -Dsonar.sources=. \
  -Dsonar.exclusions=/opt/containerd/** \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.login=sqa_c4443ef931842f00b42751bf938e3b64306e1493

Step 11: Troubleshooting (/opt/.scannerwork error)

SonarScanner is attempting to create a working directory at /opt/.scannerwork but fails due to permissions or configuration issues. Here's how you can resolve this:

Problem Breakdown

1. Default Working Directory: The default working directory for the SonarScanner is set to /opt/.scannerwork, which may not have the necessary permissions for the user running the scanner.
2. Permission Issue: The user might not have write access to /opt, causing the directory creation to fail.

Solution: Fix Working Directory Issue

Option 1: Grant Permissions to /opt (Not Recommended)

While you could allow write access to /opt, it’s not ideal because /opt is typically reserved for system-wide installed applications. Instead, use Option 2.

Option 2: Configure a Custom Working Directory

Redirect the working directory to a location where the scanner’s user has full access, such as the user’s home directory.

1. Edit the SonarScanner Configuration: Modify the sonar-scanner.properties file to set a custom working directory.
2. Locate the configuration file:

sudo nano /opt/sonar-scanner/conf/sonar-scanner.properties

3. Add or modify the following line:

sonar.working.directory=/opt/sonar-scanner/.scannerwork
sonar.exclusions=/opt/containerd/**

Replace /home/sonar with the appropriate path for the user running the scanner. e.g. /opt/sonar-scanner

4.Create the Directory: Ensure the directory exists and is writable by the user running SonarScanner:

sudo mkdir -p /opt/sonar-scanner/.scannerwork
sudo chown -R sonar:sonar /opt/sonar-scanner/.scannerwork
sudo chmod 755 /opt/sonar-scanner/.scannerwork

5. Verify Ownership and Permissions: Ensure the correct permissions:

ls -ld /opet/sonar-scanner/.scannerwork

If the issue persists, double-check:

• Permissions on /opt/sonar-scanner/.scannerwork.
• The correct ownership (sonar:sonar) of the directory.

SonarQube and Sonar Scanner are now set up and ready for use. You can analyze your code for quality issues and security vulnerabilities. Explore its dashboards to improve your codebase.