333 lines
12 KiB
Python
333 lines
12 KiB
Python
"""
|
|
Générateur de documentation Markdown pour l'aide Homelab Automation.
|
|
"""
|
|
|
|
from pathlib import Path
|
|
|
|
|
|
def build_help_markdown(html_path: Path = None, html_content: str = None) -> str:
|
|
"""Génère le contenu Markdown d'aide professionnel.
|
|
|
|
Args:
|
|
html_path: Non utilisé (conservé pour compatibilité)
|
|
html_content: Non utilisé (conservé pour compatibilité)
|
|
|
|
Returns:
|
|
Contenu Markdown formaté professionnellement
|
|
"""
|
|
return _get_professional_help_markdown()
|
|
|
|
|
|
def _get_professional_help_markdown() -> str:
|
|
"""Retourne la documentation d'aide complète et professionnelle."""
|
|
return """# Homelab Automation Dashboard
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
## Table des Matières
|
|
|
|
1. [Démarrage Rapide](#démarrage-rapide)
|
|
2. [Indicateurs de Santé des Hosts](#indicateurs-de-santé-des-hosts)
|
|
3. [Architecture de la Solution](#architecture-de-la-solution)
|
|
4. [Fonctionnalités par Section](#fonctionnalités-par-section)
|
|
5. [Système de Notifications](#système-de-notifications-ntfy)
|
|
6. [Playbooks Ansible Disponibles](#playbooks-ansible-disponibles)
|
|
7. [Référence API](#référence-api)
|
|
8. [Dépannage](#dépannage)
|
|
9. [Raccourcis et Astuces](#raccourcis-et-astuces)
|
|
|
|
---
|
|
|
|
## Démarrage Rapide
|
|
|
|
### Étape 1 : Ajouter vos Hosts
|
|
|
|
Commencez par ajouter vos serveurs dans la section **Hosts**. Chaque host nécessite :
|
|
- Un nom unique
|
|
- Une adresse IP
|
|
- Un système d'exploitation
|
|
|
|
### Étape 2 : Bootstrap Ansible
|
|
|
|
Exécutez le **Bootstrap** sur chaque host pour configurer :
|
|
- L'accès SSH avec clé publique
|
|
- L'utilisateur d'automatisation
|
|
- Les prérequis Ansible (Python, sudo)
|
|
|
|
### Étape 3 : Automatiser
|
|
|
|
Utilisez les **Actions Rapides** ou exécutez des playbooks personnalisés pour automatiser vos tâches récurrentes.
|
|
|
|
---
|
|
|
|
## Indicateurs de Santé des Hosts
|
|
|
|
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
|
|
|
|
| Niveau | Barres | Description |
|
|
|--------|--------|-------------|
|
|
| **Excellent** | 5 barres vertes | Host en ligne, bootstrap OK, vérifié récemment |
|
|
| **Bon** | 3-4 barres jaunes | Host fonctionnel mais certains aspects à améliorer |
|
|
| **Moyen** | 2 barres oranges | Attention requise - vérification recommandée |
|
|
| **Faible** | 1 barre rouge | Host hors ligne ou non configuré |
|
|
|
|
### Facteurs de Calcul du Score
|
|
|
|
| Facteur | Points | Description |
|
|
|---------|--------|-------------|
|
|
| Statut en ligne | +2 | Le host répond aux requêtes réseau |
|
|
| Bootstrap Ansible OK | +1 | SSH et prérequis Ansible configurés |
|
|
| Vérifié récemment (<1h) | +2 | Dernière vérification il y a moins d'une heure |
|
|
| Vérifié aujourd'hui | +1 | 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
|
|
|
|
- **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.
|
|
- **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
|
|
|
|
### Stack Technologique
|
|
|
|
| Composant | Technologie | Description |
|
|
|-----------|-------------|-------------|
|
|
| **Backend** | FastAPI (Python) | API REST haute performance |
|
|
| **Automation** | Ansible | Gestion de configuration |
|
|
| **Frontend** | HTML/CSS/JS + TailwindCSS | Interface web moderne |
|
|
| **Déploiement** | Docker & Docker Compose | Conteneurisation |
|
|
| **Temps réel** | WebSocket | Mises à jour live |
|
|
|
|
### 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 par Section
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
### 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é)
|
|
|
|
### 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)
|
|
|
|
Restez informé de l'état de votre infrastructure grâce au système de notifications intégré basé sur **ntfy**.
|
|
|
|
### Canaux et 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
|
|
|
|
### bootstrap-host.yml
|
|
|
|
Configure un nouveau host pour Ansible : création utilisateur, clé SSH, sudo sans mot de passe.
|
|
|
|
> **Note :** Requis avant toute autre opération
|
|
|
|
### health-check.yml
|
|
|
|
Vérifie l'état de santé : CPU, RAM, disque, services critiques.
|
|
|
|
> **Note :** Exécution rapide, non destructif
|
|
|
|
### system-upgrade.yml
|
|
|
|
Met à jour tous les paquets système (apt/yum/dnf selon l'OS).
|
|
|
|
> **Attention :** Peut nécessiter un redémarrage
|
|
|
|
### backup-config.yml
|
|
|
|
Sauvegarde les fichiers de configuration importants (/etc, configs apps).
|
|
|
|
> **Note :** Stockage local ou distant
|
|
|
|
---
|
|
|
|
## Référence 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
|
|
|
|
### 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.
|
|
|
|
### 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.
|
|
|
|
### 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.
|
|
|
|
### 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 et Astuces
|
|
|
|
### 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*
|
|
"""
|