318 lines
11 KiB
Markdown
318 lines
11 KiB
Markdown
# 🚀 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*
|