From 71e4ae30aee6a4addedfb9e90488fb3466820538 Mon Sep 17 00:00:00 2001 From: Mykola Rudyk Date: Thu, 12 Sep 2024 09:52:14 +0300 Subject: [PATCH] feat: edit quick start guide --- README.md | 2 +- .../user-guide/service/quick-start-guide.md | 84 +++++++++++++++++++ docker-compose-quick.yml | 80 ++++++++++++++++++ 3 files changed, 165 insertions(+), 1 deletion(-) create mode 100644 doc/docs/user-guide/service/quick-start-guide.md create mode 100644 docker-compose-quick.yml diff --git a/README.md b/README.md index 056fbb7c..a696fc3f 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ With these features, _LPVS_ assists developers to manage license compliance for ## Quick Start Guide & Build -- [_LPVS_ quick start guide](doc/quick-start-guide-and-build.md#quick-start-guide-1) +- [_LPVS_ quick start guide](doc/docs/user-guide/service/quick-start-guide.md#quick-start-guide-1) - [How to Build and Run _LPVS_ from Source Code](doc/quick-start-guide-and-build.md#how-to-build-and-run-lpvs-from-source-code-1) --- diff --git a/doc/docs/user-guide/service/quick-start-guide.md b/doc/docs/user-guide/service/quick-start-guide.md new file mode 100644 index 00000000..5cd9c41a --- /dev/null +++ b/doc/docs/user-guide/service/quick-start-guide.md @@ -0,0 +1,84 @@ +# Quick Start Guide & Build + +## Contents + +### [Quick Start Guide](#quick-start-guide-1) + +1. [Setting up your project to interact with _LPVS_](#1-setting-up-your-project-to-interact-with-lpvs) +2. [Using pre-built _LPVS_ Docker images](#2-using-pre-built-lpvs-docker-images) +3. [Setting up your project to interact with _LPVS_](#3-setting-up-your-project-to-interact-with-lpvs) + +--- + +## 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](#https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) 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!! + +1.2 Get a personal ngrok auth token to expose your local service (`auth-token`): + +- The ngrok agent authenticates with an authtoken. Your authtoken is available on the ngrok [dashboard](https://dashboard.ngrok.com/get-started/your-authtoken). + +--- + +### 2. Using pre-built _LPVS_ Docker images + +This section explains how to download and run pre-built _LPVS_ Docker image with ngrok reverse proxy. + +For the Docker deployment scenario, you may need to set additional parameters described in [docker section](/doc/docs/user-guide/service/docker.md). + +#### 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 + +```yaml +- github.login= +- github.token= +``` + +2.1.3 In the `environment` part of the `ngrok` service, find `## Ngrok Auth token` and fill personal `token` from [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). + +```yaml +- NGROK_AUTHTOKEN= +``` + +#### 2.2 Running _LPVS_ and MySQL Docker images with Docker Compose + +2.2.1 Start the _LPVS_ services: + +```bash +docker compose -f docker-compose-quick.yml up -d +``` + +To stop the _LPVS_ services, use next command: + +```bash +docker compose -f docker-compose-quick.yml down +``` + +### 3. Setting up your project to interact with _LPVS_ + +3.1 Configure the [webhook](/doc/docs/user-guide/service/webhook.md#configure-the-webhook-in-your-github-repository-settings) in your GitHub repository settings: + +- Go to `Settings` -> `Webhooks`. +- Click on `Add webhook`. +- Fill in the `Payload URL` with: `:7896/webhooks`. + > The `Tunnel URL` can be found on localhost: `http://127.0.0.1:4040/`. +- Specify the content type as `application/json`. +- Fill in the `Secret` field with the passphrase: `LPVS`. +- 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! +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. diff --git a/docker-compose-quick.yml b/docker-compose-quick.yml new file mode 100644 index 00000000..ccc54d56 --- /dev/null +++ b/docker-compose-quick.yml @@ -0,0 +1,80 @@ +version: '3.4' + +services: + + lpvs: + build: + context: . + image: ghcr.io/samsung/lpvs:latest + restart: always + ports: + - "7896:7896" + environment: + ## Required if frontend and backend are different + #- frontend.main-page.url=http://localhost:3000 + #- cors.allowed-origin=http://localhost:3000 + ## Database Configuration + - spring.datasource.url=jdbc:mysql://mysqldb:3306/lpvs + - spring.datasource.username=root + - spring.datasource.password= + - spring.jpa.properties.hibernate.default_schema=lpvs + ## Github data for fetching code + - github.login= + - github.token= + - github.api.url=https://api.github.com + - github.secret=LPVS + ## Google OAuth Login + - spring.security.oauth2.client.registration.google.client-id=GOOGLE_CLIENT_ID + - spring.security.oauth2.client.registration.google.client-secret=GOOGLE_CLIENT_SECRET + - spring.security.oauth2.client.registration.google.redirect-uri=http://localhost:7896/login/oauth2/code/google + - spring.security.oauth2.client.registration.google.scope=profile, email + ## Github OAuth Login + - spring.security.oauth2.client.registration.github.client-id=GITHUB_CLIENT_ID + - spring.security.oauth2.client.registration.github.client-secret=GITHUB_CLIENT_SECRET + - spring.security.oauth2.client.registration.github.redirect-uri=http://localhost:7896/login/oauth2/code/github + - spring.security.oauth2.client.registration.github.scope=user + ## Github Enterprise Configuration if necessary + #- spring.security.oauth2.client.provider.github.authorization-uri=https://HOSTNAME/login/oauth/authorize + #- spring.security.oauth2.client.provider.github.token-uri=https://HOSTNAME/login/oauth/access_token + #- spring.security.oauth2.client.provider.github.user-info-uri=https://HOSTNAME/api/v3/user + + depends_on: + mysqldb: + condition: service_healthy + networks: + - lpvs + + mysqldb: + image: mysql:latest + restart: always + ports: + - "3306:3306" + environment: + MYSQL_ALLOW_EMPTY_PASSWORD: "yes" + MYSQL_ROOT_PASSWORD: "" + healthcheck: + test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"] + timeout: 20s + retries: 10 + volumes: + #- ./mysql-lpvs-data:/var/lib/mysql # db storage + - ./src/main/resources/database_dump.sql:/docker-entrypoint-initdb.d/init.sql # init for creating db lpvs with predifined tables + ##- ./conf/my.cnf:/etc/mysql/my.cnf # custom mysql config- if needed + networks: + - lpvs + + ngrok: + image: wernight/ngrok + command: ngrok http lpvs:7896 + ## NGROK Auth token + environment: + - NGROK_AUTHTOKEN= + ports: + - "4040:4040" + depends_on: + - lpvs + networks: + - lpvs + +networks: + lpvs: