Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/francislagares/github-org-finder
A Clean Architecture Fullstack MERN application where user enters a github ORG name in text input and retrieve a list or repositories belonging to this ORG.
https://github.com/francislagares/github-org-finder
clean-architecture express mern mern-stack mongodb mongoose next15 nodejs react-query react-table react19 shadcn-ui
Last synced: about 21 hours ago
JSON representation
A Clean Architecture Fullstack MERN application where user enters a github ORG name in text input and retrieve a list or repositories belonging to this ORG.
- Host: GitHub
- URL: https://github.com/francislagares/github-org-finder
- Owner: francislagares
- License: mit
- Created: 2024-07-03T17:00:34.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-01-25T12:22:28.000Z (5 days ago)
- Last Synced: 2025-01-25T13:18:51.739Z (5 days ago)
- Topics: clean-architecture, express, mern, mern-stack, mongodb, mongoose, next15, nodejs, react-query, react-table, react19, shadcn-ui
- Language: TypeScript
- Homepage:
- Size: 1.37 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Node.js API - GitHub Repositories Explorer
This project is a Node.js-based API for exploring GitHub organization repositories. The API supports both local and Dockerized environments. Follow the instructions below to set up and run the project.
---
## **Prerequisites**
Before you begin, make sure you have the following installed:
1. **Node.js** (recommended version: 23 or later).
2. **pnpm** (preferred package manager for this project).
3. **Docker** and **Docker Compose**.
4. A GitHub personal access token for API authentication.
---
# Setup Instructions
## 1. Running Locally
To run the API locally:
1. Clone the repository and install dependencies.
```sh
# clone repository
git clone [email protected]:francislagares/github-org-finder.git
# cd into
cd github-org-finder
# install required dependencies
pnpm install
```
## **Environment Variables**
The API requires the following environment variables. Configure these in a `.env` or `.env.development.local` file in the api directory.
```env
GITHUB_SECRET=your_github_secret
REDIS_HOST=localhost
DATABASE_URL=mongodb://localhost:27017/repos_db
CORS_ORIGIN=http://localhost:5173
```
## 2. Running with PM2
To run the API using pm2:
1. Create a `.env.development.local` file in the api directory with the following Docker environment variables.
```env
GITHUB_SECRET=your_github_secret
REDIS_HOST=localhost
DATABASE_URL=mongodb://localhost:27017/repos_db
CORS_ORIGIN=http://localhost:5173
```
### Local environment
1. Run the following command:
```sh
pnpm pm2:dev
```
### Production environment
1. Run the following command:
```sh
pnpm build:api
```
2. Start the PM2 Daemon:
```sh
pnpm pm2:prod
```
### Side Notes
You need to stop and clean the instance of pm2 before switching environment. Or just change ports in ecosystem.config.js file.
### Stop the PM2 Daemon
```sh
pnpm pm2:stop
```
### Clean PM2 instance
```sh
pnpm pm2:clean
```
## 3. Running with Docker
To run the API using Docker:
1. Ensure Docker and Docker Compose are installed and running on your system.
2. Create a `.env` or `.env.development.local` file in the api directory with the following Docker environment variables.
```env
GITHUB_SECRET=your_github_secret
REDIS_HOST=redis
DATABASE_URL=mongodb://mongodb:27017/repos_db
CORS_ORIGIN=http://localhost:5173
```
3. Build and start the Docker containers:
```sh
docker-compose up --build
```
4. Verify the API is running by accessing http://localhost:4000/api/v1/health
## API Endpoints
### **Health Check**
- **URL:** `/health`
- **Method:** `GET`
- **Description:** Checks if the API is running.
### **Fetch Repositories**
- **URL:** `/api/v1/orgs/:orgName/repos`
- **Method:** `GET`
- **Query Parameters:**
- `page` (optional): Page number for pagination (default is `1`).
- `limit` (optional): Limit number for repositories (default is `10`).
- **Description:** Retrieves repositories for a given GitHub organization.
### **Save Repositories to Database**
- **URL:** `/api/v1/repos/save`
- **Method:** `POST`
- **Description:** Saves repositories to the MongoDB database.
### **Delete Repository**
- **URL:** `/api/v1/repos/:id`
- **Method:** `DELETE`
- **Description:** Deletes a repository from the MongoDB database by its ID.
## Query the API in Swagger
This project provides an API that you can interact with using Swagger, an interactive API documentation tool. To query the API correctly, you need to configure your environment with the GITHUB_SECRET token, which is required to access certain routes of the API.
### 2. Access Swagger
Once the `GITHUB_SECRET` variable is configured, you can access Swagger to explore and query the API.
- **Swagger URL**: [http://localhost:4000/api-docs](http://localhost:4000/api-docs) _(adjust the port if needed)_.
### 3. Authenticate with GitHub Secret
When accessing the API documentation via Swagger, you need to authenticate using the `GITHUB_SECRET` token. This is done via an HTTP header for routes that require authentication.
#### Add the token in Swagger
1. Open the Swagger page in your browser.
2. At the top, you'll find an "Authorize" button.
3. Click on "Authorize".
4. In the authentication field, enter your actual GITHUB_SECRET token for the `Authorization` header like so:
```
ghp_12345abcdef6789test
```
(Replace ghp_12345abcdef6789 with your actual GITHUB_SECRET token).
5. Click "Authorize" to confirm.
Now you will be able to make authenticated requests to the API routes that require the GITHUB_SECRET token.
## Current Project Status
While the API is already functional the client side is still in development and additional features are being developed and refined.
Please check the client folder for the latest updates.
## Author
- [Francis Lagares](https://www.linkedin.com/in/francislagares)
- [Portfolio](https://francislagares.vercel.app/)
## All contributions are welcome
Contributions are more than welcomed.
Feel free to open issues for asking questions, suggesting features or other things!