docs(setup): Add setup docs and easy install script

deo002 · deo002 · commit 47a515ab044f · 2025-09-09T11:03:59.000+05:30
Signed-off-by: deo002 &lt;oberoidearsh@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -57,111 +57,57 @@ As the response of the request, a JWT will be returned. Use this JWT with the
 `Authorization` header (as `-H "Authorization: <JWT>"`) to access endpoints
 requiring authentication.
 
+## Prerequisites
 
-## Prerequisite
+Before setting up the project, ensure the following tools are installed on your system:
 
-Before proceeding, make sure you have the following installed on your system:
+### 1. Golang (Go)
 
+You’ll need Go installed to build and run the project.  
+👉 [Official installation guide](https://go.dev/doc/install)
 
+### 2. PostgreSQL (v14 or later)
 
+The project uses PostgreSQL as its database. You can install it via:
 
-- Install Golang
-
-Follow the official instructions to install Golang:  
-👉 [https://go.dev/doc/install](https://go.dev/doc/install)
-
----
-
-- Install golang-migrate CLI (For Linux & MacOs)
+#### Option A: Package Manager (Linux example)
 
 ```bash
-curl -L https://github.com/golang-migrate/migrate/releases/latest/download/migrate.linux-amd64.tar.gz | tar xvz
-sudo mv migrate /usr/local/bin/
+sudo apt update
+sudo apt install postgresql
 ```
 
-## How to run this project?
-
-- Clone this Project and Navigate to the folder.
+#### Option B: Official Installer
 
-``` bash
-git clone https://github.com/fossology/LicenseDb.git
-cd LicenseDb
-```
+Download and run the official installer for your operating system from the PostgreSQL website.
+👉 [https://www.postgresql.org/download/](https://www.postgresql.org/download/)
 
-- Create the `external_ref_fields.yaml` file in the root directory of the project and change the
-  values of the extra license json keys as per your requirement.
+### 3. Install golang-migrate CLI
 
-```bash
-cp external_ref_fields.example.yaml external_ref_fields.yaml
-vim external_ref_fields.yaml
-```
+### 4. Install swagger document generator
 
-- Generate Go struct for the extra fields listed in the external_ref_fields.yaml.
+You'll need```swag``` installed to build swagger docs.
 
 ```bash
-go generate ./...
+go install github.com/swaggo/swag/cmd/swag@latest
 ```
 
-- Build the project using following command.
+#### For Linux & macOS
 
 ```bash
-go build ./cmd/laas
-```
-
-- Create the `.env` file in the root directory of the project and change the
-  values of the environment variables as per your requirement.
-
-```bash
-cp configs/.env.dev.example .env
-vim .env
-```
-
-- Run the migration files.
-```bash
-migrate -path pkg/db/migrations -database "postgres://fossy:fossy@localhost:5432/licensedb?sslmode=disable" up
-```
-
-- Run the executable.
-
-```bash
-./laas
-```
-
-- You can directly run it by the following command.
-
-```bash
-go run ./cmd/laas
+curl -L https://github.com/golang-migrate/migrate/releases/latest/download/migrate.linux-amd64.tar.gz | tar xvz
+sudo mv migrate /usr/local/bin/
 ```
 
-### Create first user
-Connect to the database using `psql` with the following command.
-```bash
-psql -h localhost -p 5432 -U fossy -d licensedb
-```
+For other platforms and installation methods, check the official docs:
+👉 [https://github.com/golang-migrate/migrate](https://github.com/golang-migrate/migrate)
 
-Run the following query to create the first user.
-```sql
-INSERT INTO users (user_name, user_password, user_level, display_name, user_email) VALUES ('<username>', '<password>', 'SUPER_ADMIN', '<display_name>', '<user_email>');
-```
+## How to run this project?
 
-### Generating Swagger Documentation
-1. Install [swag](https://github.com/swaggo/swag) using the following command.
-    ```bash
-    go install github.com/swaggo/swag/cmd/swag@latest
-    ```
-2. Run the following command to generate swagger documentation.
-    <!-- https://github.com/swaggo/swag/issues/817#issuecomment-730895033 -->
-    ```bash
-    swag init --parseDependency --generalInfo api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils --output ./cmd/laas/docs
-    ```
-3. Swagger documentation will be generated in `./cmd/laas/docs` folder.
-4. Run the project and navigate to `http://localhost:8080/swagger/index.html` to view the documentation.
-5. Optionally, after changing any documentation comments, format them with following command.
-    ```bash
-    swag fmt --generalInfo ./pkg/api/api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils
-    ```
+👉 Please follow the [Setup Guide](./SETUP.md) for step-by-step instructions on how to run the project.
 
 ### Testing (local)
+
 The PostgreSQL user `fossy` must have the `CREATEDB` privilege in order to:
 
 - Programmatically create and drop a test database.
@@ -172,7 +118,9 @@ sudo -u postgres psql; // log into psql with postgres super user
 ALTER USER fossy CREATEDB; // alter the role for fossy
 \du ;                     // verify role 
 ```
+
 Create the `.env.test` file file in the `configs` directory of the project.
-```
+
+```bash
 cp configs/.env.test.example .env.test
-```
+```
diff --git a/SETUP.md b/SETUP.md
@@ -0,0 +1,158 @@
+<!-- SPDX-FileCopyrightText: 2025 Dearsh Oberoi <dearsh.oberoi@siemens.com>
+
+     SPDX-License-Identifier: GPL-2.0-only
+-->
+
+# Project Setup
+
+There are 3 ways to run LicenseDb.
+
+## 1. Easy Install Script
+
+The easiest of them all is via the easy install script.
+
+- (Optional) Edit the ```configs/.env.dev.example``` to set the environment variables. If not done, default values will be taken.
+  
+- (Optional) Edit the ```external_ref_fields.example.yaml``` to extend the schema of licenses and obligations with custom fields. If not done, default values will be taken.
+
+- Run the easy install script to generate the app binary.
+  
+```bash
+./easy_install.sh
+```
+
+- Run the executable
+
+```bash
+./laas
+```
+
+Use the command below for more startup options.
+
+```bash
+./laas --help
+```
+
+## 2. Docker Installation
+
+- Build the app image
+  
+```bash
+docker build -t licensedb/latest
+```
+
+- Run the container
+  
+```bash
+docker compose up
+```
+
+## 3. Bare metal Installation
+
+### 1. Setting up the project
+
+- Create the `external_ref_fields.yaml` file in the root directory of the project to extend the schema of licenses and obligations with custom fields.
+
+```bash
+cp external_ref_fields.example.yaml external_ref_fields.yaml
+vim external_ref_fields.yaml
+```
+
+- Generate Go struct for the extra fields listed in the external_ref_fields.yaml.
+
+```bash
+go generate ./...
+```
+
+- Create the `.env` file in the root directory of the project and change the
+  values of the environment variables as per your requirement.
+
+```bash
+cp configs/.env.dev.example .env
+vim .env
+```
+
+- Build the project using following command.
+
+```bash
+go build ./cmd/laas
+```
+
+### 2. Setting up the database
+
+- Create database licensedb and provide user fossy all priviliges to it.
+  
+```sql
+CREATE DATABASE licensedb;
+
+CREATE USER fossy WITH PASSWORD 'fossy';
+
+GRANT ALL PRIVILEGES ON DATABASE licensedb TO fossy;
+```
+
+- Run the migration files.
+
+```bash
+migrate -path pkg/db/migrations -database "postgres://fossy:fossy@localhost:5432/licensedb?sslmode=disable" up
+```
+
+- Create first user
+
+Connect to the database using `psql` with the following command.
+
+```bash
+psql -h localhost -p 5432 -U fossy -d licensedb
+```
+
+Run the following query to create the first user.
+
+```sql
+INSERT INTO users (user_name, user_password, user_level, display_name, user_email) VALUES ('<username>', '<password>', 'SUPER_ADMIN', '<display_name>', '<user_email>');
+```
+
+### 3. Run the executable
+
+```bash
+./laas
+```
+
+Use the command below for more startup options.
+
+```bash
+./laas --help
+```
+
+- You can directly run it by the following command.
+
+```bash
+go run ./cmd/laas
+```
+
+## Post Install
+
+- ### Generating Swagger Documentation
+
+  - This step can be skipped if installation is done via the ```easy_install``` script.
+  - Install [swag](https://github.com/swaggo/swag) using the following command.
+
+      ```bash
+      go install github.com/swaggo/swag/cmd/swag@latest
+      ```
+
+  - Run the following command to generate swagger documentation.
+      <!-- https://github.com/swaggo/swag/issues/817#issuecomment-730895033 -->
+      ```bash
+      swag init --parseDependency --generalInfo api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils --output ./cmd/laas/docs
+      ```
+
+  - Swagger documentation will be generated in `./cmd/laas/docs` folder.
+  - Run the project and navigate to `http://localhost:8080/swagger/index.html` to view the documentation.
+  - After changing any documentation comments, format them with following command.
+
+      ```bash
+      swag fmt --generalInfo ./pkg/api/api.go --dir ./pkg/api,./pkg/auth,./pkg/db,./pkg/models,./pkg/utils
+      ```
+
+- The super admin user can only create new app users and import licenses and obligations.
+
+  To gain further capabilities, create a new admin user via the swagger docs or via the [LicenseDb UI](https://github.com/fossology/LicenseDb-UI).
diff --git a/cmd/laas/main.go b/cmd/laas/main.go
@@ -28,9 +28,9 @@ import (
 
 // declare flags to input the basic requirement of database connection and the path of the data file
 var (
-	datafile = flag.String("datafile", "licenseRef.json", "datafile path")
+	datafile = flag.String("datafile", "licenseRef.json", "(optional) path of the file from which licenses are to be imported")
 	// auto-update the database
-	populatedb = flag.Bool("populatedb", false, "boolean variable to update database")
+	populatedb = flag.Bool("populatedb", false, "(optional) boolean variable to populate database with licences, obligation types and classifications on start up")
 )
 
 func main() {
diff --git a/configs/.env.dev.example b/configs/.env.dev.example
@@ -9,34 +9,35 @@ READ_API_AUTHENTICATION_ENABLED=false
 
 PORT=8080
 
-# OIDC Provider (To be set if OIDC Authentication support required)
+# Email Password JWT Token Configuration
+DEFAULT_ISSUER=http://localhost:5000
+
+# OIDC Provider (Optional, to be set if OIDC Authentication support required)
 # The URL for retrieving keys for Token Parsing
-JWKS_URI=https://provider/keys
+# JWKS_URI=https://provider/keys
 
 # The field in ID Token that is to be used as username
-OIDC_USERNAME_KEY=employee_id
+# OIDC_USERNAME_KEY=employee_id
 
 # The field in ID Token that is to be used as email
-OIDC_EMAIL_KEY=mail
+# OIDC_EMAIL_KEY=mail
 
 # The issuer url
-OIDC_ISSUER=https://provider
+# OIDC_ISSUER=https://provider
 
 # The field in ID Token that is used as display name
-OIDC_DISPLAYNAME_KEY=display_name
+# OIDC_DISPLAYNAME_KEY=display_name
  
 # Some OIDC providers do not provide the "alg" header in their key set(ex. AzureAD)
 # This env variable, if set, will be used for signing while verifying the JWT signature
 # (Make sure it's same as the signing algorithm used by the provider)
 #
 # For OIDC providers that provide the "alg" header in their key set, there is no need for this to be set
-OIDC_SIGNING_ALG=RS256
+# OIDC_SIGNING_ALG=RS256
 
 # LicenseDB M2M Configuration (To be set if M2M communication support required)
 # This field's should be equal to the oidc instance's client id
-OIDC_CLIENT_TO_USER_MAPPER_CLAIM=azp
-
-
+# OIDC_CLIENT_TO_USER_MAPPER_CLAIM=azp
 
 # Database info 
 DB_NAME=licensedb
@@ -49,4 +50,4 @@ DB_HOST=localhost
 # This value can be adjusted based on the requirements of the similarity search
 # A lower value will result in more matches, while a higher value will be more strict
 # Default is set to 0.7, but can be changed to a higher value like 0.8 or 0.9 for stricter matching
-SIMILARITY_THRESHOLD = 0.8   
+SIMILARITY_THRESHOLD = 0.9
diff --git a/easy_install.sh b/easy_install.sh
diff --git a/external_ref_fields.example.yaml b/external_ref_fields.example.yaml
