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

Signed-off-by: deo002 <[email protected]>

Author: deo002

README.md

@@ -57,111 +57,71 @@ 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.
 
-
 ## Prerequisite
 
-Before proceeding, make sure you have the following installed on your system:
-
-
+Before setting up the project, ensure the following tools are installed on your system:
 
+### 1. Golang (Go)
 
-- Install Golang
+You’ll need Go installed to build and run the project.  
+👉 [Official installation guide](https://go.dev/doc/install)
 
-Follow the official instructions to install Golang:  
-👉 [https://go.dev/doc/install](https://go.dev/doc/install)
+### 2. PostgreSQL (v14 or later)
 
----
+The project uses PostgreSQL as its database. You can install it via:
 
-- 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?
+#### Option B: Official Installer
 
-- Clone this Project and Navigate to the folder.
+Download and run the official installer for your operating system from the PostgreSQL website.
+👉 [https://www.postgresql.org/download/](https://www.postgresql.org/download/)
 
-``` bash
-git clone https://github.com/fossology/LicenseDb.git
-cd LicenseDb
-```
-
-- 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.
-
-```bash
-cp external_ref_fields.example.yaml external_ref_fields.yaml
-vim external_ref_fields.yaml
-```
+### 3. Install golang-migrate CLI
 
-- Generate Go struct for the extra fields listed in the external_ref_fields.yaml.
-
-```bash
-go generate ./...
-```
-
-- Build the project using following command.
-
-```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
-```
+#### For Linux & macOS
 
-- Run the migration files.
 ```bash
-migrate -path pkg/db/migrations -database "postgres://fossy:fossy@localhost:5432/licensedb?sslmode=disable" up
+curl -L https://github.com/golang-migrate/migrate/releases/latest/download/migrate.linux-amd64.tar.gz | tar xvz
+sudo mv migrate /usr/local/bin/
 ```
 
-- Run the executable.
+For other platforms and installation methods, check the official docs:
+👉 [https://github.com/golang-migrate/migrate](https://github.com/golang-migrate/migrate)
 
-```bash
-./laas
-```
+## How to run this project?
 
-- You can directly run it by the following command.
+👉 Please follow the [Setup Guide](./SETUP.md) for step-by-step instructions on how to run the project.
 
-```bash
-go run ./cmd/laas
-```
+## Generating Swagger Documentation
 
-### Create first user
-Connect to the database using `psql` with the following command.
-```bash
-psql -h localhost -p 5432 -U fossy -d licensedb
-```
+- Install [swag](https://github.com/swaggo/swag) using the following command.
 
-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>');
-```
-
-### 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.
+
+- 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.
+
+- 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
     ```
 
 ### Testing (local)
+
 The PostgreSQL user `fossy` must have the `CREATEDB` privilege in order to:
 
 - Programmatically create and drop a test database.
@@ -172,7 +132,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
-```
+```

SETUP.md

@@ -0,0 +1,137 @@
+<!-- SPDX-FileCopyrightText: 2025 Dearsh Oberoi <[email protected]>
+
+     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
+
+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).

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() {

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