Projets/homelab_automation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
homelab_automation/app/static/help.md

11 KiB
Raw Blame History

🚀 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

:::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

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

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

:::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)

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

:::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

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

:::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

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