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 JWT : Login user/password avec rôles et tokens Bearer
• Compatibilité API key (legacy) : Mode de transition pour les anciennes intégrations
• 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 de Python

# Sur Debian/Ubuntu
sudo apt install python3.12
sudo apt install python3-pip
sudo apt install python3.12-venv

# Sur Windows 
scoop install python

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

1. Cloner le projet

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

2. Installer les dépendances Python

   # Sous Windows avec WSL (Ubuntu)
   wsl -d Ubuntu
   
   # Aller à la racine du projet (côté WSL)
   cd /mnt/c/dev/git/python/homelab-automation-api-v2
   
   # Créer et activer un environnement virtuel Python
   python3 -m venv .venv
   source .venv/bin/activate
   
   # Installer les dépendances du backend
   pip install -r app/requirements.txt
   

3. Installer configurer SSH sur clients

   # Installer SSH et sshpass
   sudo apt install ssh
   sudo apt install sshpass
   
   # Modifier configuration SSH /etc/ssh/sshd_config
   PermitRootLogin yes
   PubkeyAuthentication yes
   
   # redémarrer le service SSH pour Debian
   sudo service ssh restart
   
   # redémarrer le service SSH pour Alpine Linux
   sudo 
   
   

4. Lancer le serveur backend (recommandé)

   # Depuis la racine du projet (homelab-automation-api-v2)
   cd homelab-automation-api-v2
   python -m uvicorn app.app_optimized:app --host 0.0.0.0 --port 8000 --reload
   

   Ou directement via le script Python (chemin module explicite) :

   python -m app.app_optimized
   

   ℹ️ Le module app_optimized se trouve dans le dossier app/, il doit donc être référencé en tant que app.app_optimized lorsque vous êtes à la racine du projet.

Utilisation d'un fichier .env et des scripts de démarrage

Pour éviter d'exporter manuellement les variables d'environnement (API, SSH, notifications, JWT, base de données, etc.), vous pouvez utiliser un fichier .env à la racine du projet et les scripts fournis :

1. Créer un fichier .env à partir de l'exemple Docker

   # Depuis la racine du projet
   cp docker/.env.example .env
   # Puis éditer .env avec vos valeurs (API_KEY, SSH_USER, NTFY_*, JWT_SECRET_KEY, etc.)
   

2. Démarrer en développement sous Linux/macOS

   Le script run_dev.sh charge automatiquement les variables du fichier .env puis lance uvicorn :

   chmod +x run_dev.sh
   ./run_dev.sh
   

3. Démarrer en développement sous Windows (PowerShell)

   Le script run_dev.ps1 lit également le fichier .env et définit les variables d'environnement pour la session avant de lancer uvicorn :

   # Depuis la racine du projet
   .\run_dev.ps1
   

   Ces scripts utilisent la même commande uvicorn sous-jacente :

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

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

L'application utilise désormais une authentification JWT moderne avec utilisateur/mot de passe et support des rôles.

• Mode recommandé (JWT)

  • Login avec POST /api/auth/login/json (ou /api/auth/login en form-data)
  • Récupération d'un access_token (JWT) à transmettre dans le header Authorization: Bearer <token>
  • Récupération des infos utilisateur avec GET /api/auth/me

• Mode legacy (API key)

  • Toujours possible via API_KEY et X-API-Key, mais désactivé dès qu'un utilisateur est créé.
  • À utiliser uniquement pour la transition depuis les anciennes versions.

# 1) Création du premier utilisateur admin (si aucune BD d'utilisateurs encore)
curl -X POST "http://localhost:8000/api/auth/setup" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "motdepasse-securise",
    "display_name": "Administrateur"
  }'

# 2) Login et récupération du token JWT
TOKEN=$(curl -s -X POST "http://localhost:8000/api/auth/login/json" \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "motdepasse-securise"}' | jq -r .access_token)

# 3) Utilisation du token pour appeler l'API
curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/hosts

🔐 Sécurité / bonnes pratiques JWT

• Clé secrète forte :
  • Définir JWT_SECRET_KEY dans .env avec une valeur longue et aléatoire (au moins 32+ caractères).
  • Ne jamais committer la vraie clé dans le dépôt Git.
• Durée de vie raisonnable :
  • Utiliser JWT_EXPIRE_MINUTES pour limiter la validité du token (ex: 60 à 240 min en prod, 1440 min en dev/démo).
  • Plus la durée est courte, plus l’impact d’un token volé est réduit.
• Stockage côté client :
  • Le frontend stocke le token dans localStorage pour simplifier l’intégration.
  • Sur un déploiement exposé sur Internet, envisager des cookies HTTPOnly + TLS obligatoire pour durcir la sécurité.
• Rotation de clé :
  • En cas de suspicion de fuite, changer JWT_SECRET_KEY et redémarrer l’API : tous les anciens tokens deviennent invalides.
  • Planifier un changement périodique de la clé (ex: tous les 6–12 mois) pour les environnements sensibles.
• Protection réseau :
  • Toujours exposer l’API derrière HTTPS (reverse proxy type Nginx/Traefik, certbot, etc.).
  • Restreindre les IP/autorisations au niveau du pare-feu si possible.

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 (avec JWT)

Dans les exemples suivants, on suppose que vous avez déjà un token JWT dans la variable shell $TOKEN.

Lister les playbooks disponibles :

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/ansible/playbooks

Voir l'inventaire Ansible :

curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/ansible/inventory

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

curl -X POST -H "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/schedules/{schedule_id}/run

Voir l'historique des exécutions :

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/schedules/{schedule_id}/runs

Exemples d'utilisation des Notifications

Tester la configuration ntfy :

curl -X POST -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/notifications/test?message=Hello%20from%20Homelab"

Envoyer une notification personnalisée :

curl -X POST -H "Authorization: Bearer $TOKEN" -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 "Authorization: Bearer $TOKEN" \
  "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

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

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

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

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

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

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 :

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

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

1. Application mobile : Installez l'app ntfy (Android, iOS)
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 :

  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