https://github.com/rapter1990/footballteamapi

Case Study - Football Team Api with Hexagonal Architecture (Java 21, Spring Boot, Postgres, JUnit, Spring Security, JWT, Docker, Kubernetes, Prometheus, Grafana, Loki, Sonarqube, Github Actions (CI/CD), TestContainer)
https://github.com/rapter1990/footballteamapi

docker docker-compose github-actions grafana hexagonal-architecture java java21 junit kubernetes loki postgres prometheus sonarqube spring-security sprng-boot swagger testcontainers

Last synced: 2 days ago
JSON representation

Host: GitHub
URL: https://github.com/rapter1990/footballteamapi
Owner: Rapter1990
Created: 2025-03-10T05:48:21.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2025-07-19T17:21:17.000Z (12 months ago)
Last Synced: 2025-10-29T19:47:41.234Z (8 months ago)
Topics: docker, docker-compose, github-actions, grafana, hexagonal-architecture, java, java21, junit, kubernetes, loki, postgres, prometheus, sonarqube, spring-security, sprng-boot, swagger, testcontainers
Language: Java
Homepage:
Size: 6.85 MB
Stars: 24
Watchers: 1
Forks: 2
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

# Case Study - Football Team Api (Hexagonal Architecture)

Main Information

### 📖 Information

Football Team Management Service:
- Implement a Spring Boot-based service through hexagonal architecture for managing football teams and their associated players, encompassing functionalities for team listing, player retrieval by team ID, and support for team and player updates or deletions
- Functional Features:
  - List all football teams.
  - List players of a selected football team using the team’s ID.
  - Delete or update a football team using its ID.
  - Delete players from a football team or add a new player to the team.
- Business Rules:
  - A football team can have a maximum of 18 players.
  - Only up to 6 players on a team can be foreigners.
  - A maximum of 2 goalkeepers can be defined per team.

### Explore Rest APIs

Endpoints Summary

Method
Url
Description
Request Body
Path Variable
Response

POST
/api/v1/authentication/user/register
Register for Admin or User
RegisterRequest

CustomResponse<Void>

POST
/api/v1/authentication/user/login
Login for Admin or User
LoginRequest

CustomResponse<TokenResponse>

POST
/api/v1/authentication/user/refresh-token
Refresh Token for Admin or User
TokenRefreshRequest

CustomResponse<TokenResponse>

POST
/api/v1/authentication/user/logout
Logout for Admin or User
TokenInvalidateRequest

CustomResponse<Void>

POST
/api/v1/football-teams
Create a new football team
CreateFootballTeamRequest
-
CustomResponse<FootballTeamResponse>

PUT
/api/v1/football-teams/{teamId}
Update an existing football team's name
UpdateFootballTeamRequest
teamId (UUID)
CustomResponse<FootballTeamResponse>

GET
/api/v1/football-teams/{teamId}
Retrieve a football team's details by ID
-
teamId (UUID)
CustomResponse<FootballTeamResponse>

DELETE
/api/v1/football-teams/{teamId}
Delete a football team by ID
-
teamId (UUID)
CustomResponse<Void>

POST
/api/v1/football-teams/teamsList
Retrieve a paginated list of football teams
FootballTeamPagingRequest
-
CustomResponse<CustomPagingResponse<FootballTeamResponse>>

POST
/api/v1/football-teams/{teamId}/players
Add a new player to a team
AddPlayerRequest
teamId (UUID)
CustomResponse<PlayerResponse>

PUT
/api/v1/football-teams/{teamId}/players/{playerId}
Update an existing player on a team
UpdatePlayerRequest
teamId (UUID), playerId (UUID)
CustomResponse<PlayerResponse>

DELETE
/api/v1/football-teams/{teamId}/players/{playerId}
Delete a player from a team
-
teamId (UUID), playerId (UUID)
CustomResponse<Void>

GET
/api/v1/football-teams/{teamId}/players
Retrieve a paginated list of players for a team
PlayerPagingRequest
teamId (UUID)
CustomResponse<CustomPagingResponse<PlayerResponse>>

### Technologies

---
- Java 21
- Spring Boot 3.0
- Restful API
- Open Api (Swagger)
- Maven
- Junit5
- Mockito
- Integration Tests
- TestContainers
- Docker
- Docker Compose
- CI/CD (Github Actions)
- Postman
- Prometheus
- Grafana
- Kubernetes
- JaCoCo (Test Report)
- Sonarqube
- Loki (Log Aggregation System)

### Postman

```
Import postman collection under postman_collection folder
```

### Prerequisites

#### Define Variable in .env file

```
FOOTBALL_TEAM_DB_IP=localhost
FOOTBALL_TEAM_DB_PORT=5432
POSTGRES_USER={POSTGRES_USER}
POSTGRES_PASSWORD={POSTGRES_PASSWORD}
```

### Open Api (Swagger)

```
http://localhost:3112/swagger-ui/index.html
```

---

### JaCoCo (Test Report)

After the command named `mvn clean install` completes, the JaCoCo report will be available at:
```
target/site/jacoco/index.html
```
Navigate to the `target/site/jacoco/` directory.

Open the `index.html` file in your browser to view the detailed coverage report.

---

### Maven, Docker and Kubernetes Running Process

### Maven Run
To build and run the application with `Maven`, please follow the directions shown below;

```sh
$ cd footballteamapi
$ mvn clean install
$ mvn spring-boot:run
```

---

### Docker Run
The application can be built and run by the `Docker` engine. The `Dockerfile` has multistage build, so you do not need to build and run separately.

Please follow directions shown below in order to build and run the application with Docker Compose file;

```sh
$ cd footballteamapi
$ docker-compose up -d
```

If you change anything in the project and run it on Docker, you can also use this command shown below

```sh
$ cd footballteamapi
$ docker-compose up --build
```

To monitor the application, you can use the following tools:

- **Prometheus**:
Open in your browser at [http://localhost:9090](http://localhost:9090)
Prometheus collects and stores application metrics.

- **Grafana**:
Open in your browser at [http://localhost:3000](http://localhost:3000)
Grafana provides a dashboard for visualizing the metrics.
**Default credentials**:
- Username: `admin`
- Password: `admin`

- Define prometheus data source url, use this link shown below

```
http://prometheus:9090
```

- Define loki data source url, use this link shown below

```
http://loki:3100
```

---

### Kubernetes Run
To build and run the application with `Maven`, please follow the directions shown below;

- Start Minikube

```sh
$ minikube start
```

- Open Minikube Dashboard

```sh
$ minikube dashboard
```

- To deploy the application on Kubernetes, apply the Kubernetes configuration file underneath k8s folder

```sh
$ kubectl apply -f k8s
```

- To open Prometheus, click tunnel url link provided by the command shown below to reach out Prometheus

```sh
minikube service prometheus-service
```

- To open Grafana, click tunnel url link provided by the command shown below to reach out Prometheus

```sh
minikube service grafana-service
```

- Define prometheus data source url, use this link shown below

```
http://prometheus-service.default.svc.cluster.local:9090
```

- Define loki data source url, use this link shown below

```
http://loki-service.default.svc.cluster.local:3100
```

---
### Docker Image Location

```
https://hub.docker.com/repository/docker/noyandocker/footballteamapi/general
```

### Define Loki through Grafana

- Define Loki Dashboard
- Define `query` after selecting data source as `Loki`
- Define `Label Filter` as `app` and its value `footballteamapi`
- Run the `query`
- Show the result in the Dashboard

### Sonarqube

- Go to `localhost:9000` for Docker and Go there through `minikube service sonarqube` for Kubernetes
- Enter username and password as `admin`
- Change password
- Click `Create Local Project`
- Choose the baseline for this code for the project as `Use the global setting`
- Click `Locally` in Analyze Method
- Define Token
- Click `Continue`
- Copy `sonar.host.url` and `sonar.token` (`sonar.login`) in the `properties` part in `pom.xml`
- Run `mvn sonar:sonar` to show code analysis

### Screenshots

Click here to show the screenshots of project

Figure 1