Bruno Charest 21bee026ff first commit

2025-12-04 09:04:42 -05:00

12 KiB

Raw Blame History

Homelab Automation Dashboard

Une application moderne et professionnelle pour la gestion automatisée d'homelab, avec une interface utilisateur élégante et une API REST puissante.

✨ Fonctionnalités

Interface Utilisateur

Design Moderne : Interface élégante avec thème sombre et animations fluides
Tableau de Bord Temps Réel : Métriques et statistiques en direct
Gestion des Hôtes : Ajout, suppression et surveillance des serveurs
Gestion des Tâches : Création et suivi des tâches automatisées
Logs Système : Journalisation complète avec filtrage
WebSocket : Mises à jour en temps réel sans rechargement
Animations : Effets visuels professionnels avec Anime.js

API REST

Endpoints Complets : Gestion complète des hôtes, tâches et logs
Validation Pydantic : Validation automatique des données
WebSocket Support : Communication temps réel
Authentification API : Sécurité renforcée avec clés API
Documentation Interactive : Swagger UI et ReDoc
CORS Support : Compatible avec les applications web modernes

Intégration Ansible

Exécution de Playbooks : Lancer des playbooks Ansible depuis le dashboard
Inventaire Dynamique : Lecture automatique de l'inventaire Ansible
Actions Rapides : Upgrade, Reboot, Health-check, Backup en un clic
Groupes Ansible : Sélection des cibles par groupe (proxmox, lab, prod, etc.)

🛠️ Technologies Utilisées

Frontend

HTML5 & CSS3 : Structure et styles modernes
Tailwind CSS : Framework CSS utilitaire
Anime.js : Bibliothèque d'animations
Font Awesome : Icônes professionnelles
Google Fonts (Inter) : Typographie moderne

Backend

FastAPI : Framework web Python moderne et rapide
Pydantic : Validation de données
WebSockets : Communication temps réel
Uvicorn : Serveur ASGI performant

📁 Structure du Projet

homelab-automation-api-v2/
├── app/
│   ├── app_optimized.py    # Backend FastAPI avec intégration Ansible
│   ├── index.html          # Interface principale du dashboard
│   ├── main.js             # Logique JavaScript (appels API)
│   └── requirements.txt    # Dépendances Python
├── ansible/
│   ├── ansible.cfg         # Configuration Ansible
│   ├── inventory/
│   │   └── hosts.yml       # Inventaire des hôtes
│   ├── group_vars/
│   │   └── homelab.yml     # Variables de groupe
│   └── playbooks/
│       ├── vm-upgrade.yml      # Mise à jour des systèmes
│       ├── vm-reboot.yml       # Redémarrage des hôtes
│       ├── health-check.yml    # Vérification de santé
│       └── backup-config.yml   # Sauvegarde de configuration
└── README.md               # Documentation

🚀 Installation et Lancement

Prérequis

Python 3.10+ (testé avec Python 3.14)
Ansible (pour l'exécution des playbooks)
Navigateur moderne (Chrome, Firefox, Safari, Edge)

Installation d'Ansible (optionnel mais recommandé)

# Sur Debian/Ubuntu
sudo apt install ansible

# Sur Windows (via pip)
pip install ansible

# Sur macOS
brew install ansible

Installation

Cloner le projet

git clone <url-du-repo>
cd homelab-automation-api-v2/app

Installer les dépendances Python
```
pip install -r requirements.txt
```

Lancer le serveur backend (recommandé)

python -m uvicorn app_optimized:app --host 0.0.0.0 --port 8000 --reload

Ou directement via le script Python :

python app_optimized.py

Ouvrir le dashboard frontend complet (interface de l'image 1)

Naviguez vers :
- http://localhost:8000/ui → Dashboard Homelab (frontend HTML/JS)
Accéder à la page API (interface de l'image 2)

Naviguez vers :
- http://localhost:8000 → Page d'accueil API avec liens vers la documentation

📖 Utilisation

Interface Web

Tableau de Bord : Vue d'ensemble des métriques système
Gestion des Hôtes :
- Ajouter de nouveaux hôtes avec le bouton "Ajouter Host"
- Surveiller l'état des hôtes en temps réel
- Exécuter des actions (connexion, mise à jour, redémarrage)
Gestion des Tâches :
- Créer des tâches d'automatisation
- Suivre la progression en temps réel
- Voir les détails et les logs
Logs Système : Consulter l'historique des événements

API REST

Authentification

Toutes les requêtes API nécessitent une clé API dans le header X-API-Key:

curl -H "X-API-Key: dev-key-12345" http://localhost:8000/api/hosts

Endpoints Principaux

Hôtes

GET /api/hosts - Liste tous les hôtes
POST /api/hosts - Crée un nouvel hôte
GET /api/hosts/{id} - Récupère un hôte spécifique
DELETE /api/hosts/{id} - Supprime un hôte

Tâches

GET /api/tasks - Liste toutes les tâches
POST /api/tasks - Crée une nouvelle tâche
GET /api/tasks/{id} - Récupère une tâche spécifique
DELETE /api/tasks/{id} - Supprime une tâche

Logs

GET /api/logs - Récupère les logs récents
POST /api/logs - Ajoute un nouveau log
DELETE /api/logs - Efface tous les logs

Métriques

GET /api/metrics - Métriques système
GET /api/health/{host} - Health check d'un hôte

WebSocket

WS /ws - Connexion WebSocket pour les mises à jour temps réel

Ansible (nouveaux endpoints)

GET /api/ansible/playbooks - Liste les playbooks disponibles
GET /api/ansible/inventory - Récupère l'inventaire Ansible (hôtes et groupes)
GET /api/ansible/groups - Liste les groupes Ansible
POST /api/ansible/execute - Exécute un playbook directement
POST /api/ansible/adhoc - Exécute une commande ad-hoc sur les hôtes
POST /api/ansible/bootstrap - Bootstrap un hôte pour Ansible (crée user, SSH, sudo, Python)
GET /api/ansible/ssh-config - Diagnostic de la configuration SSH

Exemples d'utilisation Ansible

Lister les playbooks disponibles :

curl -H "X-API-Key: dev-key-12345" http://localhost:8000/api/ansible/playbooks

Voir l'inventaire Ansible :

curl -H "X-API-Key: dev-key-12345" http://localhost:8000/api/ansible/inventory

Exécuter un playbook (ex: mise à jour sur le groupe "lab") :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{"playbook": "vm-upgrade.yml", "target": "lab"}' \
  http://localhost:8000/api/ansible/execute

Créer une tâche Ansible via l'API tasks :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{"action": "upgrade", "group": "proxmox"}' \
  http://localhost:8000/api/tasks

Exécuter une commande ad-hoc :

# Vérifier l'espace disque sur tous les hôtes
curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{"target": "all", "command": "df -h /", "module": "shell"}' \
  http://localhost:8000/api/ansible/adhoc

# Redémarrer un service avec sudo
curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{"target": "web-servers", "command": "systemctl restart nginx", "become": true}' \
  http://localhost:8000/api/ansible/adhoc

Documentation API

Swagger UI : http://localhost:8000/api/docs
ReDoc : http://localhost:8000/api/redoc

🎨 Personnalisation

Thèmes

L'application supporte les thèmes clair et sombre. Utilisez le bouton en haut à droite pour basculer.

Couleurs

Les couleurs principales peuvent être modifiées dans les variables CSS :

:root {
    --primary-bg: #0a0a0a;
    --accent-color: #7c3aed;
    --success-color: #10b981;
    --error-color: #ef4444;
}

Animations

Les animations sont gérées par Anime.js dans main.js. Vous pouvez ajuster :

La durée des animations
Les effets de transition
Les comportements au scroll

🔧 Configuration

Variables d'Environnement

Créez un fichier .env pour configurer l'application :

API_KEY=votre-cle-api-secrete
SSH_REMOTE_USER=automation
LOGS_DIR=/var/log/homelab
ANSIBLE_DIR=/etc/ansible

Base de Données

Par défaut, l'application utilise une base de données en mémoire. Pour une utilisation en production, configurez PostgreSQL ou SQLite en modifiant la classe InMemoryDB.

🚀 Déploiement

Production

Configuration de la base de données

# Remplacer InMemoryDB par une vraie base de données

Sécurité
- Utilisez une clé API forte
- Activez HTTPS
- Configurez les pare-feu
- Limitez les origines CORS
Performance
- Utilisez un serveur de production (Gunicorn)
- Configurez Redis pour le cache
- Activez la compression

Docker

Le projet inclut un Dockerfile et docker-compose.yml prêts à l'emploi avec Ansible intégré.

Démarrage rapide avec Docker Compose

# 1. Copier le fichier d'exemple d'environnement
cp .env.example .env

# 2. Éditer .env pour configurer vos clés SSH
nano .env

# 3. Lancer le container
docker-compose up -d

# 4. Accéder au dashboard
# http://localhost:8000/ui

Configuration des clés SSH

Par défaut, docker-compose monte votre répertoire ~/.ssh en lecture seule. Assurez-vous que :

Votre clé privée SSH existe : ~/.ssh/id_rsa
Votre clé publique existe : ~/.ssh/id_rsa.pub

Ou spécifiez un répertoire différent dans .env :

SSH_KEY_DIR=/chemin/vers/vos/cles/ssh

Variables d'environnement

Variable	Description	Défaut
`API_KEY`	Clé API pour l'authentification	`dev-key-12345`
`SSH_USER`	Utilisateur SSH pour Ansible	`automation`
`SSH_KEY_DIR`	Répertoire des clés SSH sur l'hôte	`~/.ssh`
`SSH_KEY_PATH`	Chemin de la clé privée dans le container	`/app/ssh_keys/id_rsa`

Construction manuelle de l'image

# Construire l'image
docker build -t homelab-dashboard .

# Exécuter le container
docker run -d \
  -p 8000:8000 \
  -v ~/.ssh:/app/ssh_keys:ro \
  -v ./ansible/inventory:/ansible/inventory:ro \
  -e API_KEY=votre-cle-api-secrete \
  --name homelab-dashboard \
  homelab-dashboard

# se connecter au container
docker exec -it homelab-dashboard /bin/bash

🔧 Bootstrap SSH

Le dashboard inclut une fonctionnalité de Bootstrap pour préparer automatiquement un hôte à recevoir des commandes Ansible.

Ce que fait le Bootstrap

Crée l'utilisateur d'automatisation (par défaut: automation)
Configure l'authentification SSH par clé (copie votre clé publique)
Installe et configure sudo sans mot de passe pour cet utilisateur
Installe Python3 (requis par Ansible)
Vérifie la connexion SSH par clé après configuration

Systèmes supportés

Debian/Ubuntu (apt)
Alpine Linux (apk)
FreeBSD (pkg)

Utilisation via l'interface

Cliquez sur le bouton Bootstrap (jaune) sur la carte d'un hôte
Entrez le mot de passe root de l'hôte distant
Optionnel : modifiez le nom de l'utilisateur d'automatisation
Cliquez sur Lancer le Bootstrap

Utilisation via l'API

curl -X POST http://localhost:8000/api/ansible/bootstrap \
  -H "X-API-Key: dev-key-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "192.168.1.100",
    "root_password": "votre-mot-de-passe-root",
    "automation_user": "automation"
  }'

Prérequis

sshpass doit être installé sur la machine qui exécute le dashboard
L'hôte cible doit accepter les connexions SSH avec mot de passe (pour la configuration initiale)
Le compte root doit être accessible via SSH

# Installation de sshpass
# Debian/Ubuntu
apt install sshpass

# Alpine
apk add sshpass

# macOS
brew install hudochenkov/sshpass/sshpass

🤝 Contribution

Les contributions sont les bienvenues ! Veuillez :

Fork le projet
Créer une branche pour votre fonctionnalité
Commit vos changements
Push vers la branche
Ouvrir une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

🆘 Support

Pour toute question ou problème :

Consultez la documentation
Vérifiez les logs du serveur
Ouvrez une issue sur GitHub
Contactez l'équipe de développement

Développé avec ❤️ pour la communauté homelab

12 KiB Raw Blame History

Homelab Automation Dashboard

✨ Fonctionnalités

Interface Utilisateur

API REST

Intégration Ansible

🛠️ Technologies Utilisées

Frontend

Backend

📁 Structure du Projet

🚀 Installation et Lancement

Prérequis

Installation d'Ansible (optionnel mais recommandé)

Installation

📖 Utilisation

Interface Web

API REST

Authentification

Endpoints Principaux

Exemples d'utilisation Ansible

Documentation API

🎨 Personnalisation

Thèmes

Couleurs

Animations

🔧 Configuration

Variables d'Environnement

Base de Données

🚀 Déploiement

Production

Docker

Démarrage rapide avec Docker Compose

Configuration des clés SSH

Variables d'environnement

Construction manuelle de l'image

🔧 Bootstrap SSH

Ce que fait le Bootstrap

Systèmes supportés

Utilisation via l'interface

Utilisation via l'API

Prérequis

🤝 Contribution

📄 Licence

🆘 Support

12 KiB

Raw Blame History