readme
This commit is contained in:
@@ -12,6 +12,7 @@ Objectif : application self-hosted permettant de :
|
||||
- Calculer une **note globale** et des sous-scores (CPU, mémoire, disque, réseau, GPU).
|
||||
- Afficher un **dashboard** triant les machines par performance globale.
|
||||
- Associer des liens constructeurs et des documents (PDF / images) à chaque machine.
|
||||
- tu verifiera bien sur la coherence entre tous les fichier de consigne de prompt et si le choix des outils est cohérent
|
||||
|
||||
L’application doit être :
|
||||
- **Self-hosted** sur une machine Linux (Debian) au format Docker.
|
||||
|
||||
192
05_webui_design.md
Normal file
192
05_webui_design.md
Normal file
@@ -0,0 +1,192 @@
|
||||
|
||||
# 05 – Design WebUI (structure, pages, composants)
|
||||
|
||||
Objectif : définir l’interface utilisateur de Linux BenchTools, les pages, les composants, l’organisation visuelle et les interactions nécessaires.
|
||||
|
||||
---
|
||||
|
||||
# 1. Principes généraux
|
||||
|
||||
- Interface orientée **observabilité** des performances machines.
|
||||
- Style sombre **Monokai-like**.
|
||||
- Pages structurées en **cartes** et **tableaux lisibles**.
|
||||
- Navigation : **Dashboard**, **Devices**, **Settings**.
|
||||
- Composants réutilisables : badges score, cartes hardware, tableaux benchmark.
|
||||
|
||||
---
|
||||
|
||||
# 2. Pages de la WebUI
|
||||
|
||||
## 2.1. Dashboard (`/`)
|
||||
Présente un aperçu du parc machines et un classement global.
|
||||
|
||||
### Contenu :
|
||||
- **Stats globales**
|
||||
- Nombre de devices
|
||||
- Nombre total de benchmarks
|
||||
- Score global moyen
|
||||
- Dernier bench reçu
|
||||
- **Tableau Top Devices**
|
||||
- Rang
|
||||
- Hostname
|
||||
- Description
|
||||
- Score global
|
||||
- Scores CPU/MEM/DISK/NET/GPU
|
||||
- Dernier run
|
||||
- **Bloc “Quick Bench Script”**
|
||||
- Commande à copier pour exécuter un bench sur une nouvelle machine.
|
||||
|
||||
---
|
||||
|
||||
## 2.2. Liste Devices (`/devices`)
|
||||
|
||||
- Tableau paginé et filtrable
|
||||
- Colonnes :
|
||||
- Hostname
|
||||
- Description
|
||||
- Location
|
||||
- Tags
|
||||
- Dernier Score
|
||||
- Dernier Bench
|
||||
- Bouton “Voir”
|
||||
|
||||
Barre de recherche : filtre hostname / tags / description.
|
||||
|
||||
---
|
||||
|
||||
## 2.3. Page Device Détail (`/devices/{id}`)
|
||||
|
||||
### Sections :
|
||||
|
||||
#### A. Bandeau principal
|
||||
- Hostname
|
||||
- Description
|
||||
- Tags
|
||||
- Localisation / Owner
|
||||
|
||||
#### B. Résumé Hardware
|
||||
- CPU : modèle, cores, threads, fréquences
|
||||
- RAM : total, slots utilisés, détail
|
||||
- GPU
|
||||
- Stockage (NVMe/SSD/HDD)
|
||||
- Réseau
|
||||
- Carte mère / BIOS
|
||||
- OS / kernel
|
||||
|
||||
#### C. Dernier Benchmark
|
||||
- Score global + badge couleur
|
||||
- Scores CPU / MEM / DISK / NET / GPU
|
||||
- Timestamp
|
||||
- Bouton “Voir JSON complet”
|
||||
|
||||
#### D. Onglets
|
||||
|
||||
1. **Summary**
|
||||
2. **Benchmarks**
|
||||
- Tableau simple
|
||||
- Évolution future en graphe
|
||||
3. **Documents**
|
||||
- Upload PDF/images
|
||||
- Liste des documents
|
||||
- Boutons download/delete
|
||||
4. **Links**
|
||||
- Liste des liens constructeurs
|
||||
- Form ajout
|
||||
- Edit / Delete
|
||||
|
||||
---
|
||||
|
||||
## 2.4. Settings (`/settings`)
|
||||
|
||||
Champs configurables :
|
||||
- Bench server URL
|
||||
- Default iperf-server
|
||||
- Token API (lecture seule)
|
||||
- Commande bench générée automatiquement
|
||||
|
||||
---
|
||||
|
||||
# 3. Style visuel (Monokai Dark)
|
||||
|
||||
### Couleurs
|
||||
- Fond général : `#1e1e1e`
|
||||
- Cartes : `#2d2d2d`
|
||||
- Texte principal : `#f8f8f2`
|
||||
- Texte secondaire : `#cccccc`
|
||||
- Success : `#a6e22e`
|
||||
- Warning : `#fd971f`
|
||||
- Danger : `#f92672`
|
||||
|
||||
### Composants
|
||||
- **Badge Score**
|
||||
- 0–50 : rouge
|
||||
- 51–75 : orange
|
||||
- 76–100 : vert
|
||||
- **Cartes Hardware**
|
||||
- Layout en 2 ou 3 colonnes
|
||||
- **Tableaux**
|
||||
- Style striped + hover highlight
|
||||
|
||||
---
|
||||
|
||||
# 4. Mockups ASCII
|
||||
|
||||
## Dashboard
|
||||
```
|
||||
+---------------------------------------------------------------------------+
|
||||
| Linux BenchTools – Dashboard |
|
||||
+---------------------------------------------------------------------------+
|
||||
| Stats |
|
||||
| Devices: 12 Benchmarks: 47 Avg Score: 78.4 Last: 2025‑12‑07 |
|
||||
+---------------------------------------------------------------------------+
|
||||
| Top Devices |
|
||||
+---------------------------------------------------------------------------+
|
||||
| # | Hostname | Score | CPU | MEM | DISK | NET | GPU | Last Run |
|
||||
|---------------------------------------------------------------------------|
|
||||
| 1 | elitedesk-800g3 | 92 | 90 | 95 | 94 | 88 | -- | 10:32 |
|
||||
+---------------------------------------------------------------------------+
|
||||
| Quick Bench Script |
|
||||
| curl -s https://.../bench.sh | bash -s -- --server ... --token XXXX |
|
||||
+---------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
## Page Device
|
||||
```
|
||||
Device: elitedesk-800g3
|
||||
Location: Bureau Tags: lab, dev
|
||||
|
||||
Hardware Summary:
|
||||
CPU: Intel i7‑6700 (4C/8T, 3.4 → 4.0 GHz)
|
||||
RAM: 64GB (4×16GB)
|
||||
GPU: Intel HD 530
|
||||
Storage: NVMe 1TB + HDD 2TB
|
||||
Network: eth0 1Gbps
|
||||
OS: Debian 12 / Kernel 6.1
|
||||
|
||||
Last Benchmark:
|
||||
Global Score: 92 [GREEN]
|
||||
CPU 90 | MEM 95 | DISK 94 | NET 88 | GPU --
|
||||
Run: 2025‑12‑07 10:32
|
||||
|
||||
Tabs: [Summary] [Benchmarks] [Documents] [Links]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. API utilisée par le frontend
|
||||
|
||||
- `/api/devices`
|
||||
- `/api/devices/{id}`
|
||||
- `/api/devices/{id}/benchmarks`
|
||||
- `/api/devices/{id}/docs`
|
||||
- `/api/docs/{id}/download`
|
||||
- `/api/devices/{id}/links`
|
||||
|
||||
---
|
||||
|
||||
# 6. Améliorations futures
|
||||
|
||||
- Graphiques d’évolution des scores (Chart.js)
|
||||
- Mode mobile
|
||||
- Compare devices
|
||||
- Notifications en cas de baisse anormale de performance
|
||||
216
06_backend_architecture.md
Normal file
216
06_backend_architecture.md
Normal file
@@ -0,0 +1,216 @@
|
||||
|
||||
# 06 – Architecture Backend & Déploiement (FastAPI + Uvicorn + Docker)
|
||||
|
||||
Objectif : définir la structure technique du backend, l'organisation du code, les dépendances,
|
||||
le déploiement via Docker, et les bonnes pratiques de maintenance.
|
||||
|
||||
---
|
||||
|
||||
# 1. Architecture générale du backend
|
||||
|
||||
Le backend repose sur :
|
||||
|
||||
- Python **3.11+**
|
||||
- **FastAPI** (framework web)
|
||||
- **Uvicorn** (serveur ASGI)
|
||||
- **SQLite** (stockage local)
|
||||
- **SQLAlchemy** (ORM)
|
||||
- **Pydantic** (validation des schémas)
|
||||
- Docker (déploiement)
|
||||
- Arborescence claire modulaire
|
||||
|
||||
---
|
||||
|
||||
# 2. Arborescence recommandée
|
||||
|
||||
```
|
||||
backend/
|
||||
│
|
||||
├── app/
|
||||
│ ├── api/
|
||||
│ │ ├── benchmark.py
|
||||
│ │ ├── devices.py
|
||||
│ │ ├── docs.py
|
||||
│ │ ├── links.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── core/
|
||||
│ │ ├── config.py
|
||||
│ │ ├── security.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── models/
|
||||
│ │ ├── device.py
|
||||
│ │ ├── hardware_snapshot.py
|
||||
│ │ ├── benchmark.py
|
||||
│ │ ├── manufacturer_link.py
|
||||
│ │ ├── document.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── schemas/
|
||||
│ │ ├── benchmark.py
|
||||
│ │ ├── device.py
|
||||
│ │ ├── hardware.py
|
||||
│ │ ├── document.py
|
||||
│ │ ├── link.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── db/
|
||||
│ │ ├── base.py
|
||||
│ │ ├── session.py
|
||||
│ │ ├── init_db.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── utils/
|
||||
│ │ ├── scoring.py
|
||||
│ │ └── __init__.py
|
||||
│ │
|
||||
│ ├── main.py
|
||||
│ └── __init__.py
|
||||
│
|
||||
├── Dockerfile
|
||||
├── requirements.txt
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 3. Dépendances backend (requirements.txt)
|
||||
|
||||
```
|
||||
fastapi
|
||||
uvicorn
|
||||
sqlalchemy
|
||||
alembic
|
||||
pydantic
|
||||
python-multipart
|
||||
jinja2
|
||||
aiofiles
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 4. Fonctionnement principal
|
||||
|
||||
## 4.1 main.py
|
||||
|
||||
- Initialise FastAPI
|
||||
- Charge les routes `/api/*`
|
||||
- Initialise la base SQLite
|
||||
- Expose un `GET /api/health`
|
||||
|
||||
---
|
||||
|
||||
# 5. Configuration (core/config.py)
|
||||
|
||||
Variables chargées via environnement :
|
||||
|
||||
- `API_TOKEN`
|
||||
- `DATABASE_URL` → `sqlite:///./data.db`
|
||||
- `UPLOAD_DIR` → `./uploads`
|
||||
|
||||
---
|
||||
|
||||
# 6. Déploiement Docker
|
||||
|
||||
## 6.1 Dockerfile
|
||||
|
||||
```
|
||||
FROM python:3.11-slim
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
COPY requirements.txt .
|
||||
RUN pip install --no-cache-dir -r requirements.txt
|
||||
|
||||
COPY app ./app
|
||||
|
||||
RUN mkdir -p /app/uploads /app/data
|
||||
|
||||
ENV API_TOKEN=CHANGE_ME
|
||||
ENV DATABASE_URL=sqlite:////app/data/data.db
|
||||
ENV UPLOAD_DIR=/app/uploads
|
||||
|
||||
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8007"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6.2 docker-compose.yml
|
||||
|
||||
```
|
||||
version: "3.9"
|
||||
|
||||
services:
|
||||
backend:
|
||||
build: ./backend
|
||||
container_name: linux_benchtools_backend
|
||||
ports:
|
||||
- "8007:8007"
|
||||
volumes:
|
||||
- ./backend/data:/app/data
|
||||
- ./backend/uploads:/app/uploads
|
||||
environment:
|
||||
API_TOKEN: "SUPER_SECRET_TOKEN"
|
||||
DATABASE_URL: "sqlite:////app/data/data.db"
|
||||
UPLOAD_DIR: "/app/uploads"
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 7. Gestion des documents (PDF, images)
|
||||
|
||||
- Stockés dans `/app/uploads`
|
||||
- Nommage unique (hash)
|
||||
- Entrée correspondante dans la BDD
|
||||
- Accessibles via `/api/docs/{id}/download`
|
||||
|
||||
---
|
||||
|
||||
# 8. Pipeline d’un benchmark
|
||||
|
||||
1. Le client exécute `bench.sh`
|
||||
2. Un JSON complet est envoyé vers POST `/api/benchmark`
|
||||
3. Vérification du token
|
||||
4. Recherche ou création du device
|
||||
5. Création d’un hardware snapshot
|
||||
6. Création d’un benchmark
|
||||
7. Calcul / stockage du score global
|
||||
8. Réponse `{status: "ok", ...}`
|
||||
|
||||
---
|
||||
|
||||
# 9. Module scoring (utils/scoring.py)
|
||||
|
||||
Calcule :
|
||||
|
||||
```
|
||||
global_score =
|
||||
cpu * 0.30 +
|
||||
mem * 0.20 +
|
||||
disk * 0.25 +
|
||||
net * 0.15 +
|
||||
gpu * 0.10
|
||||
```
|
||||
|
||||
Utilise les scores normalisés reçus depuis le client.
|
||||
|
||||
---
|
||||
|
||||
# 10. Sécurité
|
||||
|
||||
- API Token unique pour tous les clients
|
||||
- Upload limité en taille
|
||||
- CORS restreint au LAN si besoin
|
||||
- Aucun endpoint destructif sans authentification
|
||||
|
||||
---
|
||||
|
||||
# 11. Maintenance
|
||||
|
||||
- Backup SQLite via cron
|
||||
- Logs Docker
|
||||
- Vérification santé via `/api/health`
|
||||
- Ajout futur : export JSON/CSV global
|
||||
|
||||
238
08_installation_bootstrap.md
Normal file
238
08_installation_bootstrap.md
Normal file
@@ -0,0 +1,238 @@
|
||||
|
||||
# 08 – Script d'installation & Bootstrapping (install.sh)
|
||||
|
||||
Objectif : fournir un guide exhaustif et un script d’installation automatisée de l’application
|
||||
**Linux BenchTools** (backend + frontend + dépendances) ainsi que son organisation dans le dépôt.
|
||||
|
||||
Ce fichier décrit :
|
||||
|
||||
- Le rôle du script `install.sh`
|
||||
- Les prérequis système
|
||||
- L’installation via Docker ou native
|
||||
- La génération automatique de l’arborescence
|
||||
- Les variables d’environnement nécessaires
|
||||
- Le lancement des services
|
||||
|
||||
---
|
||||
|
||||
# 1. Objectifs du script `install.sh`
|
||||
|
||||
Le script doit :
|
||||
|
||||
1. Vérifier les prérequis (Docker, Docker Compose, Python si installation native)
|
||||
2. Créer l'arborescence du projet si inexistante
|
||||
3. Générer les fichiers `.env` nécessaires
|
||||
4. Installer le backend (FastAPI)
|
||||
5. Installer le frontend (fichiers statiques)
|
||||
6. Construire et lancer les conteneurs
|
||||
7. Vérifier que l’application fonctionne via un health check
|
||||
8. Afficher les URL utiles et les commandes d’usage
|
||||
|
||||
---
|
||||
|
||||
# 2. Arborescence créée automatiquement
|
||||
|
||||
```
|
||||
linux-benchtools/
|
||||
│
|
||||
├── backend/
|
||||
│ ├── app/
|
||||
│ ├── Dockerfile
|
||||
│ ├── requirements.txt
|
||||
│ └── data/ (auto)
|
||||
│
|
||||
├── frontend/
|
||||
│ ├── index.html
|
||||
│ ├── devices.html
|
||||
│ ├── device_detail.html
|
||||
│ ├── settings.html
|
||||
│ ├── css/
|
||||
│ └── js/
|
||||
│
|
||||
├── uploads/ (auto)
|
||||
│
|
||||
├── docker-compose.yml
|
||||
├── .env
|
||||
└── install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 3. Prérequis système
|
||||
|
||||
Le script doit vérifier la présence de :
|
||||
|
||||
- **curl**
|
||||
- **git**
|
||||
- **Docker**
|
||||
- **Docker Compose (plugin)**
|
||||
|
||||
Si absent → afficher un message clair (avec commande d’installation Debian/Ubuntu).
|
||||
|
||||
Exemple :
|
||||
|
||||
```bash
|
||||
if ! command -v docker >/dev/null 2>&1; then
|
||||
echo "[ERREUR] Docker n’est pas installé."
|
||||
echo "Installez-le avec :"
|
||||
echo " curl -fsSL https://get.docker.com | sh"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 4. Fichier `.env` généré
|
||||
|
||||
Le script crée automatiquement un fichier `.env` si absent.
|
||||
|
||||
Exemple :
|
||||
|
||||
```
|
||||
API_TOKEN=$(openssl rand -hex 32)
|
||||
DATABASE_URL=sqlite:////app/data/data.db
|
||||
UPLOAD_DIR=/app/uploads
|
||||
BACKEND_PORT=8007
|
||||
FRONTEND_PORT=8087
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 5. docker-compose.yml généré
|
||||
|
||||
Le script crée un fichier minimal :
|
||||
|
||||
```
|
||||
version: "3.9"
|
||||
|
||||
services:
|
||||
backend:
|
||||
build: ./backend
|
||||
ports:
|
||||
- "${BACKEND_PORT}:8007"
|
||||
volumes:
|
||||
- ./backend/data:/app/data
|
||||
- ./uploads:/app/uploads
|
||||
env_file: .env
|
||||
restart: unless-stopped
|
||||
|
||||
frontend:
|
||||
image: nginx:latest
|
||||
volumes:
|
||||
- ./frontend:/usr/share/nginx/html:ro
|
||||
ports:
|
||||
- "${FRONTEND_PORT}:80"
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. Installation native (option)
|
||||
|
||||
Si l'utilisateur passe `install.sh --native` :
|
||||
|
||||
- Installation Python + venv
|
||||
- Installation requirements.txt
|
||||
- Exécution via :
|
||||
|
||||
```
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8007
|
||||
```
|
||||
|
||||
Frontend servi via un simple `python3 -m http.server`.
|
||||
|
||||
---
|
||||
|
||||
# 7. Vérification de l’installation
|
||||
|
||||
Une fois les services lancés :
|
||||
|
||||
```
|
||||
curl -s http://localhost:${BACKEND_PORT}/api/health
|
||||
```
|
||||
|
||||
Si réponse :
|
||||
|
||||
```
|
||||
{"status":"ok"}
|
||||
```
|
||||
|
||||
→ installation validée.
|
||||
|
||||
---
|
||||
|
||||
# 8. Affichage final après installation
|
||||
|
||||
Le script doit afficher :
|
||||
|
||||
```
|
||||
Installation terminée !
|
||||
|
||||
Backend API : http://localhost:8007
|
||||
Frontend UI : http://localhost:8087
|
||||
Token API : <xxx>
|
||||
|
||||
Pour exécuter un benchmark sur une machine :
|
||||
curl -s <URL bench.sh> | bash -s -- --server http://<ip>:8007/api/benchmark --token <TOKEN>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 9. Structure du script `install.sh`
|
||||
|
||||
### Exemple de squelette :
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
|
||||
set -e
|
||||
|
||||
echo "[INFO] Vérification des prérequis..."
|
||||
# test docker, docker compose, curl...
|
||||
|
||||
echo "[INFO] Création des dossiers..."
|
||||
mkdir -p backend/data
|
||||
mkdir -p uploads
|
||||
|
||||
echo "[INFO] Génération du fichier .env..."
|
||||
if [ ! -f .env ]; then
|
||||
API_TOKEN=$(openssl rand -hex 32)
|
||||
cat <<EOF > .env
|
||||
API_TOKEN=$API_TOKEN
|
||||
DATABASE_URL=sqlite:////app/data/data.db
|
||||
UPLOAD_DIR=/app/uploads
|
||||
BACKEND_PORT=8007
|
||||
FRONTEND_PORT=8087
|
||||
EOF
|
||||
fi
|
||||
|
||||
echo "[INFO] Construction des containers..."
|
||||
docker compose build
|
||||
|
||||
echo "[INFO] Lancement..."
|
||||
docker compose up -d
|
||||
|
||||
echo "[INFO] Vérification..."
|
||||
sleep 2
|
||||
curl -s http://localhost:8007/api/health || {
|
||||
echo "[ERREUR] Le backend ne répond pas."
|
||||
exit 1
|
||||
}
|
||||
|
||||
echo "----------------------------------------------"
|
||||
echo " Linux BenchTools installé avec succès !"
|
||||
echo " Backend : http://localhost:8007"
|
||||
echo " Frontend : http://localhost:8087"
|
||||
echo " Token : $(grep API_TOKEN .env | cut -d= -f2)"
|
||||
echo "----------------------------------------------"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 10. Améliorations futures
|
||||
|
||||
- Choix interactif du port
|
||||
- Installation sans Docker (automatique)
|
||||
- Ajout d'un mode "cluster" (plusieurs workers backend)
|
||||
- Génération automatique d’un certificat TLS
|
||||
|
||||
263
09_tests_qualite.md
Normal file
263
09_tests_qualite.md
Normal file
@@ -0,0 +1,263 @@
|
||||
|
||||
# 09 – Stratégie de tests, validation et qualité pour Linux BenchTools
|
||||
|
||||
Objectif : définir comment tester et valider chaque brique de l’application
|
||||
(backend, script bench, frontend), afin d’assurer fiabilité, reproductibilité des mesures
|
||||
et facilité de maintenance.
|
||||
|
||||
Ce document sert de guide pour écrire les tests et scénarios de validation manuelle.
|
||||
|
||||
---
|
||||
|
||||
# 1. Périmètre des tests
|
||||
|
||||
Les tests couvrent :
|
||||
|
||||
1. **Backend API**
|
||||
- Validation des endpoints
|
||||
- Validation de la persistance en base
|
||||
- Validation de la sécurité (token)
|
||||
2. **Script client `bench.sh`**
|
||||
- Fonctionnement sur différentes machines Debian/Ubuntu
|
||||
- Gestion des erreurs (outils manquants, serveur indisponible)
|
||||
- Qualité du JSON envoyé
|
||||
3. **Frontend WebUI**
|
||||
- Rendu des pages (Dashboard, Devices, Device Detail, Settings)
|
||||
- Consommation correcte de l’API
|
||||
- UX minimale (lisibilité, tri, navigation)
|
||||
4. **Tests de bout en bout (E2E)**
|
||||
- Exécution complète d’un bench depuis un client → apparition dans le Dashboard.
|
||||
|
||||
---
|
||||
|
||||
# 2. Tests Backend
|
||||
|
||||
## 2.1. Types de tests
|
||||
|
||||
- **Tests unitaires** : fonctions isolées (scoring, mapping JSON → modèles).
|
||||
- **Tests d’intégration** : endpoints FastAPI avec base SQLite de test.
|
||||
- **Tests E2E API** : envoi d’un payload complet depuis un script de test.
|
||||
|
||||
Framework recommandé :
|
||||
- `pytest`
|
||||
- `httpx` ou client de test FastAPI
|
||||
|
||||
## 2.2. Cas de test principaux
|
||||
|
||||
### a) POST /api/benchmark
|
||||
|
||||
- [OK] Payload complet, token valide :
|
||||
- Retourne 200
|
||||
- Crée un `device` si inexistant
|
||||
- Crée un `hardware_snapshot`
|
||||
- Crée un `benchmark`
|
||||
- [OK] Device existant :
|
||||
- Réutilise le `device`
|
||||
- [ERR] Token manquant :
|
||||
- 401
|
||||
- [ERR] Token incorrect :
|
||||
- 401
|
||||
- [ERR] JSON invalide :
|
||||
- 400
|
||||
|
||||
### b) GET /api/devices
|
||||
|
||||
- [OK] Base vide → items = [].
|
||||
- [OK] Avec plusieurs devices et benchmarks :
|
||||
- Retourne un `last_benchmark` cohérent.
|
||||
- [OK] Paramètres `page`, `page_size` :
|
||||
- Pagination effective.
|
||||
|
||||
### c) GET /api/devices/{id}
|
||||
|
||||
- [OK] Device existant :
|
||||
- Retourne résumé, snapshot, dernier benchmark.
|
||||
- [ERR] Device inexistant :
|
||||
- 404.
|
||||
|
||||
### d) Liens constructeur
|
||||
|
||||
- [OK] CRUD complet sur `/api/devices/{id}/links`.
|
||||
- [ERR] URL invalide (peut être toléré ou validé selon règle).
|
||||
|
||||
### e) Documents
|
||||
|
||||
- [OK] Upload PDF :
|
||||
- Fichier stocké physiquement
|
||||
- Entrée BDD créée
|
||||
- [OK] Download :
|
||||
- Renvoie bon `Content-Type`
|
||||
- [ERR] doc_id invalide :
|
||||
- 404.
|
||||
|
||||
---
|
||||
|
||||
# 3. Tests Script client (bench.sh)
|
||||
|
||||
## 3.1. Contexte
|
||||
|
||||
Les tests sur `bench.sh` sont principalement :
|
||||
- des tests manuels guidés
|
||||
- des tests automatisables partiellement (CI dans un container Docker).
|
||||
|
||||
## 3.2. Cas de test
|
||||
|
||||
### a) Aide & usage
|
||||
|
||||
- `bench.sh --help` → affiche usage.
|
||||
- Sans arguments → erreur claire.
|
||||
|
||||
### b) Prérequis
|
||||
|
||||
- Si `curl`, `jq`, `sysbench`, `fio` manquants :
|
||||
- message explicite
|
||||
- tentative d’installation si possible (apt-get)
|
||||
- en cas d’échec, test concerné désactivé mais script continue.
|
||||
|
||||
### c) Exécution minimale
|
||||
|
||||
- `bench.sh --server http://backend:8007/api/benchmark --token XXX` :
|
||||
- Détecte le hostname
|
||||
- Exécute les tests par défaut
|
||||
- Envoie un JSON valide (vérifiable via logs backend).
|
||||
|
||||
### d) Modes d’options
|
||||
|
||||
- `--short` :
|
||||
- Durées de tests CPU/mémoire/disk raccourcies
|
||||
- `--skip-network` :
|
||||
- Aucun test iperf3, bloc `results.network` absent ou null
|
||||
- `--iperf-server` avec serveur iperf opérationnel :
|
||||
- Champs réseau correctement renseignés.
|
||||
|
||||
### e) Gestion des erreurs réseau
|
||||
|
||||
- Backend down :
|
||||
- Message d’erreur clair
|
||||
- Code HTTP ≠ 200 connu
|
||||
- Iperf3 indisponible :
|
||||
- Bloc network absent/null
|
||||
|
||||
---
|
||||
|
||||
# 4. Tests Frontend
|
||||
|
||||
## 4.1. Smoke tests (manuels)
|
||||
|
||||
- Accès à :
|
||||
- `/` → Dashboard
|
||||
- `/devices`
|
||||
- `/devices/{id}`
|
||||
- `/settings`
|
||||
- Vérification du rendu :
|
||||
- Aucune erreur JS console
|
||||
- Chargement des datas via API
|
||||
- Tri de base dans les tableaux
|
||||
|
||||
## 4.2. Tests fonctionnels (scénarios)
|
||||
|
||||
### Scénario 1 : Premier lancement
|
||||
|
||||
1. Déployer l’application.
|
||||
2. Vérifier Dashboard vide, message “Aucun device”.
|
||||
3. Exécuter `bench.sh` sur une machine.
|
||||
4. Rafraîchir Dashboard :
|
||||
- Device apparaît avec score.
|
||||
|
||||
### Scénario 2 : consultation d’un device
|
||||
|
||||
1. Cliquer sur un device dans le Dashboard.
|
||||
2. Page détail :
|
||||
- Hardware résumé cohérent.
|
||||
- Dernier benchmark affiché.
|
||||
3. Onglet Benchmarks :
|
||||
- Historique listé.
|
||||
|
||||
### Scénario 3 : Documents
|
||||
|
||||
1. Aller dans onglet Documents d’un device.
|
||||
2. Uploader un PDF.
|
||||
3. Vérifier sa présence dans la liste.
|
||||
4. Télécharger pour confirmer.
|
||||
|
||||
### Scénario 4 : Liens constructeur
|
||||
|
||||
1. Onglet Links d’un device.
|
||||
2. Ajouter un lien avec label + URL.
|
||||
3. Vérifier qu’il est cliquable.
|
||||
4. Tester suppression.
|
||||
|
||||
---
|
||||
|
||||
# 5. Tests E2E (de bout en bout)
|
||||
|
||||
Objectif : couvrir la chaîne complète depuis la machine cliente jusqu’au Dashboard.
|
||||
|
||||
### Scénario E2E type
|
||||
|
||||
1. Lancer backend + frontend via `docker compose up`.
|
||||
2. Déployer `bench.sh` sur un client Debian.
|
||||
3. Exécuter :
|
||||
|
||||
```bash
|
||||
curl -s https://.../bench.sh | bash -s -- \
|
||||
--server http://IP_BACKEND:8007/api/benchmark \
|
||||
--token XXX \
|
||||
--iperf-server 10.0.0.10
|
||||
```
|
||||
|
||||
4. Vérifier côté backend (logs) qu’un benchmark a été créé.
|
||||
5. Ouvrir le Dashboard :
|
||||
- Device présent, scores visibles.
|
||||
|
||||
---
|
||||
|
||||
# 6. Données de test
|
||||
|
||||
Créer un répertoire `tests/data/` contenant :
|
||||
|
||||
- Exemples de payload JSON de bench :
|
||||
- `bench_full.json` (tous tests)
|
||||
- `bench_no_gpu.json`
|
||||
- `bench_short.json`
|
||||
- Scripts auxiliaires :
|
||||
- `send_bench_payload.py` (envoi direct d’un payload pour tests).
|
||||
|
||||
---
|
||||
|
||||
# 7. Automatisation CI (optionnel)
|
||||
|
||||
Intégration avec :
|
||||
|
||||
- GitHub Actions
|
||||
- Gitea Actions / Drone / Woodpecker
|
||||
|
||||
Tâches CI typiques :
|
||||
|
||||
1. `pytest` sur le backend
|
||||
2. Lancement d’un backend en mode test
|
||||
3. Envoi d’un payload JSON factice
|
||||
4. Vérification de la réponse HTTP
|
||||
|
||||
---
|
||||
|
||||
# 8. Critères de qualité
|
||||
|
||||
L’application sera considérée comme “OK” pour usage perso si :
|
||||
|
||||
- Au moins 1 test unitaire par endpoint critique
|
||||
- Un scénario E2E réussi
|
||||
- `bench.sh` fonctionne sur :
|
||||
- 1 machine physique
|
||||
- 1 VM
|
||||
- Les erreurs d’auth/token sont gérées proprement
|
||||
- Le Dashboard reste utilisable avec plusieurs dizaines de devices et benchmarks
|
||||
|
||||
---
|
||||
|
||||
# 9. Améliorations possibles
|
||||
|
||||
- Ajout de tests de charge (Gatling / k6) sur le backend
|
||||
- Ajout de tests de non-régression des scores (baseline)
|
||||
- Ajout de tests visuels (Playwright, Cypress)
|
||||
- Intégration d’un badge “build/test status” dans le README principal
|
||||
216
10_roadmap_evolutions.md
Normal file
216
10_roadmap_evolutions.md
Normal file
@@ -0,0 +1,216 @@
|
||||
|
||||
# 10 – Roadmap & évolutions futures pour Linux BenchTools
|
||||
|
||||
Objectif : lister les évolutions possibles de l’application, organisées par phases, avec une vision
|
||||
à court, moyen et long terme. Ce fichier sert de base pour prioriser les développements.
|
||||
|
||||
---
|
||||
|
||||
# 1. Vision globale
|
||||
|
||||
Linux BenchTools doit évoluer depuis un simple serveur de benchmarks centralisés vers :
|
||||
|
||||
- Un **inventaire matériel dynamique** de ton parc.
|
||||
- Un **historique de performance** exploitable (avant/après upgrade, changement de config, etc.).
|
||||
- Un **outil d’aide à la décision** (quelle machine est la plus adaptée pour tel usage).
|
||||
- Un **hub de diagnostics** (détection de régression de perf, disques fragiles, réseau bridé…).
|
||||
|
||||
---
|
||||
|
||||
# 2. Phase 1 – MVP (déjà spécifiée dans les fichiers 01 → 09)
|
||||
|
||||
Fonctionnalités :
|
||||
|
||||
- Réception de benchmarks via `bench.sh`
|
||||
- Stockage dans SQLite
|
||||
- Dashboard avec classement des machines
|
||||
- Détail device + historique de benchmarks
|
||||
- Liens constructeur
|
||||
- Upload de documents (PDF, images)
|
||||
- Script d’installation (Docker / compose)
|
||||
|
||||
Objectif :
|
||||
Avoir une base utilisable **en production perso** sur ton infra maison.
|
||||
|
||||
---
|
||||
|
||||
# 3. Phase 2 – Améliorations UX & stabilité
|
||||
|
||||
## 3.1. Frontend
|
||||
|
||||
- Tri avancé sur les colonnes (score, date dernier bench, hostname).
|
||||
- Filtre par tags, type de machine (bare-metal / VM / SBC).
|
||||
- Ajout d’icônes simples (type machine, OS, réseau 1G/2.5G/10G…).
|
||||
- Page “Benchmarks” globale (tous les benchmarks, filtrables par device).
|
||||
|
||||
## 3.2. Backend
|
||||
|
||||
- Meilleure gestion des erreurs côté API (messages clairs, codes cohérents).
|
||||
- Pagination plus fine (page_size configurable).
|
||||
- Logging structuré (JSON logs optionnels).
|
||||
- Limitation taille payload JSON (protection simple).
|
||||
|
||||
## 3.3. Script client
|
||||
|
||||
- Mode “dry-run” (afficher JSON sans l’envoyer).
|
||||
- Mode “debug” (log détaillé des commandes).
|
||||
|
||||
---
|
||||
|
||||
# 4. Phase 3 – Historisation avancée & graphes
|
||||
|
||||
## 4.1. Graphes dans la WebUI
|
||||
|
||||
- Sur page device :
|
||||
- Graphique du **global_score** sur le temps.
|
||||
- Graphiques séparés :
|
||||
- CPU score vs temps
|
||||
- Mémoire score vs temps
|
||||
- Disque score vs temps
|
||||
- Réseau score vs temps
|
||||
- Lib JS possible :
|
||||
- Chart.js ou ECharts (simple, self-hosté).
|
||||
|
||||
## 4.2. Comparaison de benchmarks
|
||||
|
||||
- Comparer 2 benchmarks d’un même device :
|
||||
- Afficher les différences (avant/après ajout RAM, changement SSD…).
|
||||
- Comparer 2 devices :
|
||||
- Table des scores côte-à-côte.
|
||||
- Exemple d’usage :
|
||||
- “Quelle machine est la meilleure candidate pour un nouveau service Docker ?”
|
||||
|
||||
---
|
||||
|
||||
# 5. Phase 4 – Détection de régressions & alertes
|
||||
|
||||
## 5.1. Détection automatique
|
||||
|
||||
- Calcul d’un “baseline” par device :
|
||||
- par exemple moyenne des N meilleurs scores.
|
||||
- Lors d’un nouveau bench :
|
||||
- si le score est inférieur de X% à la baseline → marquer en **WARNING**.
|
||||
- Indicateurs :
|
||||
- CPU plus lent
|
||||
- Disque sensiblement plus lent (fragilité SSD/HDD)
|
||||
- Réseau plus lent (câble / switch / config ?)
|
||||
|
||||
## 5.2. Alertes
|
||||
|
||||
- Marquage visuel dans la WebUI (icône warning).
|
||||
- Export JSON ou webhook Webhook simple :
|
||||
- POST vers un endpoint externe (ex: Home Assistant, Node-RED, etc.)
|
||||
- Intégration possible :
|
||||
- Appel HTTP vers Home Assistant pour créer une notification.
|
||||
|
||||
---
|
||||
|
||||
# 6. Phase 5 – Intégrations externes
|
||||
|
||||
## 6.1. Intégration Gitea / Git
|
||||
|
||||
- Stocker le dépôt `bench.sh` dans une forge (déjà le cas).
|
||||
- Ajouter :
|
||||
- Liens vers la version exacte du script qui a généré tel bench.
|
||||
- Option :
|
||||
- Webhook Gitea → déclencher bench sur un device après un changement de config.
|
||||
|
||||
## 6.2. Intégration Home Assistant
|
||||
|
||||
- Exposer certains indicateurs via une API ou MQTT :
|
||||
- Dernier score par device
|
||||
- Warn/alert sur régression
|
||||
- Dashboard HA :
|
||||
- Carte des machines avec état “OK / Warning / Error”.
|
||||
|
||||
## 6.3. Intégration Prometheus / Grafana (option)
|
||||
|
||||
- Exporter métriques (nombre de devices, benchs, scores moyens) via `/metrics`.
|
||||
- Visualisation dans Grafana.
|
||||
|
||||
---
|
||||
|
||||
# 7. Phase 6 – Extensions techniques
|
||||
|
||||
## 7.1. Support multi-OS
|
||||
|
||||
- Extension `bench.sh` pour :
|
||||
- Linux non-Debian (Arch, Fedora)
|
||||
- macOS (optionnel)
|
||||
- Windows (PowerShell script séparé)
|
||||
|
||||
## 7.2. Agents “semi-persistants”
|
||||
|
||||
- Mode où un service systemd sur certains serveurs :
|
||||
- exécute un bench toutes les X semaines.
|
||||
- envoie automatiquement les données au backend.
|
||||
|
||||
## 7.3. Export / Import
|
||||
|
||||
- Export complet de :
|
||||
- devices
|
||||
- benchmarks
|
||||
- hardware_snapshots
|
||||
- Formats :
|
||||
- JSON
|
||||
- CSV (pour certains tableaux)
|
||||
- Import depuis un ancien fichier → migration facile vers nouvelle instance.
|
||||
|
||||
---
|
||||
|
||||
# 8. Phase 7 – UX & ergonomie avancées
|
||||
|
||||
- Tags et “groupes” de devices (ex: “serveurs prod”, “lab”, “RPi”, “Proxmox nodes”).
|
||||
- Vues filtrées :
|
||||
- Vue “serveurs”
|
||||
- Vue “VM Proxmox”
|
||||
- Vue “SBC (RPi, OPi, etc.)”
|
||||
- Possibilité de nommer des “profils” :
|
||||
- ex: “Profil NVR”, “Profil VM/Proxmox”, “Profil PC Gaming”
|
||||
- et voir les devices qui matchent le mieux chaque profil en fonction de leur score.
|
||||
|
||||
---
|
||||
|
||||
# 9. Idées long terme (si tu veux pousser très loin)
|
||||
|
||||
- Auto-détection hardware via une petite API agent qui tourne sur les machines en continu (au-delà du script ponctuel).
|
||||
- Benchmark réseau multi-nœuds :
|
||||
- topologie logical de ton réseau
|
||||
- latences et débits entre plusieurs points.
|
||||
- Vue “Carte du réseau” :
|
||||
- affichage graphique des performances entre différentes machines.
|
||||
- Plugins :
|
||||
- Ajouter une API plugin pour créer ses propres tests (ex: bench spécifique Docker, base de données, etc.).
|
||||
|
||||
---
|
||||
|
||||
# 10. Priorisation suggérée
|
||||
|
||||
1. **Stabiliser MVP** (Phase 1 + tests fichier 09)
|
||||
2. UX de base + tri / filtre (Phase 2)
|
||||
3. Graphes d’historique (Phase 3)
|
||||
4. Détection régressions + petites alertes (Phase 4)
|
||||
5. Intégrations Home Assistant / Prometheus (Phase 5)
|
||||
6. Support multi-OS (Phase 6)
|
||||
7. Développements avancés (Phase 7+8)
|
||||
|
||||
---
|
||||
|
||||
# 11. TODO résumé par phase
|
||||
|
||||
- Phase 1 :
|
||||
- Implémenter API, DB, bench.sh, WebUI minimal, Docker, install.sh
|
||||
- Phase 2 :
|
||||
- Tri, filtres, ergonomie
|
||||
- Phase 3 :
|
||||
- Graphes (global_score, composantes)
|
||||
- Phase 4 :
|
||||
- Baselines, détection de régression, marquage visuel
|
||||
- Phase 5 :
|
||||
- Webhooks / MQTT / intégration HA
|
||||
- Phase 6 :
|
||||
- Scripts bench pour autres OS
|
||||
- Phase 7 :
|
||||
- Vues avancées, cartes réseau, plugins
|
||||
|
||||
Ce document pourra servir de base à un Kanban (Gitea, Kanboard, etc.) en créant une tâche par élément de la roadmap.
|
||||
Reference in New Issue
Block a user