Skip to content

Commit b1d9781

Browse files
MirkoZETAMirkoZETA
committed
Merge branch 'feature/documentation-improvement' into develop
2 parents 2c10471 + fc08501 commit b1d9781

10 files changed

Lines changed: 792 additions & 396 deletions

File tree

‎.github/workflows/README_DEV.md‎

Lines changed: 71 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,93 @@
1-
# Flex Net Sim Backend API - Development and Deployment Instructions
1+
# Flex Net Sim API - Development Guide
22

3-
This document is for developers who want to set up, develop, and deploy the Flex Net Sim Backend API.
3+
This guide helps developers set up, test, and deploy the Flex Net Sim Backend API.
44

55
## Prerequisites
66

7-
* Python 3.9 or higher
8-
* g++ (GNU C++ Compiler)
9-
* Docker (for containerization)
10-
* Google Cloud SDK (for deployment to Google Cloud Run)
11-
* A Google Cloud Project with Cloud Run API enabled.
7+
* Python 3.9+
8+
* g++ (GNU C++ Compiler)
9+
* Docker (for containerization)
10+
* A Google Cloud Project with Cloud Run API enabled
11+
12+
## Local Development Setup
13+
14+
1. **Clone the repository:**
15+
```bash
16+
git clone https://github.com/MirkoZETA/FlexNetSim-API.git
17+
cd FlexNetSim-API
18+
```
19+
20+
2. **Set up Python environment:**
21+
```bash
22+
# Create virtual environment
23+
python3 -m venv .venv
24+
25+
# Activate (Linux/macOS)
26+
source .venv/bin/activate
27+
28+
# Activate (Windows)
29+
.venv\Scripts\activate
30+
31+
# Install dependencies
32+
pip install -r requirements.txt
33+
```
34+
35+
3. **Run the application:**
36+
```bash
37+
flask --app backend run
38+
```
39+
The API will be available at `http://127.0.0.1:5000`.
40+
41+
4. **Test the API:**
42+
```bash
43+
# Test help endpoint
44+
curl http://127.0.0.1:5000/help
45+
46+
# Test simulation endpoint
47+
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
48+
```
49+
50+
## Testing
51+
52+
Run the test suite to ensure code quality:
1253

13-
## Getting Started (Local Development)
14-
15-
1. **Clone the repository:**
16-
```bash
17-
git clone [https://github.com/MirkoZETA/FlexNetSim-API.git](https://github.com/MirkoZETA/FlexNetSim-API.git)
18-
cd flask-simulation-backend
19-
```
20-
21-
2. **Create a Python virtual environment (recommended):**
22-
```bash
23-
python3 -m venv .venv
24-
```
25-
26-
On Linux/macOS:
27-
```bash
28-
source .venv/bin/activate
29-
```
30-
31-
On Windows
32-
```bash
33-
.venv\Scripts\activate
34-
```
35-
3. **Install Python dependencies:**
36-
```bash
37-
pip install -r requirements.txt
38-
```
39-
40-
4. **Run the Flask backend:**
41-
```bash
42-
flask --app backend run
43-
```
44-
The backend will be accessible at `http://127.0.0.1:5000`.
45-
46-
5. **Test**:
47-
```bash
48-
curl http://127.0.0.1:5000/help
49-
```
50-
or
51-
```bash
52-
curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
53-
```
54+
```bash
55+
pytest --cov=backend tests/
56+
```
5457

55-
### Dockerization
58+
## Docker Deployment
5659

57-
To build the Docker image:
60+
Build and run the Docker container locally:
5861

5962
```bash
63+
# Build image
6064
docker build -t fns-api .
65+
66+
# Run container
67+
docker run -p 5000:5000 fns-api
6168
```
6269

63-
## GCloud Deployment Configuration
70+
## Google Cloud Deployment Configuration
6471

65-
As a prerequisite is mandatory to apply the following steps to the GCloud project for the docker image build and upload to artifacts, and also service account creation and IAM policy binding:
72+
The following steps are required to configure your Google Cloud project for deployment. These steps focus solely on the Google Cloud setup, not the GitHub Actions workflow configuration.
6673

6774
[GCloud Configuration Video Tutorial](https://www.youtube.com/watch?v=KQUKDiBz3IA)
6875

69-
This video will guide you through the necessary configurations in the Google Cloud Console to prepare your project for Cloud Run deployments using GitHub Actions.
76+
**Note: This video demonstrates only the Google Cloud Console configurations.** The YAML workflow files shown in the video may be outdated and are not necessary for current deployments.
77+
78+
Follow the Google Cloud setup steps from the video, focusing on:
79+
80+
* Creating a project
81+
* Setting up Docker repositories
82+
* Creating service accounts
83+
* Configuring permissions
7084

71-
**Key Reminders from the Video & for Successful Deployment:**
85+
**Key Information to Record During Setup:**
7286

73-
* **Keep Track of Docker Image Name, Project ID:** Note these down during the video configuration, as you will need them in subsequent steps and for your GitHub Actions workflow.
74-
* **Service Account Email:** Ensure you create a Service Account as shown in the video and securely download and store the JSON key file. You'll also need to note the Service Account's email address.
87+
* **Docker Image Name and Project ID:** Note these for your deployment process
88+
* **Service Account Email:** Create a Service Account, download its JSON key file, and record the email address
7589

76-
**Post-Configuration Steps (using `gcloud` and `cloud-run`):**
90+
**Post-Configuration Steps (using `gcloud` CLI):**
7791

7892
1. Activate necessary apis:
7993

‎.github/workflows/gke-cd.yml‎

Lines changed: 4 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,17 @@
1-
name: Branch-Specific Deploy FNS API to Cloud Run
1+
name: Deploy to Cloud Run
22

33
on:
44
push:
55
branches:
66
- master
7-
- feature/*
8-
- develop
9-
pull_request:
10-
branches:
11-
- master
12-
- feature/*
13-
- develop
147

158
jobs:
16-
test:
17-
name: Run Backend Tests
18-
runs-on: ubuntu-latest
19-
steps:
20-
- name: Checkout code
21-
uses: actions/checkout@v2
22-
23-
- name: Set up Python 3.9
24-
uses: actions/setup-python@v2
25-
with:
26-
python-version: 3.9
27-
28-
- name: Install dependencies
29-
run: pip install -r requirements.txt
30-
31-
- name: Run tests
32-
run: python -m unittest tests/test_backend.py
33-
349
build-and-push-image:
3510
name: Build and Push Docker Image
3611
runs-on: ubuntu-latest
37-
needs: test
38-
if: github.ref == 'refs/heads/master' # Condition: Only run on master branch
3912
steps:
4013
- name: Checkout code
41-
uses: actions/checkout@v2
14+
uses: actions/checkout@v3
4215

4316
- name: Google Cloud Auth
4417
uses: google-github-actions/auth@v2
@@ -67,10 +40,9 @@ jobs:
6740
name: Deploy to Cloud Run
6841
runs-on: ubuntu-latest
6942
needs: build-and-push-image
70-
if: github.ref == 'refs/heads/master' # Condition: Only run on master branch
7143
steps:
72-
- name: Checkout code (again, if needed)
73-
uses: actions/checkout@v2
44+
- name: Checkout code
45+
uses: actions/checkout@v3
7446

7547
- name: Google Cloud Auth
7648
uses: google-github-actions/auth@v2

‎.github/workflows/test-coverage.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: Test Coverage
2+
3+
on:
4+
# Run on pushes to these branches
5+
push:
6+
branches:
7+
- master
8+
- feature/*
9+
- develop
10+
# Run on pull requests to these branches
11+
pull_request:
12+
branches:
13+
- master
14+
- feature/*
15+
- develop
16+
# Allow manual trigger
17+
workflow_dispatch:
18+
19+
# Permissions needed for GitHub Pages
20+
permissions:
21+
contents: read
22+
pages: write
23+
id-token: write
24+
25+
# Allow only one concurrent deployment
26+
concurrency:
27+
group: "pages"
28+
cancel-in-progress: false
29+
30+
jobs:
31+
# First job: Run tests and generate coverage report
32+
test-coverage:
33+
name: Run Tests with Coverage
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Checkout code
37+
uses: actions/checkout@v4
38+
39+
- name: Set up Python 3.9
40+
uses: actions/setup-python@v4
41+
with:
42+
python-version: 3.9
43+
44+
- name: Install dependencies
45+
run: |
46+
python -m pip install --upgrade pip
47+
pip install -r requirements.txt
48+
49+
- name: Run tests with coverage
50+
run: |
51+
pytest --cov=backend --cov-report=html tests/
52+
53+
- name: Upload coverage reports artifact
54+
if: github.ref == 'refs/heads/master'
55+
uses: actions/upload-artifact@v4
56+
with:
57+
name: coverage-report
58+
path: htmlcov/
59+
retention-days: 7
60+
61+
# Second job: Deploy coverage report to GitHub Pages
62+
deploy:
63+
name: Deploy Coverage Report
64+
needs: test-coverage
65+
# Only deploy from master branch
66+
if: github.ref == 'refs/heads/master'
67+
environment:
68+
name: github-pages
69+
url: ${{ steps.deployment.outputs.page_url }}
70+
runs-on: ubuntu-latest
71+
steps:
72+
- name: Download coverage reports
73+
uses: actions/download-artifact@v4
74+
with:
75+
name: coverage-report
76+
path: htmlcov/
77+
78+
- name: Setup Pages
79+
uses: actions/configure-pages@v3
80+
81+
- name: Move coverage to subdirectory
82+
run: |
83+
mkdir -p public/coverage
84+
mv htmlcov/* public/coverage/
85+
86+
- name: Upload pages artifact
87+
uses: actions/upload-pages-artifact@v2
88+
with:
89+
path: './public'
90+
91+
- name: Deploy to GitHub Pages
92+
id: deployment
93+
uses: actions/deploy-pages@v2

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,9 @@ simulation.out
55
.vscode/
66

77
# macOS
8-
**/.DS_Store
8+
**/.DS_Store
9+
10+
# Test files
11+
.coverage
12+
htmlcov
13+
.pytest_cache

‎CHANGELOG.md‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10-
### Added
11-
- Unitary tests.
12-
1310
### ROADMAP
1411
- Switch to Flex Net Sim v0.8.2.
15-
- Enchance previous algorithms.
12+
- Enhance previous algorithms.
1613
- Add algorithm BestFit.
17-
- Point README docs to oficial documentation.
1814
- Switch to new domain.
1915

16+
## [1.1.0] - 2025-03-01
17+
18+
### Added
19+
- Comprehensive unit tests for all API endpoints and functions
20+
- Test coverage reporting with pytest-cov
21+
- GitHub Pages integration for coverage reports
22+
- Coverage badges in README.md
23+
- New GitHub Actions workflow for test coverage
24+
25+
### Changed
26+
- Improved documentation in README.md with clearer structure and badges
27+
- Enhanced API documentation in backend.py with better comments and docstrings
28+
- Updated development guide with clearer instructions
29+
- Refactored GitHub Actions workflows to separate testing and deployment
30+
- Improved code comments and function documentation
31+
32+
### Fixed
33+
- Modified .gitignore to handle coverage files
34+
2035
## [1.0.0] - 2025-02-19
2136

2237
### Added
@@ -37,4 +52,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
3752
- API allocated in cloud run.
3853
- Documentation README for the process of develop/deployment located in [workflows](https://github.com/MirkoZETA/FlexNetSim-API/tree/master/.github/workflows/README_DEV.md).
3954

55+
[1.1.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v1.1.0
4056
[1.0.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v1.0.0

0 commit comments

Comments
 (0)