# 🚀 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} :::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. ::: --- ## ❤️‍🩹 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 `. | 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*