Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
deo002 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 31 additions & 161 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,13 @@ and changes.

- **license_dbs** table has list of licenses and all the data related to the licenses.
- **obligations** table has the list of obligations that are related to the licenses.
- **obligation_classifications** table has the list of classifications that are related to the obligations.
- **obligation_types** table has the list of types that are related to the obligations.
- **obligation_maps** table that maps obligations to their respective licenses.
- **users** table has the user that are associated with the licenses.
- **audits** table has the data of audits that are done in obligations or licenses
- **change_logs** table has all the change history of a particular audit.
- **oidc_clients** table has all the oidc clients used for communication with fossology.

![ER Diagram](./docs/assets/licensedb_erd.png)

Expand Down Expand Up @@ -57,192 +60,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/
```

## How to run this project?

- Clone this Project and Navigate to the folder.

``` bash
git clone https://github.com/fossology/LicenseDb.git
cd LicenseDb
sudo apt update
sudo apt install postgresql
```

- 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
```
#### Option B: Official Installer

- Generate Go struct for the extra fields listed in the external_ref_fields.yaml.
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
go generate ./...
```
### 3. Install golang-migrate CLI
Copy link
Copy Markdown
Member

@avinal avinal Sep 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add the command/script or refer to the repository.

Copy link
Copy Markdown
Member

@avinal avinal Sep 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The instructions are under a wrong header; please fix.


- 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
```

### 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>');
```
## LicenseDB with Docker
<!-- TODO: Update `<org>` and `<project>` in the link below to actual values. -->

LicenseDB is available as a prebuilt Docker image on [GitHub Container Registry (GHCR)](https://ghcr.io/fossology/licensedb).
You can run it either using a simple `docker run` command or with the included `docker-compose.yml` file for a full setup with PostgreSQL.

---

### Option 1: Run with Docker directly

```bash
# Pull the latest stable release
docker pull ghcr.io/fossology/licensedb:latest

# Run LicenseDB (requires a PostgreSQL instance)
docker run \
--name licensedb \
-p 8080:8080 \
-e DB_HOST=<your-postgres-host> \
-e DB_PORT=5432 \
-e DB_USER=fossy \
-e DB_PASSWORD=fossy \
-e DB_NAME=licensedb \
ghcr.io/fossology/licensedb:latest
curl -L https://github.com/golang-migrate/migrate/releases/latest/download/migrate.linux-amd64.tar.gz | tar xvz
sudo mv migrate /usr/local/bin/
```

> ⚠️ This method requires you to have PostgreSQL running separately.
> If you’d like an **all-in-one setup** with PostgreSQL included, use the Docker Compose option below.
For other platforms and installation methods, check the official docs:
👉 [https://github.com/golang-migrate/migrate](https://github.com/golang-migrate/migrate)

---
### 4. Install swagger document generator

### Option 2: Run with Docker Compose (recommended)

A `docker-compose.yml` is included in this repository to make it easy to spin up LicenseDB along with PostgreSQL.
You'll need ```swag``` installed to build swagger docs.

```bash
# Build and start the containers
docker compose up -d
go install github.com/swaggo/swag/cmd/swag@latest
```

This will start two services:
- **licensedb** → The LicenseDB API (exposed at `http://localhost:8080`)
- **postgres** → PostgreSQL 16 instance with preconfigured credentials

---

## ⚙️ Environment Variables

You can customize LicenseDB behavior via environment variables in the `docker-compose.yml`.

| Variable | Default Value | Description |
|-----------------------------------|-------------------------|------------------------------------------------|
| `DB_HOST` | `postgres` | Hostname of the PostgreSQL database |
| `DB_PORT` | `5432` | PostgreSQL port |
| `DB_USER` | `fossy` | Database username |
| `DB_PASSWORD` | `fossy` | Database password |
| `DB_NAME` | `licensedb` | Database name |
| `GIN_MODE` | `debug` | Gin mode (`debug`, `release`) |
| `DEFAULT_ISSUER` | `http://localhost:8080` | Default issuer for authentication tokens |
| `SIMILARITY_THRESHOLD` | `0.9` | Similarity threshold for license matching |
| `PORT` | `8080` | Port where LicenseDB runs inside the container |
| `TOKEN_HOUR_LIFESPAN` | `24` | Token expiration time in hours |
| `READ_API_AUTHENTICATION_ENABLED` | `false` | Enable/disable authentication for read APIs |

---

## 🔍 Verify the Setup

Once containers are running, you can check:

```bash
# List running containers
docker ps

# View logs for LicenseDB
docker logs -f licensedb
```
## How to run this project?

Backend should be available at:
👉 [http://localhost:8080](http://localhost:8080)


### 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.
Expand All @@ -253,7 +121,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
```
Loading
Loading