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

Planificateur (Scheduler)

Planification de Playbooks : Exécution automatique des playbooks (unique ou récurrente)
Interface Multi-étapes : Création intuitive de schedules en 3 étapes
Vue Liste/Calendrier : Visualisation des schedules planifiés
Expression Cron : Support des expressions cron personnalisées
Historique d'exécution : Traçabilité complète de chaque run
Intégration Dashboard : Widget des prochaines exécutions

Notifications Push (ntfy)

Intégration ntfy : Notifications push vers serveur ntfy self-hosted ou ntfy.sh
Non-bloquant : Les notifications n'impactent jamais les opérations principales
Templates prédéfinis : Backup, Bootstrap, Health checks, Tâches
Configurable : Activation/désactivation, topics personnalisés, authentification
API complète : Endpoints pour tester et envoyer des notifications personnalisées

🛠️ 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
APScheduler : Planification de tâches en arrière-plan
Croniter : Parsing d'expressions cron

📁 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
│   ├── .host_status.json   # Cache JSON de l'état des hôtes
│   ├── 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
├── tasks_logs/
│   ├── .bootstrap_status.json  # État du bootstrap Ansible/SSH par hôte
│   ├── .schedule_runs.json     # Historique des exécutions de schedules
│   └── 2025/
│       └── 12/
│           └── *.json          # Logs détaillés des tâches/schedules par date
├── test_schedule.json      # Exemple de définition de schedule
└── README.md               # Documentation

Fichiers JSON requis

Les fichiers JSON suivants sont utilisés par l'application pour stocker l'état et l'historique des opérations :

ansible/.host_status.json
- Contient l'état courant des hôtes connus (reachability, dernier health-check, etc.).
- Utilisé par l'API et le dashboard pour afficher rapidement le statut des machines sans relancer un scan complet.
tasks_logs/.bootstrap_status.json
- Mémorise l'état du bootstrap Ansible/SSH par hôte (succès, échec, dernier message).
- Permet au dashboard d'indiquer si un hôte est prêt pour l'exécution de playbooks.
tasks_logs/.schedule_runs.json
- Journalise les exécutions des schedules (id du schedule, heure de run, résultat, durée, message d'erreur éventuel).
- Sert de source de vérité pour l'historique affiché dans l'interface Planificateur.
tasks_logs/<année>/<mois>/*.json
- Fichiers horodatés contenant les logs détaillés de chaque exécution de tâche/schedule.
- Permettent de tracer finement ce qui s'est passé pour chaque run (playbook lancé, cible, sortie Ansible, statut).
test_schedule.json
- Exemple de définition de schedule utilisé pour les tests et la validation de l'API de planification.
- Peut servir de modèle pour comprendre la structure JSON attendue lors de la création de nouveaux schedules.

🚀 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

Planificateur (Schedules)

GET /api/schedules - Liste tous les schedules
POST /api/schedules - Crée un nouveau schedule
GET /api/schedules/{id} - Récupère un schedule spécifique
PUT /api/schedules/{id} - Met à jour un schedule
DELETE /api/schedules/{id} - Supprime un schedule
POST /api/schedules/{id}/run - Exécution forcée immédiate
POST /api/schedules/{id}/pause - Met en pause un schedule
POST /api/schedules/{id}/resume - Reprend un schedule
GET /api/schedules/{id}/runs - Historique des exécutions
GET /api/schedules/stats - Statistiques globales
POST /api/schedules/validate-cron - Valide une expression cron

Notifications (ntfy)

GET /api/notifications/config - Configuration actuelle des notifications
POST /api/notifications/test - Envoie une notification de test
POST /api/notifications/send - Envoie une notification personnalisée
POST /api/notifications/toggle - Active/désactive les notifications

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

Exemples d'utilisation du Planificateur

Créer un schedule quotidien :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{
    "name": "Backup quotidien",
    "playbook": "backup-config.yml",
    "target": "all",
    "schedule_type": "recurring",
    "recurrence": {"type": "daily", "time": "02:00"},
    "tags": ["Backup", "Production"]
  }' \
  http://localhost:8000/api/schedules

Créer un schedule hebdomadaire (lundi et vendredi) :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{
    "name": "Health check bi-hebdo",
    "playbook": "health-check.yml",
    "target": "proxmox",
    "schedule_type": "recurring",
    "recurrence": {"type": "weekly", "time": "08:00", "days": [1, 5]}
  }' \
  http://localhost:8000/api/schedules

Créer un schedule avec expression cron :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{
    "name": "Maintenance mensuelle",
    "playbook": "vm-upgrade.yml",
    "target": "lab",
    "schedule_type": "recurring",
    "recurrence": {"type": "custom", "cron_expression": "0 3 1 * *"}
  }' \
  http://localhost:8000/api/schedules

Lancer un schedule immédiatement :

curl -X POST -H "X-API-Key: dev-key-12345" \
  http://localhost:8000/api/schedules/{schedule_id}/run

Voir l'historique des exécutions :

curl -H "X-API-Key: dev-key-12345" \
  http://localhost:8000/api/schedules/{schedule_id}/runs

Exemples d'utilisation des Notifications

Tester la configuration ntfy :

curl -X POST -H "X-API-Key: dev-key-12345" \
  "http://localhost:8000/api/notifications/test?message=Hello%20from%20Homelab"

Envoyer une notification personnalisée :

curl -X POST -H "X-API-Key: dev-key-12345" -H "Content-Type: application/json" \
  -d '{
    "topic": "homelab-alerts",
    "message": "Serveur redémarré avec succès",
    "title": "🔄 Reboot terminé",
    "priority": 3,
    "tags": ["white_check_mark", "computer"]
  }' \
  http://localhost:8000/api/notifications/send

Désactiver temporairement les notifications :

curl -X POST -H "X-API-Key: dev-key-12345" \
  "http://localhost:8000/api/notifications/toggle?enabled=false"

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

L'application utilise SQLite avec SQLAlchemy 2.x async pour le stockage persistant des données (hôtes, tâches, schedules, logs). La base est créée automatiquement au démarrage dans data/homelab.db.

Migration depuis les fichiers JSON

Si vous migrez depuis une version antérieure utilisant des fichiers JSON :

# 1. Installer les nouvelles dépendances
pip install -r app/requirements.txt

# 2. Exécuter le script de migration
python migrate_json_to_sqlite.py

Le script :

Importe les données depuis ansible/.host_status.json, tasks_logs/.bootstrap_status.json, etc.
Crée des sauvegardes .bak des fichiers JSON originaux
Génère un rapport de migration

Structure de la base de données

data/homelab.db
├── hosts              # Inventaire des hôtes
├── bootstrap_status   # Statut bootstrap SSH par hôte
├── tasks              # Historique des tâches exécutées
├── schedules          # Planifications récurrentes
├── schedule_runs      # Historique des exécutions de schedules
└── logs               # Logs système

Migrations Alembic

Pour les évolutions de schéma :

# Appliquer les migrations
alembic upgrade head

# Créer une nouvelle migration
alembic revision --autogenerate -m "description"

🚀 Déploiement

Production

Configuration de la base de données
- Par défaut : SQLite dans data/homelab.db
- Variable d'environnement : DATABASE_URL=sqlite+aiosqlite:///./data/homelab.db
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`
`NTFY_BASE_URL`	URL du serveur ntfy	`http://localhost:8150`
`NTFY_DEFAULT_TOPIC`	Topic par défaut pour les notifications	`homelab-events`
`NTFY_ENABLED`	Activer/désactiver les notifications	`true`
`NTFY_TIMEOUT`	Timeout des requêtes HTTP (secondes)	`5`
`NTFY_USERNAME`	Nom d'utilisateur (auth Basic)	(vide)
`NTFY_PASSWORD`	Mot de passe (auth Basic)	(vide)
`NTFY_TOKEN`	Token Bearer (alternative à Basic)	(vide)

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

🔔 Notifications Push (ntfy)

L'application intègre un système de notifications push via ntfy, un service de notifications open-source.

Configuration

Serveur ntfy : Vous pouvez utiliser :
- Le service public : https://ntfy.sh
- Votre propre instance self-hosted (recommandé pour la vie privée)

Variables d'environnement : Ajoutez dans votre .env :

NTFY_BASE_URL=http://raspi.8gb.home:8150
NTFY_DEFAULT_TOPIC=homelab-events
NTFY_ENABLED=true

Authentification (optionnel) :

# Auth Basic
NTFY_USERNAME=votre-user
NTFY_PASSWORD=votre-password

# Ou Token Bearer
NTFY_TOKEN=tk_votre_token

Topics utilisés

Topic	Description
`homelab-events`	Notifications générales (topic par défaut)
`homelab-backup`	Résultats des backups (succès/échec)
`homelab-bootstrap`	Bootstrap des hôtes
`homelab-health`	Changements d'état des hôtes (up/down)
`homelab-schedules`	Exécutions des schedules planifiés

Événements notifiés automatiquement

Tâches Ansible : Succès ou échec de l'exécution
Bootstrap : Début, succès ou échec du bootstrap d'un hôte
Schedules : Résultat des exécutions planifiées
Health checks : Changement d'état d'un hôte (online → offline ou inverse)

Recevoir les notifications

Application mobile : Installez l'app ntfy (Android, iOS)
Abonnez-vous aux topics souhaités (ex: homelab-events)
Web : Accédez à http://votre-serveur-ntfy/homelab-events dans un navigateur

Désactiver les notifications

Temporairement via API :

curl -X POST -H "X-API-Key: dev-key-12345" \
  "http://localhost:8000/api/notifications/toggle?enabled=false"

Définitivement : Mettez NTFY_ENABLED=false dans .env

🤝 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