diff --git a/doc/docs/user-guide/service/quick-start-guide.md b/doc/docs/user-guide/service/quick-start-guide.md index 5cd9c41a..2c500225 100644 --- a/doc/docs/user-guide/service/quick-start-guide.md +++ b/doc/docs/user-guide/service/quick-start-guide.md @@ -1,84 +1,67 @@ -# Quick Start Guide & Build +# Quick Start Guide -## 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) +Minimal configuration to set up and run the LPVS GitHub service locally. --- -## Quick Start Guide +## Setting up your project to interact with _LPVS_ service -### 1. Setting up your project to interact with _LPVS_ +To enable _LPVS_ license scanning for your project, you need to set up GitHub Webhooks. -To enable _LPVS_ license scanning for your project, you need to set up GitHub Webhooks: +* Create a personal Github access token (`personal-token`): -1.1 Create a personal github access token (`personal-token`): + - Follow the instructions [here](/doc/docs/user-guide/service/webhook.md#create-a-personal-github-access-token) to create a personal access token with the necessary permissions. -- 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. +!!! warning -> [!NOTE] -> Pay attention that the token must be copied immediately after creation, because you will not be able to see it later!! + 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`): +* 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). + - The ngrok agent authenticates with an authtoken. Your authtoken is available on the ngrok [portal](https://dashboard.ngrok.com/get-started/your-authtoken). --- -### 2. Using pre-built _LPVS_ Docker images +## 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 +### Setting up _LPVS_ Docker environment variables -2.1.1 Open `docker-compose.yml` file. +* Open `docker-compose-quick.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 +* 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). +* 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 +### Running _LPVS_ and MySQL Docker images with Docker Compose -2.2.1 Start the _LPVS_ services: +* Start the _LPVS_ services: ```bash docker compose -f docker-compose-quick.yml up -d ``` -To stop the _LPVS_ services, use next command: +* 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: +## Setting up your project to interact with _LPVS_ -- 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`. +Configure the [webhook](/doc/docs/user-guide/service/webhook.md#configure-the-webhook-in-your-github-repository-settings) in your GitHub repository settings 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/doc/docs/user-guide/service/webhook.md b/doc/docs/user-guide/service/webhook.md index 47aeb447..b71e0fcc 100644 --- a/doc/docs/user-guide/service/webhook.md +++ b/doc/docs/user-guide/service/webhook.md @@ -18,6 +18,20 @@ to create a personal access token (`personal-token`) with the necessary permissi --- +## (Optional) Configure Ngrok reverse proxy + +To configure GitHub access to a personal server, you need to expose the URL to an external API. If the server has a dedicated IP address or domain, this step can be omitted. + +- Install ngrok and connect your account from [Ngrok guide](https://ngrok.com/docs/getting-started/#step-2-install-the-ngrok-agent) (follow steps 1 and 2). + +- If ngrok included in docker compose, auth token can be found on [Ngrok portal](https://dashboard.ngrok.com/get-started/your-authtoken). + +- Run ngrok using the command: + +```bash +ngrok http 7896 +``` + ## Configure the webhook in your GitHub repository settings Follow the next steps: @@ -30,15 +44,12 @@ Follow the next steps: ![step2](../../img/webhook/step_1_2.png) -- Fill in the `Payload URL` with: `http://:7896/webhooks`. +- Fill in the `Payload URL` with: `http:///webhooks`. !!! note - 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](https://ngrok.com/docs/getting-started/#step-2-install-the-ngrok-agent) (follow steps 1 and 2). - - - Run ngrok using the command: `ngrok http 7896`. + If you're using ngrok, the `Payload URL` can be found on localhost: `http://127.0.0.1:4040/`. + It should be like `https://50be-62-205-136-206.ngrok-free.app/`. - Specify the content type as `application/json`. - Fill in the `Secret` field with the passphrase: `LPVS`. diff --git a/doc/mkdocs.yml b/doc/mkdocs.yml index 6b1b6b32..b988c785 100644 --- a/doc/mkdocs.yml +++ b/doc/mkdocs.yml @@ -28,7 +28,7 @@ plugins: nav: - Home: index.md - #- Getting Started: getting-started.md + - Quick Start Guide: user-guide/service/quick-start-guide.md - User Guide: - User guide: user-guide/README.md - Service mode: diff --git a/docker-compose-quick.yml b/docker-compose-quick.yml index ccc54d56..d9c92055 100644 --- a/docker-compose-quick.yml +++ b/docker-compose-quick.yml @@ -11,8 +11,6 @@ services: - "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 @@ -33,10 +31,6 @@ services: - 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: @@ -57,9 +51,7 @@ services: 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