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. Installation process is the same whether your have purchased Linty Ultra or not.

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.1 (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

Requirements

Hardware

Memory: At least 2GB of free RAM is necessary to run the web server and the database.
CPU: There will not be a heavy usage of CPU server-side. Invest more on CPU scanner-side.
Disk:
- Hard drives that have excellent read & write performance (SSD) are highly recommended.
- Necessary disk space will depend on how much code you analyze. 10GB should already allow you to store data for several large projects.

Network

No external connection is needed to run the Linty platform.

Operating System

Linty runs on Linux. We recommend Ubuntu. But distribution is up to you.
Docker Engine (with containerd and Docker Compose) 23 or greater should be installed

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 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>
    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 down

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

services:
  linty-server:
    ...
    image: lintyservices/linty-server:<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 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 down

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

Securing the server behind a proxy (nginx)

Let’s say that the URL to access the Linty server would be: https://linty.my-domain.com

Install and configure nginx

Install nginx:

sudo apt install nginx

Create linty.my-domain.com file in /etc/nginx/sites-available:

cd /etc/nginx/sites-available
sudo vi linty.my-domain.com

With the following content:

server {
  listen 80;
  server_name linty.my-domain.com www.linty.my-domain.com;
}

Restart nginx:

sudo ln -s /etc/nginx/sites-available/linty.my-domain.com /etc/nginx/sites-enabled/
sudo systemctl restart nginx
sudo systemctl status nginx

Generate SSL certificates with Let’s Encrypt

See for instance this DigitalOcean tutorial.

sudo apt install python3-acme python3-certbot python3-mock python3-openssl python3-pkg-resources python3-pyparsing python3-zope.interface
sudo apt install python3-certbot-nginx

sudo certbot --nginx -d linty.my-domain.com -d www.linty.my-domain.com

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator nginx, Installer nginx
Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): my-email-address@my-domain.com
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at
https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf. You must
agree in order to register with the ACME server at
https://acme-v02.api.letsencrypt.org/directory
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: N
Obtaining a new certificate
Performing the following challenges:
http-01 challenge for linty.my-domain.com
http-01 challenge for www.linty.my-domain.com
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/linty.my-domain.com
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/linty.my-domain.com

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/linty.my-domain.com
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/linty.my-domain.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled https://linty.my-domain.com
and https://www.linty.my-domain.com

Update nginx configuration

sudo vi /etc/nginx/sites-available/linty.my-domain.com

With below content (see lines not commented with ‘managed by Certbot’):

server {
    server_name linty.my-domain.com www.linty.my-domain.com;

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/linty.my-domain.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/linty.my-domain.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

    if ($host = www.linty.my-domain.com) {
        return 301 https://linty.my-domain.com$request_uri;
    }

    client_max_body_size 500M;

    location / {
        proxy_pass http://localhost:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
    }
}
server {
    if ($host = www.linty.my-domain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    if ($host = linty.my-domain.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;
    server_name linty.my-domain.com www.linty.my-domain.com;
    return 404; # managed by Certbot
}

Restart nginx:

sudo systemctl restart nginx
sudo systemctl status nginx

In your browser, check that SonarQube web interface is displayed at https://linty.my-domain.com and that you can login. Check that:

http://linty.my-domain.com/ redirects to https://linty.my-domain.com/
http://www.linty.my-domain.com and https://www.linty.my-domain.com redirect to https://linty.my-domain.com/

Docker Image Content

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