Install Linty Platform

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 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 (Community Edition)
4.0.0 (latest)	10.7.0
3.1.0	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

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 the 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.

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

Manually 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 / restart / stop linty service:

sudo systemctl start linty
sudo systemctl restart linty
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
      ...

Docker Image Content

SonarQube Community Edition
All Linty Plugins (VHDL, Verilog/SystemVerilog, Tcl, Code coverage, etc.)
JDK 17