Merge branch 'doc' of https://github.com/FPirazz/Traffic-Management i…

…nto doc

README.md

@@ -1,2 +1,5 @@
 # Traffic-Management
 Project for both SPA and SPE
+
+
+Link to the [documentation (DOC).](https://fpirazz.github.io/Traffic-Management/)

docs/SPE/CD.md

@@ -0,0 +1,55 @@
+# Continuous Deployment with AWS and Kubernetes
+
+## Overview
+
+Continuous Deployment (CD) is a critical aspect of modern software development, automating the release and deployment processes to deliver new features and improvements seamlessly. In this project, CD is facilitated through the integration of Amazon Web Services (AWS) and Kubernetes.
+
+## Amazon Web Services (AWS)
+
+Amazon Web Services (AWS) is a comprehensive cloud computing platform offered by Amazon. It provides a wide range of services, including computing power, storage, databases, machine learning, analytics, and more. AWS enables developers to build scalable and flexible applications without the need for extensive infrastructure management.
+
+## Continuous Deployment Workflow
+
+The CD workflow is orchestrated using Kubernetes, a container orchestration platform, Docker, since the frontend will be hosted on a container, and also Kubernetes is supported my the Minikube technology which requires the instantiation of a minikube container, along with AWS services. Here's an overview of the process:
+
+1. **Minikube Setup**: Before starting the deployment, ensure Docker Desktop, or the Docker daemon, is running, and Minikube is installed. Execute `minikube start` to initiate the Minikube cluster.
+
+2. **Kubernetes Deployment**: Navigate to the directory containing the files regaring CD and execute the following commands to deploy the Kubernetes services:
+
+    ```bash
+    kubectl apply -f intersection-agents-deployment.yaml,intersection-agents-service.yaml,spring-db-app-deployment.yaml,spring-db-app-service.yaml,user-db-deployment.yaml,user-db-service.yaml
+    ```
+
+3. **Docker Compose for Vue**: Build and run the Vue application container:
+
+    ```bash
+    docker compose build --no-cache
+    docker run -it --rm -d -p 8080:80 --name vue-app traffic-management-vue-app:latest
+    ```
+
+4. **Minikube Tunneling**: Start Minikube tunneling to expose services locally:
+
+    ```bash
+    minikube tunnel
+    ```
+
+5. **Check Service IPs**: In a separate terminal, verify that the external IPs of the services are set to their assigned Cluster-IPs:
+
+    ```bash
+    kubectl get svc
+    ```
+
+6. **Accessing the Application**: Visit the hostname where the application is being hosted, on the port 8008 in your browser, to access the application. The Vue app communicates with Kubernetes clusters (Spring, User-DB, Intersection Agents) through AWS services.
+
+## AWS Integration
+
+AWS plays a crucial role in this CD workflow by hosting the Vue application, a Nginx reverse proxy and the Kubernets services.
+
+The Vue containerized Vue application itself also contains an internal Nginx reverse-proxy, used to redirect any Axios requests (RPC requests) made towards the services properly, in our case the requests are re-directed to another Nginx proxy instantiated in the EC2 instance itself.
+The second Nginx proxy routes HTTP calls from the browser to the appropriate Kubernetes clusters, mainly by letting the frontend know where each REST endpoint is.
+And finally each Kubernetes service exposes an external IP, on a port, to let request come in and be processed.
+
+This CD approach ensures that changes are seamlessly deployed to the Kubernetes clusters, providing a smooth and efficient development and deployment pipeline, which is also made secure by the fact that the only port that is accessibile externally from the EC2 instance it's only the one related to the frontend, so no other request can be done on other ports. In our case, because of the fact that this is an academic project, the EC2 instance is only turned on when necessary because running any type of service on AWS costs money, so therefore we only test deployment when necessary, but in a real world scenario, the instance/s can be left running, also employing other EC2 services such as requesting a static IP for the instance.
+
+
+[Go Back.](./index.md)

docs/SPE/CI.md

@@ -0,0 +1,83 @@
+# Continuous Integration with GitHub Actions
+
+GitHub Actions provides a powerful platform for automating Continuous Integration (CI) workflows, allowing developers to streamline the build and testing processes of their projects directly within their GitHub repositories.
+
+## Build Gradle Project Workflow
+
+```yaml
+name: Build Gradle project
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+
+jobs:
+  build-gradle-project:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout project sources
+        uses: actions/checkout@v4
+      - name: Set up JDK 19
+        uses: actions/setup-java@v3
+        with:
+          java-version: '19'
+          distribution: 'temurin' # Or other distributions like 'adopt'
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v3
+      - name: Execute Gradle build
+        run: ./gradlew build
+```
+
+This GitHub Actions workflow automates the Gradle project's build process triggered by pushes to the main and develop branches. The workflow sets up the environment with JDK 19, configures Gradle, and executes the build tasks.
+It ensures a consistent and efficient CI pipeline for Gradle-based development.
+
+## Automatic Deployment to AWS.
+
+```yaml
+name: Deploy Application to AWS EC2 Instance
+on:
+  push:
+    branches:
+      - prepDeploy
+      - main
+
+jobs:
+  Deploy:
+    name: Deploy to EC2
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Build & Deploy
+        env:
+          PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
+          HOSTNAME: ${{secrets.SSH_HOST}}
+          USER_NAME: ${{secrets.USER_NAME}}
+
+        run: |
+          echo "$PRIVATE_KEY" > ./private_key && chmod 600 ./private_key
+          cat ./private_key
+          ssh -o StrictHostKeyChecking=no -i ./private_key ${USER_NAME}@${HOSTNAME} '
+          
+          
+              # Now we have got the access of EC2 and we will start the deploy .
+              kubectl delete --all svc
+              kubectl delete --all deploy
+              kubectl delete --all pods
+              sudo docker container delete vue-app
+          
+              minikube start
+              cd my-dashboard/
+          
+              sudo docker pull leomarzoli/traffic_management_system:latest
+              kubectl apply -f intersection-agents-deployment.yaml,intersection-agents-service.yaml,spring-db-app-deployment.yaml,spring-db-app-service.yaml,user-db-deployment.yaml,user-db-service.yaml
+              docker run -it --rm --add-host=host.docker.internal:host-gateway -d -p 8080:80 --name vue-app leomarzoli/traffic_management_system:latest
+          
+              minikube tunnel -c
+              '
+```
+This YAML file configures a GitHub Actions workflow for deploying an app to an AWS EC2 instance. Triggered by a push to either the'prepDeploy' or 'main' branch, establishes an SSH connection using secrets which are added to the secret repository section (in our case since the EC2 instance costs money, the secret regarding the host name, needs to be changed everytime the instance is turned off then on), and initiates deployment operations on the EC2 instance. It removes Kubernetes services and deployments and also deletes the containerized frontend via Docker of the frontend just in case any of these services were already started from a previous deployment, then it starts Minikube, applies Kubernetes services and deployments, and starts the frontend Docker container automatically by pulling it and running it, exposing port 8080, and also routing said port to port 80. The goal is to automate the application deployment process on a remote machine, streamlining the development cycle, and improving release management.
+
+[Go Back.](./index.md) [Go Next.](./containerization.md)

docs/SPE/build_automation.md

@@ -0,0 +1,98 @@
+# System Implementation
+
+After analyzing the project requirements, the application was implemented by developing three sub-applications, specifically three microservices, and using a Java-based external SQL database named H2. The sub-applications are defined as follows:
+
+1. **userContext:**
+   - A Spring Boot Java project creating REST endpoints for frontend interaction.
+   - Utilizes Spring Boot's dialects for various DB interactions.
+   - All RPCs to userContext perform queries on the H2 Database.
+
+2. **H2 Database:**
+   - Derived from an existing image of a basic H2 Database implementation.
+   - Modified for deployment with all necessary components.
+
+3. **intersectionAggregate:**
+   - A Multi-Agent System implemented through the JaCaMo library.
+   - Leverages JaCaMo-Rest for RPC endpoints to access agent system artifacts.
+   - Deployed as a microservice.
+
+4. **tcm_frontend:**
+   - A simple Vue application serving as the frontend.
+   - When deployed as a container, it includes an internal reverse proxy Nginx server.
+   - The Nginx server handles redirecting calls from the Vue app to the right endpoints and resolves CORS Policy issues.
+
+## Continuous Delivery
+
+To automate the initial execution of the system, Gradle (v8.2) was employed, and a series of "build.gradle" files were defined. These files specify how the project is compiled, manage dependencies, and configure other aspects of the build process.
+
+### Implementation Strategy:
+
+The implementation strategy employs a hierarchical structure, with each microservice having its own "build.gradle" file. These microservices are then linked via dependencies to a more generic "build.gradle" file, which defines several tasks within it.
+
+The structure ensures modularization and allows for centralized management of common build tasks. This approach enhances maintainability and streamlines the continuous delivery process.
+
+This is how appears the main and generalized "build.gradle" file.
+
+<p align="center">
+  <img src="./img/automation1.png" alt="./img/automation1.png"/>
+</p>
+
+In the "build.gradle" file, the following tasks are defined:
+
+1. **runAll:**
+   - Executes all the necessary components for the application.
+
+2. **cleanAll:**
+   - Cleans the various microservices from the files generated during the compilation phase.
+
+3. **buildAll:**
+   - Cleans the various microservices from the files generated during the compilation phase.
+
+4. **cleanAndBuildAll:**
+   - Executes all the previously described tasks.
+
+These tasks are designed to streamline the build and deployment process. Running `cleanAndBuildAll` ensures a fresh start by cleaning the microservices and then building them, providing a comprehensive approach to managing the application's lifecycle.
+
+In this next section of the page we want to highlight the best task for each each microservices that has been developed.
+
+<p align="center">
+  <img src="./img/automation2.png" alt="./img/automation2.png"/>
+</p>
+
+1. **runAgents:**
+   - Executes a JaCaMo application using the class `jacamo.infra.JaCaMoLauncher`.
+   - Before execution, it creates a log directory.
+   - Depends on the "classes" task to ensure correct compilation of source code.
+   - The argument "intersection.jcm" is passed, representing the file containing the agent environment.
+   - Configures the classpath with necessary dependencies.
+
+ The `runAgents` task, in particular, is crucial for launching JaCaMo applications (agents) with the necessary configurations.
+
+<p align="center">
+  <img src="./img/automation3.png" alt="./img/automation3.png"/>
+</p>
+
+2. **runUserApplication:**
+   - Runs a user context application using the class `com.userContext.infrastructure_layer.springBoot.UserApplication`.
+   - Configures the classpath with the necessary dependencies using the runtimeClasspath of the main source set
+
+In the `build.gradle` file of the `tcm_frontend` microservice, the following task is defined for building the Vue project:
+
+<p align="center">
+  <img src="./img/automation4.png" alt="./img/automation4.png"/>
+</p>
+
+1. **npmBuildProject:**
+   - Groups tasks necessary for building a Vue project.
+   - Installs dependencies defined in `package.json` using the "npmInstallProject" task.
+   - Cleans the project with "npmClean" by removing the "dist" and "build" directories.
+   - Runs the build script via "npmRunBuild".
+
+### Conclusion and usage:
+So as a final step to actually test the build automation of the application one can simply navigate to the project root and execute the command:
+
+```bash
+gradle cleanAndBuildAll
+```
+
+[Go Back.](./index.md) [Go Next.](./CI.md)

docs/SPE/containerization.md

@@ -0,0 +1,83 @@
+# Containerization using Docker
+
+Containerization, facilitated by Docker, plays a crucial role in efficiently isolating and distributing applications. Docker containers encapsulate everything needed to run an application, ensuring consistency across various environments. This approach simplifies distribution, versioning, and dependency management, enhancing the overall portability of applications.
+
+To containerize the system, a strategy was devised to incorporate a Dockerfile within each microservice, tailoring it to the specific platform used for the service. From JaCaMo for the agents to Spring for the backend and Vue for the frontend, each Dockerfile is crafted accordingly.
+
+### Dockerfiles and Descriptions:
+
+#### 1. **JaCaMo Agents - Dockerfile for Build and Execution Phases:**
+
+<p align="center">
+  <img src="./img/container1.png" alt="./img/container1.png"/>
+</p>
+
+   - *Build Phase:*
+     - Starts from a Gradle image version 8.6.0 with JDK 21 on Alpine Linux.
+     - Copies the source code into the directory /home/gradle/src.
+     - Sets the working directory.
+     - Executes the `gradle wrapper` command.
+     - Builds the project with `./gradlew build --parallel`.
+
+   - *Execution Phase:*
+     - Uses an OpenJDK image version 19 on Alpine Linux.
+     - Sets the working directory for the application to /app.
+     - Exposes port 9080.
+     - Copies the source code from the build phase.
+     - Executes the Gradle task "runAgents" during application startup.
+
+#### 2. **Spring Boot Application - Dockerfile for Build and Deployment Phases:**
+
+<p align="center">
+  <img src="./img/container2.png" alt="./img/container2.png"/>
+</p>
+
+   - *Build Phase:*
+     - Utilizes the base Gradle image version 8.2.0 with Alpine Linux.
+     - Copies the project content into the container's directory.
+     - Sets the working directory.
+     - Exposes ports 9085 and 9092.
+     - Configures Gradle Wrapper.
+     - Builds the project using `./gradlew build` in parallel mode.
+
+   - *Deployment Phase:*
+     - Uses an OpenJDK image version 19.
+     - Creates a directory "/app" within the container.
+     - Copies the build result from the previous phase into the "/app" directory.
+     - Specifies the entrypoint to execute the Spring Boot application upon container launch.
+
+#### 3. **Node.js Application with Nginx - Dockerfile for Build and Production Phases:**
+
+<p align="center">
+  <img src="./img/container3.png" alt="./img/container3.png"/>
+</p>
+
+   - *Build Phase with Node.js:*
+     - Utilizes a Node.js LTS image on Alpine Linux.
+     - Sets the working directory to `/app`.
+     - Copies the source code into the current directory.
+     - Executes the `npm install` command.
+     - Executes the `npm run build` command.
+
+   - *Production Phase:*
+     - Utilizes a stable Nginx image on Alpine Linux.
+     - Copies the build result from the previous phase into the Nginx application directory.
+     - Copies the Nginx configuration file.
+     - Exposes ports 80 and 8080.
+     - Starts Nginx with the command `nginx -g 'daemon off;` during container execution.
+
+### Docker Compose:
+
+The Dockerfiles are orchestrated using Docker-Compose, a tool simplifying the management of multi-container Docker applications. The `compose.yml` file defines the configuration, services, and dependencies of the application.
+
+<p align="center">
+  <img src="./img/docker-compose.png" alt="docker-compose.png"/>
+</p>
+
+   - Specifies the version of the Compose file format.
+   - Defines four distinct services: Vue.js application, user database, Spring application with a database, and a generic application with agents.
+   - Configures mapped ports for each service.
+
+Running the command `docker compose up` will initiate the Docker containers, automatically executing `gradlew` within them. This fully automates the system, providing a seamless and consistent deployment environment.
+
+[Go Back.](./index.md) [Go Next.](./CD.md)