DOI: 10.5281/zenodo.18344847
title: OSSBridge

description: 1. OSSBridge - Quick Start Guide


## Prerequisites


1. **Docker Desktop** installed and running

- Download: https://www.docker.com/products/docker-desktop

- Supports: Windows 10/11, macOS 10.15+, Linux

- Free for educational and research use


2. **Dataset** downloaded from Zenodo

- Download the Dataset.zip from Zenodo

- Extract it to a location on your computer


---


## Setup


### Step 1: Extract OSSBridge Package


Extract the `OSSBridge-Docker.zip` file to a folder on your computer.


### Step 2: Configure Dataset Path


1. Open the `.env` file in a text editor:


**Mac/Linux:**

```bash

nano .env

```


**Windows:**

```

notepad .env

```


2. Update the `DATASET_PATH` line with the location where you extracted the dataset:


**Mac Example:**

```bash

DATASET_PATH=/Users/yourname/Downloads/Dataset

```


**Windows Example:**

```

DATASET_PATH=C:/Users/yourname/Downloads/Dataset

```


**Linux Example:**

```bash

DATASET_PATH=/home/yourname/Downloads/Dataset

```


**Or use relative path** (if Dataset folder is next to OSSBridge-Docker):

```bash

DATASET_PATH=../Dataset

```


3. Save the file and close the editor


### Step 3: Start OSSBridge


**Mac/Linux:**

```bash

cd OSSBridge-Docker

./start.sh

```


**Windows:**

```

cd OSSBridge-Docker

start.bat

```


**Or manually:**

```bash

cd OSSBridge-Docker

docker-compose up --build

```


### Step 4: Access the Application


Once you see "Server running on port 5050" in the terminal:


1. Open your web browser

2. Go to: **http://localhost:3000**

3. The OSSBridge interface should load


---


## Using OSSBridge


1. **Search for a library** (e.g., type "jackson")

2. **Select a library** from the dropdown (e.g., "jackson-databind")

3. **Select a version** (e.g., "2.17.2")

4. **Click "Analyze Usage"** to view analytics

5. **Explore the visualizations:**

- Usage statistics

- Dependent analysis

- Maintainer summary

- API surface usage

- Test coverage


---


## Stopping the Application


**In the terminal where Docker is running:**

- Press `Ctrl+C`


**Then clean up:**

```bash

docker-compose down

```


---


## Troubleshooting


### "Docker is not running."

- **Solution:** Start the Docker Desktop application

- Wait for Docker to fully start (whale icon in system tray)


### "Cannot find dataset" or "ENOENT: no such file or directory."

- **Problem:** Dataset path in `.env` is incorrect

- **Solution:**

1. Check the path inthe  `.env` file

2. Make sure you extracted the Dataset.zip

3. Use an absolute path (full path from root)

4. On Windows, use forward slashes: `C:/Users/...` not `C:\Users\...`


### "Port 3000 already in use."

- **Problem:** Another application is using port 3000

- **Solution:**

- Stop other applications using port 3000

- Or edit `docker-compose.yml` and change `"3000:80"` to `"8080:80"`


### "Port 5050 already in use."

- **Problem:** Another application is using port 5050

- **Solution:**

- Stop other applications using port 5050

- Or edit `docker-compose.yml` and change the backend port


### Build fails, or images won't start

- **Solution:**

```bash

# Clean up and rebuild

docker-compose down --rmi all

docker-compose up --build

```


---


## System Requirements


- **Operating System:** Windows 10/11, macOS 10.15+, or Linux

- **RAM:** 4GB minimum, 8GB recommended

- **Disk Space:**

- ~2GB for Docker images

- Dataset size (varies)

- ~1GB for temporary build files

- **Docker Desktop:** Latest version


---


## Additional Commands

```bash

# Start in detached mode (background)

docker-compose up -d


# View logs

docker-compose logs -f


# Stop containers

docker-compose down


# Rebuild from scratch

docker-compose up --build


# Remove everything (containers, images, volumes)

docker-compose down --rmi all --volumes

```


---