Linty Documentation

Install Linty Platform

Table of Contents:

Linty Server / SonarQube versions
- Which SonarQube edition to use
Prerequisites
Deploy Linty platform
Stop and restart Linty
Run Linty as a service
Backup and restore database
- Backup database
  - Manual backup
  - Automated backups
- Restore database
Upgrade Linty
Migrate from a legacy (non-Docker) Linty platform
Install Linty documentation locally
Clean up before re-installing Linty from scratch
Debug
Add Additional Plugins
Docker Image Content
- linty-server
- linty-server-with-branch-support

Linty extends the SonarQube platform, the leader platform in clean code. Linty adds the following plugins:

VHDL: To analyze VHDL code
Verilog: To analyze Verilog/SystemVerilog code
Tcl: To analyse Tcl (Tool Command Language) scripts
ModelSim/QuestaSim Code Coverage: To decorate code from ModelSim code coverage reports

The Linty platform is made of two components:

A web server to display quality reports
A database (PostgreSQL) to store projects quality data

The Linty platform is provided as a Docker image. Please, follow below documentation to install and configure it.

If you already have your own SonarQube platform, download Linty plugins from Linty website into $SONARQUBE_HOME/extensions/plugins and restart your SonarQube platform. Then, jump directly to Configure Linty Platform.

Linty Server / SonarQube versions

Linty Server	Embedded SonarQube version Either Community or Developer Edition
3.1.0 (latest)	10.5.1
3.0.0	10.3.0
2.1.0	10.3.0
2.0.0	10.2.0
1.2.0	10.1.0
1.1.0	10.0.0
1.0.0	9.9.0

Which SonarQube edition to use

If you do not need branch or PR analysis support, install lintyservices/linty-server Docker image based on SonarQube Community Edition.

If you need branch and PR analysis support (recommended), use lintyservices/linty-server-branch-support Docker image based on SonarQube Developer Edition. SonarQube Developer Edition license to be purchased at https://www.sonarsource.com/plans-and-pricing/. Note that we can purchase it on your behalf.

Prerequisites

Linux host machine. We recommend Ubuntu. But distribution is up to you.
Docker Engine (with containerd and Docker Compose) 23 or greater
No external connection is needed to run the Linty platform

Deploy Linty platform

Create a linty user:

# Create new 'linty' user
sudo adduser linty
    
# Set 'linty' user's password if not asked during the previous step, ignore otherwise.
sudo passwd linty

# Add 'linty' to sudoers
#  - Ubuntu/Debian
sudo adduser linty sudo
#  - CentOS
sudo usermod -aG wheel linty
   
# Add 'linty' to 'docker' group
sudo groupadd docker
sudo usermod -aG docker linty

All the below commands (whatever the section) are to be run with linty user. So, let’s become linty user:
```
sudo su - linty
```
Create a new file: sudo vi /etc/sysctl.d/99-linty.conf, with the following content:
```
vm.max_map_count=524288
fs.file-max=131072
```
Reload kernel properties:
```
sudo sysctl --system
```
Create a directory to store Linty artifacts: $LINTY_HOME. We propose /opt/linty. But location is up to you.
```
sudo mkdir /opt/linty
sudo chown linty:linty /opt/linty
```

Create a new file: vi $LINTY_HOME/docker-compose.yml (Replace $LINTY_HOME with proper location). Replace <version> with proper lintyservices/linty-server or lintyservices/linty-server-branch-support image version. Feel free to change database name, user and password in both containers but do not forget to replace those values in subsequent commands as default linty values are used in this documentation. Double-check proper two-space indentation before saving the file.

version: "3.8"

services:
  linty-server:
    depends_on:
      - linty-database
    image: lintyservices/linty-server:<version>
    # Comment line above and uncomment line below to get branch and PR analysis support
    # image: lintyservices/linty-server-branch-support:<version>
    container_name: linty-server
    ports:
      - 9000:9000
    networks:
      - linty-network
    environment:
      - SONAR_JDBC_URL=jdbc:postgresql://linty-database:5432/linty_db_name
      - SONAR_JDBC_USERNAME=linty_db_user
      - SONAR_JDBC_PASSWORD=linty_db_password
    volumes:
      - linty_data:/opt/sonarqube/data
      - linty_logs:/opt/sonarqube/logs

  linty-database:
    image: postgres:15
    container_name: linty-database
    networks:
      - linty-network
    environment:
      - POSTGRES_DB=linty_db_name
      - POSTGRES_USER=linty_db_user
      - POSTGRES_PASSWORD=linty_db_password
    volumes:
      - linty_database:/var/lib/postgresql
      - linty_database_data:/var/lib/postgresql/data

volumes:
  linty_data:
  linty_logs:
  linty_database:
  linty_database_data:

networks:
  linty-network:

Create and start Linty:
```
cd $LINTY_HOME
docker compose up -d
```
Wait for a few seconds before browsing http://localhost:9000. Default credentials are admin/admin.
Change admin password when prompted
Accept usage of third-party plugins when prompted
You can now configure your Linty platform and scan your code

Stop and restart Linty

To stop Linty:

cd $LINTY_HOME
docker compose stop

To restart Linty:

cd $LINTY_HOME
docker compose start

Run Linty as a service

Create a new file: sudo vi /etc/systemd/system/linty.service. Replace $LINTY_HOME with proper location.

[Unit]
Description=Linty
Requires=docker.service
After=docker.service
[Service]
Type=simple
User=linty
Group=linty
PermissionsStartOnly=true
ExecStart=/usr/bin/docker compose -f $LINTY_HOME/docker-compose.yml up --force-recreate
ExecStop=/usr/bin/docker compose -f $LINTY_HOME/docker-compose.yml down
TimeoutStartSec=10
Restart=always
[Install]
WantedBy=multi-user.target

To take into account this new linty service, run once:
```
sudo systemctl daemon-reload
```
To automatically start linty service at boot, run once:
```
sudo systemctl enable linty
```

To manually start linty service:

sudo systemctl start linty

To manually stop linty service:

sudo systemctl stop linty

Backup and restore database

Create a directory to store database backups: $LINTY_BACKUP_DIR. We propose /opt/linty/backups. But location is up to you.

mkdir /opt/linty/backups

Backup database

Manual backup

docker exec linty-database /bin/bash \
  -c "/usr/bin/pg_dump -F c -U linty_db_user linty_db_name" \
  | gzip -9 > $LINTY_BACKUP_DIR/linty-database-backup.sql.gz 

Automated backups

Create a new file: vi $LINTY_HOME/linty-database-backup.sh (Replace $LINTY_HOME with proper location) with the following content (Replace $LINTY_BACKUP with proper location):

#!/bin/bash
set -e

DEST_DIR=/opt/linty/backups
DEST=$DEST_DIR/linty-database-backup-$(date +%Y-%m-%d-%H%M).sql
KEEP_DAYS=15

docker exec linty-database /bin/bash -c "/usr/bin/pg_dump -F c -U linty_db_user linty_db_name" > $DEST
gzip -9 $DEST

find $DEST_DIR -type f -mtime +$KEEP_DAYS -delete

Make this script executable:
```
chmod +x linty-database-backup.sh 
```

Add cron job to back up your database on a regular basis:

sudo crontab -e

# For instance, add the following line to back up the database every day at 2:00 AM
# (replace $LINTY_HOME with proper location):
0 2 * * * sudo su linty -c '$LINTY_HOME/linty-database-backup.sh'

On a regular basis, copy $LINTY_BACKUP_DIR directory to another machine to have redundant backup

Restore database

Stop Linty:

# If installed as a service:
sudo systemctl stop linty

# If not installed as a service:
cd $LINTY_HOME
docker compose stop

Start database container only:

cd $LINTY_HOME
docker compose up -d linty-database

Restore from database backup:

cd $LINTY_BACKUP_DIR
gzip -d -k linty-database-backup.sql.gz
docker cp linty-database-backup.sql linty-database:/var/lib/postgresql/data
docker exec linty-database psql -U linty_db_user -d postgres -c "DROP DATABASE linty_db_name;"
docker exec linty-database psql -U linty_db_user -d postgres -c "CREATE DATABASE linty_db_name OWNER linty_db_user;"
docker exec linty-database pg_restore -U linty_db_user -d linty_db_name /var/lib/postgresql/data/linty-database-backup.sql
docker container stop linty-database
docker container rm linty-server linty-database
docker volume rm linty_linty_data

Restart Linty:

# If installed as a service:
sudo systemctl restart linty

# If not installed as a service:
cd $LINTY_HOME
docker compose up -d

Upgrade Linty

Back up your Linty database: See “Backup database” section.
Carefully read the upgrade notes.

Stop Linty:

# If installed as a service:
sudo systemctl stop linty

# If not installed as a service:
cd $LINTY_HOME
docker compose stop

Update version of lintyservices/linty-server or lintyservices/linty-server-branch-support Docker image in $LINTY_HOME/docker-compose.yml:

services:
  linty-server:
    ...
    image: lintyservices/linty-server:<new-version>
    # image: lintyservices/linty-server-branch-support:<new-version>

Restart Linty:

# If installed as a service:
sudo systemctl restart linty

# If not installed as a service:
cd $LINTY_HOME
docker compose up --force-recreate -d

Browse http://localhost:9000/setup and update database if required

Migrate from a legacy (non-Docker) Linty platform

If you are not running PostgreSQL 11 or greater, please contact Linty support before starting the migration.

Upgrade your SonarQube platform to the latest LTS (9.9.0) with latest Linty plugins
Shut down your current SonarQube platform
Follow “Create Linty platform” section. Replace database name, user and password with your current values.

Backup your current database:

/usr/bin/pg_dump -F c -U <db-user> <db-name> | gzip -9 > ./linty-database-backup.sql.gz 

Follow “Backup and restore database > Restore database” section with the backup you just created
Ask for a new license key

Install Linty documentation locally

Linty latest version of the documentation is available online.

Linty documentation can also be made available locally from you host machine if, for instance:

You do not have access to the Internet
You want to be able to access a specific version of the documentation (the one related to your Linty Server version, not the latest version that is available online)

To make the documentation available locally:

Add a linty-doc service to $LINTY_HOME/docker-compose.yml:

version: "3.8"

services:
  linty-server:
    ...

  linty-database:
    ...

  linty-doc:
    image: lintyservices/linty-doc:<version>  # <version> should match linty-server or linty-server-branch-support version
    container_name: linty-doc
    ports:
      - 8080:80
    networks:
      - linty-network

volumes:
  ...

networks:
  ...

Restart Linty:

# If installed as a service:
sudo systemctl restart linty

# If not installed as a service:
cd $LINTY_HOME
docker compose up --force-recreate -d

Browse local documentation at http://localhost:8080

Clean up before re-installing Linty from scratch

To start from scratch and run a fresh Linty platform:

Stop Linty:

# If installed as a service:
sudo systemctl stop linty

# If not installed as a service:
cd $LINTY_HOME
docker compose stop

Clean up:

# Remove existing Docker containers
docker container rm linty-server linty-database

# Remove existing Docker volumes
# Volume prefix is 'linty-'. It is the name of the directory containing your docker-compose.yml file followed by an underscore.
# Update the prefix accordingly if your docker-compose.yml file is not located in /opt/linty
docker volume rm \
  linty_linty_data \
  linty_linty_database \
  linty_linty_database_data \
  linty_linty_logs

Debug

To follow logs:

docker logs -f <container-name>

# To follow logs of linty-server:
docker logs -f linty-server

# To follow logs of linty-database:
docker logs -f linty-database

To enter a container with a bash:

docker exec -it <container_name> bash

# To debug linty-server:
docker exec -it linty-server bash

# To debug linty-database:
docker exec -it linty-database bash

Add Additional Plugins

To add additional plugins:

Create a new directory: mkdir /opt/linty/custom_plugins
Add your custom plugins to this directory

Update /opt/linty/docker-compose.yml as below:

services:
  linty-server:
    ...
    volumes:
      - /opt/linty/custom_plugins:/opt/sonarqube/extensions/custom_plugins
      ...

Install Linty Platform

Linty Server / SonarQube versions

Which SonarQube edition to use

Prerequisites

Deploy Linty platform

Stop and restart Linty

Run Linty as a service

Backup and restore database

Backup database

Manual backup

Automated backups

Restore database

Upgrade Linty

Migrate from a legacy (non-Docker) Linty platform

Install Linty documentation locally

Clean up before re-installing Linty from scratch

Debug

Add Additional Plugins

Docker Image Content

linty-server

linty-server-with-branch-support