Remove HTML-to-Markdown parser and PDF generation functionality, clean up unused imports and whitespace
This commit is contained in:
@@ -0,0 +1,317 @@
|
||||
# 🚀 Guide d'Utilisation
|
||||
|
||||
Bienvenue dans le guide officiel de votre **Homelab Automation Dashboard** !
|
||||
Découvrez comment gérer et automatiser efficacement votre infrastructure grâce à cette solution puissante et centralisée.
|
||||
|
||||
---
|
||||
|
||||
## ⚡️ Démarrage Rapide {#help-quickstart}
|
||||
|
||||
<!-- quickstart-cards -->
|
||||
:::card green fa-1
|
||||
### Ajouter vos Hosts
|
||||
Commencez par ajouter vos serveurs dans la section `Hosts`. Chaque host nécessite un nom, une adresse IP et un système d'exploitation.
|
||||
:::
|
||||
|
||||
:::card blue fa-2
|
||||
### Bootstrap Ansible
|
||||
Exécutez le `Bootstrap` sur chaque host pour configurer l'accès SSH et les prérequis Ansible.
|
||||
:::
|
||||
|
||||
:::card purple fa-3
|
||||
### Automatiser
|
||||
Utilisez les `Actions Rapides` ou exécutez des playbooks personnalisés pour automatiser vos tâches.
|
||||
:::
|
||||
<!-- /quickstart-cards -->
|
||||
|
||||
---
|
||||
|
||||
## ❤️🩹 Indicateurs de Santé des Hosts {#help-indicators}
|
||||
|
||||
Chaque host affiche un indicateur visuel de santé représenté par des barres colorées. Cet indicateur combine plusieurs facteurs pour évaluer l'état global de votre serveur.
|
||||
|
||||
### Comprendre l'Indicateur
|
||||
|
||||
:::health-level excellent 5 green
|
||||
**Excellent** (5 barres vertes)
|
||||
Host en ligne, bootstrap OK, vérifié récemment
|
||||
:::
|
||||
|
||||
:::health-level good 3 yellow
|
||||
**Bon** (3-4 barres jaunes)
|
||||
Host fonctionnel mais certains aspects à améliorer
|
||||
:::
|
||||
|
||||
:::health-level medium 2 orange
|
||||
**Moyen** (2 barres oranges)
|
||||
Attention requise - vérification recommandée
|
||||
:::
|
||||
|
||||
:::health-level low 1 red
|
||||
**Faible** (1 barre rouge)
|
||||
Host hors ligne ou non configuré
|
||||
:::
|
||||
|
||||
### Facteurs de Calcul du Score
|
||||
|
||||
:::score-factor fa-circle green +2 points
|
||||
**Statut en ligne**
|
||||
Le host répond aux requêtes réseau
|
||||
:::
|
||||
|
||||
:::score-factor fa-check-circle blue +1 point
|
||||
**Bootstrap Ansible OK**
|
||||
SSH et prérequis Ansible configurés
|
||||
:::
|
||||
|
||||
:::score-factor fa-clock purple +2 points
|
||||
**Vérifié récemment (<1h)**
|
||||
Dernière vérification il y a moins d'une heure
|
||||
:::
|
||||
|
||||
:::score-factor fa-clock yellow +1 point
|
||||
**Vérifié aujourd'hui**
|
||||
Dernière vérification dans les 24 dernières heures
|
||||
:::
|
||||
|
||||
> **Astuce:** Exécutez régulièrement un `Health Check` pour maintenir un score de santé élevé.
|
||||
|
||||
### Statuts Bootstrap Ansible
|
||||
|
||||
:::status-badge green fa-check-circle Ansible Ready
|
||||
Le host est entièrement configuré pour Ansible. L'utilisateur automation existe, la clé SSH est déployée et sudo est configuré sans mot de passe.
|
||||
:::
|
||||
|
||||
:::status-badge yellow fa-exclamation-triangle Non configuré
|
||||
Le bootstrap n'a pas encore été exécuté sur ce host. Cliquez sur le bouton `Bootstrap` pour configurer l'accès Ansible.
|
||||
:::
|
||||
|
||||
### Que signifie "Jamais vérifié" ?
|
||||
|
||||
Ce message apparaît lorsqu'aucun Health Check n'a été exécuté sur le host depuis son ajout. Le système ne peut pas déterminer l'état réel du serveur. Lancez un Health Check pour mettre à jour le statut et obtenir un score de santé précis.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture de la Solution {#help-architecture}
|
||||
|
||||
### Stack Technologique
|
||||
|
||||
- **Backend:** FastAPI (Python) - API REST haute performance {icon:fa-server color:green}
|
||||
- **Automation:** Ansible - Gestion de configuration {icon:fa-cogs color:orange}
|
||||
- **Frontend:** HTML/CSS/JS avec TailwindCSS {icon:fa-desktop color:blue}
|
||||
- **Déploiement:** Docker & Docker Compose {icon:fab fa-docker color:cyan}
|
||||
- **Temps réel:** WebSocket pour les mises à jour live {icon:fa-plug color:yellow}
|
||||
|
||||
### Structure des Fichiers
|
||||
|
||||
```
|
||||
homelab-automation/
|
||||
├── app/
|
||||
│ ├── routes/ # Routes API FastAPI
|
||||
│ ├── models/ # Modèles SQLAlchemy
|
||||
│ ├── schemas/ # Schémas Pydantic
|
||||
│ ├── services/ # Logique métier
|
||||
│ ├── index.html # Interface web
|
||||
│ └── main.js # Logique frontend
|
||||
├── ansible/
|
||||
│ ├── inventory/
|
||||
│ │ ├── hosts.yml # Inventaire des hosts
|
||||
│ │ └── group_vars/ # Variables par groupe
|
||||
│ └── playbooks/ # Playbooks Ansible
|
||||
├── alembic/ # Migrations de base de données
|
||||
├── data/ # Base de données SQLite
|
||||
├── tasks_logs/ # Logs des tâches
|
||||
├── docker-compose.yml
|
||||
└── Dockerfile
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ Fonctionnalités Détaillées par Section {#help-features}
|
||||
|
||||
:::accordion fa-tachometer-alt purple Dashboard
|
||||
Vue d'ensemble centralisée de votre infrastructure homelab.
|
||||
|
||||
- **Métriques en temps réel:** État des hosts (Online/Offline), statistiques des tâches (Succès/Échec).
|
||||
- **Actions Rapides:** Accès immédiat aux opérations courantes (Mise à jour globale, Health Check général).
|
||||
- **Aperçu des Hosts:** Liste condensée avec indicateurs de statut et OS pour une surveillance rapide.
|
||||
- **Notifications:** Alertes visuelles sur les dernières activités importantes.
|
||||
:::
|
||||
|
||||
:::accordion fa-server blue Hosts
|
||||
Gestion complète du cycle de vie de vos serveurs.
|
||||
|
||||
- **Inventaire:** Ajout, modification et suppression de hosts avec détection d'OS.
|
||||
- **Bootstrap Ansible:** Préparation automatique des serveurs (User, Clés SSH, Sudo).
|
||||
- **Indicateurs de Santé:** Score de santé détaillé basé sur la connectivité et la configuration.
|
||||
- **Actions Individuelles:** Exécution de playbooks spécifiques (Upgrade, Backup, Reboot) sur un host.
|
||||
- **Détails Avancés:** Vue détaillée avec historique des tâches et logs spécifiques au host.
|
||||
:::
|
||||
|
||||
:::accordion fa-book pink Playbooks
|
||||
Bibliothèque et exécution de playbooks Ansible personnalisés.
|
||||
|
||||
- **Catalogue:** Liste de tous les playbooks disponibles dans votre répertoire.
|
||||
- **Exécution Ciblée:** Lancement de playbooks sur des hosts spécifiques ou des groupes.
|
||||
- **Logs en Direct:** Suivi temps réel de l'exécution Ansible (console output).
|
||||
- **Historique:** Accès rapide aux résultats des exécutions précédentes.
|
||||
:::
|
||||
|
||||
:::accordion fa-tasks green Tasks
|
||||
Traçabilité complète de toutes les opérations d'automatisation.
|
||||
|
||||
- **Suivi d'État:** Visualisation instantanée (En cours, Succès, Échec).
|
||||
- **Filtrage Avancé:** Recherche par statut, par date ou par type d'action.
|
||||
- **Logs Détaillés:** Accès aux sorties standard et d'erreur pour le débogage.
|
||||
- **Auto-refresh:** Mise à jour automatique des tâches en cours d'exécution.
|
||||
:::
|
||||
|
||||
:::accordion fa-calendar-alt indigo Schedules
|
||||
Planification automatisée des tâches récurrentes.
|
||||
|
||||
- **Planification Cron:** Configuration flexible de la fréquence d'exécution.
|
||||
- **Tâches Récurrentes:** Backups quotidiens, Mises à jour hebdomadaires, Health Checks horaires.
|
||||
- **Ciblage:** Définition des hosts ou groupes cibles pour chaque planification.
|
||||
- **Gestion:** Activation, désactivation ou modification des planifications existantes.
|
||||
:::
|
||||
|
||||
:::accordion fa-file-alt orange Logs
|
||||
Journal technique des événements système.
|
||||
|
||||
- **Streaming WebSocket:** Arrivée des logs en temps réel sans rechargement de page.
|
||||
- **Niveaux de Log:** Distinction claire entre Info, Warning et Error.
|
||||
- **Export:** Possibilité de télécharger les logs pour analyse externe.
|
||||
- **Rétention:** Gestion de l'historique et nettoyage des logs anciens.
|
||||
:::
|
||||
|
||||
:::accordion fa-bell red Alertes
|
||||
Centre de messages pour les événements importants.
|
||||
|
||||
- **Suivi:** Consultez les alertes récentes (succès/échec, changements d'état).
|
||||
- **Lecture:** Les alertes peuvent être marquées comme lues pour garder une boîte de réception propre.
|
||||
- **Notifications:** Certaines alertes peuvent déclencher des notifications ntfy (si activé).
|
||||
:::
|
||||
|
||||
:::accordion fa-cog cyan Configuration
|
||||
Paramètres de l'application et intégrations.
|
||||
|
||||
- **Paramètres applicatifs:** Options persistées (ex: collecte des métriques).
|
||||
- **Notifications:** Configuration et test du service ntfy.
|
||||
- **Sécurité:** Gestion du compte utilisateur (mot de passe) via l'écran utilisateur.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 🔔 Système de Notifications (ntfy) {#help-notifications}
|
||||
|
||||
Restez informé de l'état de votre infrastructure grâce au système de notifications intégré basé sur **ntfy**.
|
||||
|
||||
### Canaux & Configuration
|
||||
|
||||
Les notifications sont envoyées via le service ntfy, permettant de recevoir des alertes push sur mobile et desktop.
|
||||
|
||||
- **Push Mobile:** Via l'application ntfy (Android/iOS).
|
||||
- **Web Push:** Notifications navigateur sur desktop.
|
||||
- **Priorité:** Gestion des niveaux d'urgence (Low à High).
|
||||
|
||||
### Types d'Alertes
|
||||
|
||||
Vous recevez des notifications pour les événements critiques :
|
||||
|
||||
- ✅ Succès des Backups
|
||||
- ❌ Échecs de Tâches
|
||||
- ⚠️ Changements de Santé Host
|
||||
- 🛠️ Fin de Bootstrap
|
||||
|
||||
---
|
||||
|
||||
## 📖 Playbooks Ansible Disponibles {#help-playbooks}
|
||||
|
||||
:::playbook fa-tools yellow bootstrap-host.yml
|
||||
Configure un nouveau host pour Ansible: création utilisateur, clé SSH, sudo sans mot de passe.
|
||||
**Requis avant toute autre opération**
|
||||
:::
|
||||
|
||||
:::playbook fa-heartbeat green health-check.yml
|
||||
Vérifie l'état de santé: CPU, RAM, disque, services critiques.
|
||||
**Exécution rapide, non destructif**
|
||||
:::
|
||||
|
||||
:::playbook fa-arrow-up blue system-upgrade.yml
|
||||
Met à jour tous les paquets système (apt/yum/dnf selon l'OS).
|
||||
**Peut nécessiter un redémarrage**
|
||||
:::
|
||||
|
||||
:::playbook fa-save cyan backup-config.yml
|
||||
Sauvegarde les fichiers de configuration importants (/etc, configs apps).
|
||||
**Stockage local ou distant**
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 🔗 Référence API {#help-api}
|
||||
|
||||
L'API REST est accessible sur le port configuré. Authentification via header `Authorization: Bearer <token>`.
|
||||
|
||||
| Endpoint | Méthode | Description |
|
||||
|----------|---------|-------------|
|
||||
| `/api/hosts` | GET | Liste tous les hosts |
|
||||
| `/api/hosts` | POST | Ajoute un nouveau host |
|
||||
| `/api/hosts/{id}` | PUT | Modifie un host existant |
|
||||
| `/api/hosts/{id}` | DELETE | Supprime un host |
|
||||
| `/api/tasks/logs` | GET | Récupère les logs de tâches |
|
||||
| `/api/ansible/playbooks` | GET | Liste les playbooks disponibles |
|
||||
| `/api/ansible/execute` | POST | Exécute un playbook |
|
||||
| `/api/schedules` | GET | Liste les planifications |
|
||||
| `/api/schedules` | POST | Crée une planification |
|
||||
| `/api/metrics` | GET | Métriques du dashboard |
|
||||
| `/api/auth/login` | POST | Authentification utilisateur |
|
||||
| `/api/auth/me` | GET | Informations utilisateur courant |
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ Dépannage {#help-troubleshooting}
|
||||
|
||||
:::troubleshoot Le bootstrap échoue avec "Permission denied"
|
||||
**Cause:** Les identifiants SSH fournis sont incorrects ou l'utilisateur n'a pas les droits sudo.
|
||||
|
||||
**Solution:** Vérifiez le nom d'utilisateur et mot de passe. Assurez-vous que l'utilisateur peut exécuter `sudo` sur le host cible.
|
||||
:::
|
||||
|
||||
:::troubleshoot Les hosts apparaissent "offline" alors qu'ils sont accessibles
|
||||
**Cause:** Le health check n'a pas été exécuté ou la clé SSH n'est pas configurée.
|
||||
|
||||
**Solution:** Exécutez le bootstrap si ce n'est pas fait, puis lancez un Health Check.
|
||||
:::
|
||||
|
||||
:::troubleshoot Les tâches restent bloquées "En cours"
|
||||
**Cause:** Le processus Ansible peut être bloqué ou le host ne répond plus.
|
||||
|
||||
**Solution:** Vérifiez la connectivité réseau. Consultez les logs système pour plus de détails. Redémarrez le conteneur Docker si nécessaire.
|
||||
:::
|
||||
|
||||
:::troubleshoot L'interface ne se met pas à jour en temps réel
|
||||
**Cause:** La connexion WebSocket est interrompue.
|
||||
|
||||
**Solution:** Rafraîchissez la page. Vérifiez que le port WebSocket n'est pas bloqué par un firewall ou proxy.
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## ✨ Raccourcis & Astuces {#help-shortcuts}
|
||||
|
||||
### Navigation
|
||||
|
||||
- Cliquez sur le logo pour revenir au Dashboard
|
||||
- Utilisez les onglets du menu pour naviguer
|
||||
- Le thème clair/sombre est persistant
|
||||
|
||||
### Productivité
|
||||
|
||||
- Filtrez les hosts par groupe pour des actions groupées
|
||||
- Utilisez les filtres de date pour retrouver des tâches
|
||||
- Exportez les logs avant de les effacer
|
||||
|
||||
---
|
||||
|
||||
*Documentation générée par Homelab Automation Dashboard v1.0*
|
||||
Reference in New Issue
Block a user