quick-start-guide-and-build.md

Quick Start Guide & Build

Contents

Quick Start Guide

1. Setting up your project to interact with LPVS
2. Using pre-built LPVS Docker images

How to Build and Run LPVS from Source Code

1. Build Prerequisites
2. Create Necessary MySQL Database and User (optional if not using a database)
3. Setting up LPVS application.properties
4. Build LPVS Application with Maven and Run it

---

Quick Start Guide

1. Setting up your project to interact with LPVS

To enable LPVS license scanning for your project, you need to set up GitHub Webhooks:

1.1 Create a personal github access token (personal-token):

• Follow the instructions here to create a personal access token with the necessary permissions.

Note

Pay attention that the token must be copied immediately after creation, because you will not be able to see it later!!

2.1 Configure the webhook in your GitHub repository settings:

• Go to Settings -> Webhooks.
• Click on Add webhook.
• Fill in the Payload URL with: http://<IP where LPVS is running>:7896/webhooks.

  If you're using ngrok, the Payload URL should be like https://50be-62-205-136-206.ngrok-free.app/webhooks.

  • Install ngrok and connect your account from here (follow steps 1 and 2).
  • Run ngrok using the command: ngrok http 7896.
• Specify the content type as application/json.
• Fill in the Secret field with the passphrase: LPVS.
• Save the same passphrase in github.secret of the LPVS backend application.properties or docker-compose.yml files.
• Select Let me select individual events -> Pull requests (make sure only Pull requests is selected).
• Set the webhook to Active.
• Click Add Webhook.

Configuration from your project side is now complete!

Alternatively, you can use the Pull Request Single Scan API to analyze the code of a specific pull request. Please refer to the API Documentation for more information.

---

2. Using pre-built LPVS Docker images

This section explains how to download and run pre-built LPVS Docker images without building the LPVS project.

For the Docker deployment scenario, you may need to fill in the environment variables in the docker-compose.yml file.

2.1 Setting up LPVS Docker environment variables

2.1.1 Open docker-compose.yml file.

2.1.2 In the environment part of the lpvs service, find ## Github data for fetching code and fill in the github login and personal token that was generated earlier

- github.login=<github-login>
- github.token=<personal-token>

2.1.3 In case you plan to use a database user other than root reflect this in the appropriate lines in the ## Database Configuration part of the lpvs service in environment section:

- spring.datasource.username=user
- spring.datasource.password=password  

2.1.4 Make the following changes in the environment section of mysqldb service near MYSQL_ROOT_PASSWORD value:

- MYSQL_USER: user
- MYSQL_PASSWORD: password

If you are using only the root user, make the following change:

- spring.datasource.username=root
- spring.datasource.password=rootpassword

- MYSQL_ROOT_PASSWORD: rootpassword

In both cases, ensure that the MYSQL_ROOT_PASSWORD field is filled.

2.1.5 You can also change the directory for storing MySQL data by modifying the following line:

- ./mysql-lpvs-data:/var/lib/mysql # db storage by default it is a directory in the root of the repository with the name mysql-lpvs-data

2.2 Running LPVS and MySQL Docker images with Docker Compose

Start the LPVS services using docker-compose (before Compose V2):

docker-compose up -d

Start the LPVS services using docker compose (after Compose V2):

docker compose up -d

Stop the LPVS services using docker-compose (before Compose V2):

docker-compose down -v --rmi local

Stop the LPVS services using docker compose (after Compose V2):

docker compose down

You can now create a new pull request or update an existing one with commits. LPVS will automatically start scanning and provide comments about the licenses found in the project.

---

How to Build and Run LPVS from Source Code

1. Build Prerequisites

Before building LPVS from source code, ensure that you have the following prerequisites installed:

• SCANOSS Python package by following the guidelines. Install it using the command:

  pip3 install scanoss

  Make sure that the path variable is added to the environment:

  export PATH="$HOME/.local/bin:$PATH"

• MySQL server installed locally. Install it using the command:

  sudo apt install mysql-server

2. Create Necessary MySQL Database and User (optional if not using a database)

2.1 Start the MySQL server:

sudo service mysql start

2.2 Open the MySQL command line interface:

sudo mysql

2.3 Run the following commands in the MySQL command line interface to create the necessary database and user:

mysql> create database lpvs;
mysql> create user username;
mysql> grant all on lpvs.* to username;
mysql> alter user username identified by 'password';
mysql> exit;

2.4 (Optional) If you have an existing dump file, import it into the newly created database using the command:

mysql -u[username] -p[password] < src/main/resources/database_dump.sql

2.5 Fill in the license_list and license_conflicts tables with the information about permitted, restricted, and prohibited licenses, as well as their compatibility specifics. You can find an example database dump file in the repository at src/main/resources/database_dump.sql.

2.6 Update the following lines in the src/main/resources/application.properties file:

spring.datasource.username=username
spring.datasource.password=password

3. Setting up LPVS application.properties

Fill in the following lines in the src/main/resources/application.properties file:

# GitHub configuration (github.token and github.secret required)
github.token=
github.login=
github.api.url=
github.secret=LPVS

Note

For personal GitHub account use https://api.github.com in field github.api.url=.

# Used license scanner: scanoss (at the moment, only this scanner is supported)
scanner=scanoss

# Used license conflicts source:
# > option "db": take conflicts from MySQL database - 'license_conflicts' table (should be filled manually
# according to the example at 'src/main/resources/database_dump.sql')
# > option "scanner": take conflicts from the scanner response
  license_conflict=db

# DB configuration (username and password)
...
spring.datasource.username=
spring.datasource.password=

Alternatively, you can provide the necessary values using the following environment variables: LPVS_GITHUB_LOGIN, LPVS_GITHUB_TOKEN, LPVS_GITHUB_API_URL, LPVS_GITHUB_SECRET, and LPVS_LICENSE_CONFLICT.

4. Build LPVS Application with Maven and Run it

4.1 Service mode (default)

To build LPVS from source code and run it in the default service mode, follow these steps:

4.1.1 Build the LPVS application using Maven:

mvn clean install

4.1.2 Navigate to the target directory:

cd target/

4.1.3 Run the LPVS application.

Service is run using the following command:

java -jar lpvs-*.jar

Alternatively, you can provide the necessary values associated with GitHub and license using the command line:

java -jar -Dgithub.token=<my-token> -Dgithub.secret=<my-secret> lpvs-*.jar

Note

Use LPVS as the value for the -Dgithub.secret= parameter.

LPVS is now built and running. You can create a new pull request or update an existing one with commits, and LPVS will automatically start scanning and provide comments about the licenses found in the project.

4.2 Single scan mode

Alternatively, you can perform a one-time scan on a specific pull request using the single scan mode. Follow these steps:

4.2.1 Begin by running the installation and navigating to the target directory, similar to the process in service mode (refer to steps 4.1.1 and 4.1.2):

mvn clean install
cd target/

4.2.2 Execute the single scan with the following command:

java -jar -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL>

4.2.3 By default, the above command requires a pre-configured MySQL database. To avoid setting up the database, use the "singlescan" profile:

java -jar -Dspring.profiles.active=singlescan -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL>

These steps streamline the process, allowing you to run a scan on a single pull request without the need for a preconfigured database.

4.2.4 Available option to generate an HTML report and save it in a specified folder. Replace /path/to/your/folder with the full path to the folder where you want to save the HTML report, and your_report_filename.html with the desired filename for the report.

java -jar -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL> --build.html.report=</path/to/your/folder/your_report_filename.html>

These steps streamline the process, allowing you to run a scan on a single pull request without the need for a preconfigured database.

4.3 Use of LPVS JAR lpvs-x.y.z.jar in your project

4.3.1 Authenticating with a personal access token

You can authenticate to GitHub Packages with Apache Maven by editing your ~/.m2/settings.xml file to include your personal access token

Note

Create a token with minimally sufficient rights:

• Fine-grained tokens (recommended)
  Only select repositories -> Permissions -> Repository permissions -> Metadata -> Read-only
• Tokens (classic)
  Select scopes -> read:packages

Create a new ~/.m2/settings.xml file if one doesn't exist.

Example settings.xml

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">

  <activeProfiles>
    <activeProfile>github</activeProfile>
  </activeProfiles>

  <profiles>
    <profile>
      <id>github</id>
      <repositories>
         <repository>
          <id>github</id>
          <url>https://maven.pkg.github.com/samsung/lpvs</url>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </profile>
  </profiles>

  <servers>
    <server>
      <id>github</id>
      <username>USERNAME</username>
      <password>TOKEN</password>
    </server>
  </servers>
</settings>

Note

if your settings.xml file is not located in ~/.m2/settings.xml, then you need to add the -s path/to/file/settings.xml option to mvn command

4.3.2 Installing a package

Edit the <dependencies> element of the pom.xml file located in your project directory.

...
    <dependencies>
        <dependency>
            <groupId>com.lpvs</groupId>
            <artifactId>lpvs</artifactId>
            <version>x.y.z</version>
        </dependency>
    </dependencies>
...