Skip to content

Improving readme structure #477

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

Merged
Ziadsharkos merged 3 commits into from
Apr 11, 2025
Merged

Improving readme structure #477

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a2f67d1
GH-0: [docs] Update README.md to enhance project description and setu…
Ziadsharkos Apr 10, 2025
9e2d4b2
GH-0: [docs] Update frontend setup link in README.md to point to the …
Ziadsharkos Apr 11, 2025
b844137
GH-0: [docs] Add link to Release 2 video presentation in README.md
Ziadsharkos Apr 11, 2025
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
139 changes: 95 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,34 @@
<h1>Release Demos</h1>
# 🏀 Sporta – Sports Event Organizer

Sporta connects users who are passionate about playing sports, enabling them to create and join public events for games like soccer, basketball, tennis, and more. Users can register, create profiles with their skill levels, and browse events based on location and availability. The app allows for real-time updates on event participation, skill-based filtering, and in-app messaging to coordinate with others. Sporta enables users to post photos and rate fellow players to foster engagement.


---

## 📑 Table of Contents

[Release 2 Video Presentation](https://drive.google.com/file/d/1nWpURlvlSsaBed25e8k0oZryIKKR7ceT/view?usp=drive_link)
[Release 1 Video Presentation](https://drive.google.com/file/d/1eRpaNODa4Dt50EICdGhrMVTBgtZf7av6/view?usp=drive_link)

1. [🎥 Release Demos](#-release-demos)
2. [📂 Important Files](#-important-files)
3. [🧪 Important Tests](#-important-tests)
4. [👥 Team Members](#-team-members)
5. [⚙️ Project Setup & Build Guide](#️-project-setup--build-guide)
- [Prerequisites](#prerequisites)
- [Clone the Repository](#1-clone-the-repository)
- [Build the Application with Gradle](#2-build-the-application-with-gradle)
- [Docker Containerization](#3-docker-containerization)
- [Docker Compose Setup](#4-docker-compose-setup-for-microservices)
- [Running Multiple Microservices](#5-running-multiple-microservices)

---

## 🎥 Release Demos

- [Release 2 Video Presentation](https://drive.google.com/file/d/1nWpURlvlSsaBed25e8k0oZryIKKR7ceT/view?usp=drive_link)
- [Release 1 Video Presentation](https://drive.google.com/file/d/1eRpaNODa4Dt50EICdGhrMVTBgtZf7av6/view?usp=drive_link)

---
<p align="center">
<a href="https://youtu.be/4d0tcheM6pI">
<img src="https://github.com/user-attachments/assets/049ad161-e044-4a47-8b56-973ef32456aa" width="300" />
Expand Down Expand Up @@ -30,92 +56,113 @@
| [PostServiceImplTest.java](https://github.com/SOEN490-SportsApp/SportsApp/blob/main/Microservices/event-service/src/test/java/app/sportahub/eventservice/service/social/PostServiceImplTest.java) | Tests all logic related to the post and comment handling of the app |
| [MessagingServiceTest.java](https://github.com/SOEN490-SportsApp/SportsApp/blob/main/Microservices/messaging-service/src/test/java/app/sportahub/messaging_service/service/MessagingServiceTest.java) | Validates MessagingService operations, mainly on making sure private and group messaging is possible. |
| [EventSearchTest.java](https://github.com/SOEN490-SportsApp/SportsApp/blob/main/Microservices/user-service/src/test/java/app/sportahub/userservice/repository/user/SearchingUserRepositoryImplTest.java](https://github.com/SOEN490-SportsApp/SportsApp/blob/main/Microservices/event-service/src/test/java/app/sportahub/eventservice/service/event/EventSearchTest.java)) | Validates event search and pagination by ensuring accurate and reliable query functionality for the event service |
---

## 👥 Team Members

<h1 align="center">Sporta</h1>

### Project Summary:
Sporta connects users who are passionate about playing sports, enabling them to create and join public events for games like soccer, basketball, tennis, and more. Users can register, create profiles with their skill levels, and browse events based on location and availability. The app allows for real-time updates on event participation, skill-based filtering, and in-app messaging to coordinate with others. Sporta enables users to post photos and rate fellow players to foster engagement.
| Name | Student ID | GitHub | Email |
|------|------------|--------|-------|
| Daniel Duguay | 40202775 | [DanDuguay](https://github.com/DanDuguay) | Duguay9@gmail.com |
| Nicolas Chelico | 40156158 | [NicolasChelico](https://github.com/NicolasChelico) | nicolas.chelico@outlook.com |
| Wadeh Hamati | 40216893 | [wade3hamati](https://github.com/wade3hamati) | wade3_hamati@outlook.com |
| Walid Achlaf | 40210355 | [walidoow](https://github.com/walidoow) | walidachlaf@gmail.com |
| Monika Moanes | 40188452 | [MonikaaMoanes](https://github.com/MonikaaMoanes) | monicanasser6@gmail.com |
| Khalil Garaali | 40226310 | [KhalilGarali](https://github.com/KhalilGarali) | garalikhalil@gmail.com |
| Youssef Alsheghri | 40108014 | [yousfino](https://github.com/yousfino) | youssef.alsheghri@gmail.com |
| Ziad Elsharkawi | 40213438 | [Ziadsharkos](https://github.com/Ziadsharkos) | ziadelsharkawi@outlook.com |
| Patrick MacEachen | 40209790 | [patrickmac3](https://github.com/patrickmac3) | patrickmaceachen9@gmail.com |
| Joud Babik | 40031039 | [JRB958](https://github.com/JRB958) | j_babik@live.concordia.ca |
| Jean-Nicolas Sabatini-Ouellet | 40207926 | [wolfie7679](https://github.com/wolfie7679) | je_sabat@live.concordia.ca |

### Team Members:
---

| Name | Student ID | GitHub ID | Email Address |
|-------------------------------|------------|----------------|-----------------------------|
| Daniel Duguay | 40202775 | DanDuguay | Duguay9@gmail.com |
| Nicolas Chelico | 40156158 | NicolasChelico | nicolas.chelico@outlook.com |
| Wadeh Hamati | 40216893 | wade3hamati | wade3_hamati@outlook.com |
| Walid Achlaf | 40210355 | walidoow | walidachlaf@gmail.com |
| Monika Moanes | 40188452 | MonikaaMoanes | monicanasser6@gmail.com |
| Khalil Garaali | 40226310 | KhalilGarali | garalikhalil@gmail.com |
| Youssef Alsheghri | 40108014 | yousfino | youssef.alsheghri@gmail.com |
| Ziad Elsharkawi | 40213438 | Ziadsharkos | ziadelsharkawi@outlook.com |
| Patrick MacEachen | 40209790 | patrickmac3 | patrickmaceachen9@gmail.com |
| Joud Babik | 40031039 | JRB958 | j_babik@live.concordia.ca |
| Jean-Nicolas Sabatini-Ouellet | 40207926 | wolfie7679 | je_sabat@live.concordia.ca |
## ⚙️ Project Setup & Build Guide

# Project Setup and Build Guide
### Prerequisites

This guide provides all the steps needed to set up, build, and run this project, including Docker containerization and Gradle configuration. It is important to note that this is the main setup for the backend. In order to setup the frontend, please consult the following [README.md](https://github.com/SOEN490-SportsApp/SportsApp/tree/chore/issue-137/read-me-setup-for-project/ClientApp#readme
) to understand more about the Expo app.
Ensure the following tools are installed:

## Prerequisites
- Git
- Docker
- Java JDK 21
- Gradle (or use `./gradlew` wrapper)
- **Note that this is the main setup for the backend. In order to setup the frontend, please consult the following [README.md](https://github.com/SOEN490-SportsApp/SportsApp/tree/main/ClientApp#readme) to understand more about the Expo app.**

Before starting, ensure you have the following installed:
- **Git**: for cloning the repository.
- **Docker**: for containerizing the application.
- **Java Development Kit (JDK)**: version 21.
- **Gradle**: or use the Gradle wrapper (`./gradlew`) included in the project.
---

## Getting Started

### 1. Clone the Repository

First, clone the repository to your local machine:
```bash
git clone <repository-url>
cd <repository-directory>
```

---

### 2. Build the Application with Gradle
Use Gradle to build the project and run tests.

### Build the project:
```bash
Use the Gradle wrapper to build the project:

```bash
./gradlew build
```
This command will compile the project, package it, and run unit tests.

This command compiles, packages, and runs all unit tests.

---

### 3. Docker Containerization
This project uses a Dockerfile to package the application for containerized deployment.

#### Dockerfile Overview
The Dockerfile sets up the container with an OpenJDK base image, configures environment variables, copies the JAR file, and exposes port 8080.
#### 🔹 Build the JAR

#### Steps to Build and Run the Docker Image
##### Build the JAR file using Gradle:
```bash
./gradlew build
```
The generated JAR file will be located in `build/libs` as `project-name-0.0.1-SNAPSHOT.jar`.

##### Build the Docker Image:
The generated JAR file will be located in `build/libs/` as `project-name-0.0.1-SNAPSHOT.jar`.

#### 🔹 Build Docker Image

```bash
docker build --build-arg JAR_FILE=build/libs/project-name-0.0.1-SNAPSHOT.jar -t project-image .
```
##### Run the Docker Container:
To run the container, map port 8080 and use an `.env` file to provide the environment variables:

#### 🔹 Run Docker Container

```bash
docker run -p 8080:8080 --env-file .env project-image
```
Replace `.env` with the path to your environment variable file or set the variables directly in the command.

> Replace `.env` with the path to your environment variable file, or set the variables directly in the command line.

#### Gradle Build and Dependency Configuration
The `build.gradle` file specifies dependencies, configurations, and build tasks. Key sections include:

---

### 4. Docker Compose Setup for Microservices
This project relies on several microservices, each with its own Docker setup. All microservices depend on the services defined in a shared `docker-compose.yml` file, which includes services such as MongoDB, MySQL (for Keycloak), and Keycloak itself. These services must be running for the microservices to function properly.
The `docker-compose.yml` file configures and manages the required services. You will need to ensure that the services are up and running before starting any microservice.

We use a **monorepo architecture** with services located in `Microservices/<service-name>`.

Here are the required backend services:

| Microservice | Docker Package |
|------------------------|------------------------------------|
| Event Service | `sportsapp-event-service` |
| User Service | `sportsapp-user-service` |
| Messaging Service | `sportsapp-messaging-service` |
| Storage Service | `sportsapp-storage-service` |
| API Gateway | `sportsapp-gateway` |
| Kafka Event Model | `app.sportahub.kafka-events` |
| Orchestration Service | `sportsapp-orchestration-service` |
| Email Service | `sportsapp-email-service` |
| Notification Service | `sportsapp-notification-service` |

---
#### How to Set it Up:
1. Navigate to the directory of the microservice you want to run.

Expand All @@ -128,6 +175,8 @@ docker-compose up --build
```
Once the services are up and running, the microservice will be able to interact with MongoDB, Keycloak, and other dependencies.

---

### 5. Running Multiple Microservices
The project consists of several microservices, each located in its respective folder under `Microservices/<service-name>`. The README assumes the backend is located at the root of the project directory, but since we have multiple microservices, each microservice has its own folder and configuration.

Expand All @@ -146,3 +195,5 @@ This ensures that each microservice runs with its own set of services (like data

#### Running the Application
After building the project and Docker image, you can access the application at `http://localhost:8080`

---