homelab_automation/README.md

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

### 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é)
```bash
# Sur Debian/Ubuntu
sudo apt install ansible

# Sur Windows (via pip)
pip install ansible

# Sur macOS
brew install ansible
```

### Installation

1. **Cloner le projet**
   ```bash
   git clone <url-du-repo>
   cd homelab-automation-api-v2/app
   ```

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

3. **Lancer le serveur backend (recommandé)**
   ```bash
   python -m uvicorn app_optimized:app --host 0.0.0.0 --port 8000 --reload
   ```

   Ou directement via le script Python :
   ```bash
   python app_optimized.py
   ```

4. **Ouvrir le dashboard frontend complet** (interface de l'image 1)
   
   Naviguez vers :
   - `http://localhost:8000/ui` → Dashboard Homelab (frontend HTML/JS)

5. **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

1. **Tableau de Bord** : Vue d'ensemble des métriques système
2. **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)
3. **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
4. **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`:
```bash
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 :**
```bash
curl -H "X-API-Key: dev-key-12345" http://localhost:8000/api/ansible/playbooks
```

**Voir l'inventaire Ansible :**
```bash
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") :**
```bash
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 :**
```bash
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 :**
```bash
# 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 :**
```bash
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) :**
```bash
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 :**
```bash
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 :**
```bash
curl -X POST -H "X-API-Key: dev-key-12345" \
  http://localhost:8000/api/schedules/{schedule_id}/run
```

**Voir l'historique des exécutions :**
```bash
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 :**
```bash
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 :**
```bash
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 :**
```bash
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 :
```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 :

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

```bash
# 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 :

```bash
# Appliquer les migrations
alembic upgrade head

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

## 🚀 Déploiement

### Production

1. **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`

2. **Sécurité**
   - Utilisez une clé API forte
   - Activez HTTPS
   - Configurez les pare-feu
   - Limitez les origines CORS

3. **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

```bash
# 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 :

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

Ou spécifiez un répertoire différent dans `.env` :
```bash
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

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

```bash
# 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
```

```bash
# 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

1. **Crée l'utilisateur d'automatisation** (par défaut: `automation`)
2. **Configure l'authentification SSH par clé** (copie votre clé publique)
3. **Installe et configure sudo** sans mot de passe pour cet utilisateur
4. **Installe Python3** (requis par Ansible)
5. **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

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

### Utilisation via l'API

```bash
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

```bash
# 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](https://ntfy.sh/), un service de notifications open-source.

### Configuration

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

2. **Variables d'environnement** : Ajoutez dans votre `.env` :
   ```env
   NTFY_BASE_URL=http://raspi.8gb.home:8150
   NTFY_DEFAULT_TOPIC=homelab-events
   NTFY_ENABLED=true
   ```

3. **Authentification** (optionnel) :
   ```env
   # 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

1. **Application mobile** : Installez l'app ntfy ([Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy), [iOS](https://apps.apple.com/app/ntfy/id1625396347))
2. **Abonnez-vous** aux topics souhaités (ex: `homelab-events`)
3. **Web** : Accédez à `http://votre-serveur-ntfy/homelab-events` dans un navigateur

### Désactiver les notifications

- **Temporairement via API** :
  ```bash
  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 :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité
3. Commit vos changements
4. Push vers la branche
5. 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 :

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

---

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