🔎 Plugin Uptime Kuma pour Jeedom
Le plugin Uptime Kuma connecte Uptime Kuma a Jeedom. Il remonte en temps reel l'etat de tous vos moniteurs (sites web, API, serveurs, ports TCP, DNS, ping...) et vous permet d'exploiter ces informations dans vos scenarios.
💡 Pourquoi utiliser ce plugin ?
Supervision centralisee dans Jeedom
Plus besoin de jongler entre l'interface Uptime Kuma et Jeedom. Tous les moniteurs/sondes que vous souhaitez sont visibles directement dans le dashboard, avec des widgets dedies et un panel de synthese.
Notifications temps reel via webhooks
En complement du polling periodique, le plugin installe des webhooks dans Uptime Kuma pour recevoir instantanement les changements d'etat. Un service tombe ? Jeedom le sait immediatement.
Multi-sources
Vous avez plusieurs instances Uptime Kuma (production, labo, clients) ? Le plugin les gere toutes. Chaque instance est une Source, chaque check un Moniteur.
Exploitable dans les scenarios
Chaque moniteur expose des commandes info (statut, ping, message) directement utilisables dans les scenarios Jeedom pour declencher des alertes, des actions correctives ou des logs.
📊 En resume
| Fonctionnalite | Description |
|---|---|
| Monitoring | Statut UP/DOWN/PENDING/MAINTENANCE de chaque moniteur |
| Temps de reponse | Ping en millisecondes (historise) |
| Webhooks | Notifications instantanees depuis Uptime Kuma |
| Multi-sources | Plusieurs instances Uptime Kuma |
| Panel | Vue globale filtrable avec synthese |
| Scenarios | Commandes info exploitables dans les scenarios |
| Widgets | Templates dedies pour sources et moniteurs |
⚙️ Prerequis
- Jeedom 4.4 minimum
- Debian 11 a 13
- Une instance Uptime Kuma accessible depuis Jeedom (HTTP ou HTTPS)
- Un compte Uptime Kuma avec acces API (identifiant / mot de passe)
📥 Installation
1️⃣ Installer le plugin
Plugins > Gestion des plugins > Market > Uptime Kuma > Installer stable
Activer le plugin apres installation.
2️⃣ Installer les dependances
Les dependances s'installent automatiquement a l'activation. Elles comprennent :
- Un environnement virtuel Python (venv)
- La librairie
uptime-kuma-api2pour communiquer avec l'API d'Uptime Kuma
Verifier le statut OK dans la page de configuration du plugin.
3️⃣ Configurer et demarrer le demon
Dans la page Configuration du plugin :
| Parametre | Description | Defaut |
|---|---|---|
| Port socket interne | Port de communication entre Jeedom et le demon | 55210 |
| Frequence de polling | Intervalle en secondes entre chaque interrogation d'Uptime Kuma | 60 |
Demarrer le demon et verifier le statut OK.
Le demon interroge periodiquement toutes les sources configurees. Les webhooks completent ce mecanisme pour les notifications instantanees.
🔌 Ajouter une source Uptime Kuma
Une Source represente une instance Uptime Kuma.
Creer l'equipement source
- Aller dans Plugins > Monitoring > Uptime Kuma
- Cliquer Ajouter
- Nommer la source (ex: "Uptime Kuma Prod")
- Dans l'onglet Equipement, remplir :
| Champ | Description |
|---|---|
| URL | Adresse de l'instance Uptime Kuma (ex: https://status.mondomaine.fr) |
| Identifiant | Nom d'utilisateur Uptime Kuma (optionnel) |
| Mot de passe | Mot de passe (chiffre en base, jamais affiche) |
-
Cliquer Tester la connexion pour valider
-
Sauvegarder l'equipement
Synchroniser les moniteurs
Apres avoir sauvegarde la source :
- Cliquer Decouvrir les moniteurs pour voir la liste des moniteurs disponibles
- Selectionner ceux que vous souhaitez creer dans Jeedom
- Valider pour creer les equipements correspondants
La synchronisation cree les moniteurs manquants et met a jour les existants (nom, type, hostname, tags). Elle ne supprime jamais un moniteur — les moniteurs disparus d'Uptime Kuma sont marques comme orphelins et desactives.
📡 Commandes
Commandes d'une Source
| Commande | Type | Description |
|---|---|---|
| connection | info binaire | 1 = connecte a Uptime Kuma, 0 = deconnecte |
| monitor_count | info numerique | Nombre total de moniteurs |
| monitors_up | info numerique | Moniteurs en etat UP |
| monitors_down | info numerique | Moniteurs en etat DOWN |
| monitors_pending | info numerique | Moniteurs en etat PENDING |
| monitors_maintenance | info numerique | Moniteurs en MAINTENANCE |
| monitors_unavailable | info numerique | Moniteurs UNAVAILABLE (Jeedom ne peut joindre Uptime Kuma) |
| last_state_change | info string | Date/heure du dernier changement d'etat d'un moniteur |
Commandes d'un Moniteur
Commandes info
| Commande | Type | Description |
|---|---|---|
| status | binaire | 1 = UP, 0 = DOWN |
| status_code | numerique | Code brut : 0=DOWN, 1=UP, 2=PENDING, 3=MAINTENANCE, 4=UNAVAILABLE |
| status_text | string | Libelle lisible du statut |
| ping | numerique | Temps de reponse en ms (historise) |
| message | string | Dernier message de statut |
| last_check | string | Date/heure du dernier check |
Commandes action
| Commande | Description |
|---|---|
| refresh | Force un rafraichissement immediat via le demon |
| toggle_webhook | Active ou desactive le webhook pour ce moniteur |
🎨 Widgets
Widget Moniteur
Le widget moniteur affiche :
- Indicateur de statut colore (vert = UP, rouge = DOWN, orange = PENDING, bleu = MAINTENANCE, gris = UNAVAILABLE)
- Message du dernier check (tronque avec tooltip)
- Ping en millisecondes
- Dernier check (date/heure)
- Type de moniteur (HTTP, Ping, TCP, DNS...)
- Webhook avec bouton toggle pour activer/desactiver
Widget Source
Le widget source affiche :
- Etat de connexion (icone prise coloree)
- Nombre total de moniteurs (chiffre prominent)
- Repartition par statut : UP, DOWN, MAINTENANCE, PENDING, UNAVAILABLE avec pastilles colorees
- Dernier changement d'etat (date/heure du dernier moniteur ayant change de statut)
🎛️ Panel de synthese
Le panel offre une vue globale de tous les moniteurs, toutes sources confondues.
Cartes de synthese
En haut du panel, des cartes colorees affichent les compteurs globaux :
| Carte | Couleur | Contenu |
|---|---|---|
| Total | — | Nombre total de moniteurs |
| UP | Vert | Moniteurs en ligne |
| DOWN | Rouge | Moniteurs en panne |
| PENDING | Orange | Moniteurs en attente |
| MAINTENANCE | Bleu | Moniteurs en maintenance |
| UNAVAILABLE | Gris | Moniteurs injoignables |
| Connexion | — | Sources connectees / total |
Section Problemes
Sous les cartes, une section affiche tous les moniteurs non UP avec leur statut et leurs details. Cette section disparait si tout est UP.
Filtres
Le panel propose plusieurs criteres de filtrage combinables :
| Filtre | Description |
|---|---|
| Boutons de statut | ALL, DOWN, N/A, PENDING, MAINT., UP |
| Source | Filtrer par instance Uptime Kuma |
| Tag | Filtrer par tag de moniteur |
| Recherche | Recherche en temps reel sur le nom du moniteur |
Tableau des moniteurs
Chaque moniteur est affiche sur une ligne avec :
- Nom et lien vers l'equipement Jeedom
- Type de moniteur
- Tags (badges colores)
- Ping
- Dernier check
- Statut webhook (badge vert = Jeedom, orange = autre, rouge = aucun)
🔔 Webhooks
Les webhooks permettent a Uptime Kuma de notifier Jeedom instantanement lors d'un changement d'etat, sans attendre le prochain cycle de polling.
Fonctionnement
- Le plugin cree une notification webhook dans Uptime Kuma pointant vers Jeedom
- La notification est attachee au moniteur concerne
- Quand le statut du moniteur change, Uptime Kuma envoie un POST a Jeedom
- Jeedom met a jour les commandes du moniteur en temps reel
Activer / desactiver un webhook
- Depuis le widget moniteur : cliquer le bouton toggle webhook
- Depuis le panel : le badge webhook indique l'etat actuel
Les webhooks necessitent que Jeedom soit accessible depuis l'instance Uptime Kuma (reseau local ou URL publique). Verifiez la connectivite si les webhooks ne fonctionnent pas.
Securite des webhooks
Chaque source dispose d'un token webhook dedie genere automatiquement. Ce token est independant de la cle API Jeedom et authentifie les requetes entrantes pour empecher les appels non autorises.
💡 Exemples de scenarios
Alerte quand un service tombe
Declencheur : #[Monitoring][Mon Site Web][status]# == 0
→ Notification "Mon Site Web est DOWN !"
→ Envoyer un SMS
Alerte si ping eleve
SI #[Monitoring][API Production][ping]# > 2000
Alors → log "API Production : latence elevee (#[Monitoring][API Production][ping]# ms)"
Alors → Notification "API lente"
Resume quotidien
Programmation : tous les jours a 8h
→ Message "Moniteurs DOWN : #[Monitoring][Source Prod][monitors_down]# / #[Monitoring][Source Prod][monitor_count]#"
Relancer un service automatiquement
Declencheur : #[Monitoring][Docker Portainer][status]# == 0
→ Commande SSH : "docker restart portainer"
→ Pause 30s
→ SI #[Monitoring][Docker Portainer][status]# == 0
→ Notification "Portainer n'a pas redemarre — intervention manuelle"
📱 Panel mobile
Le plugin dispose d'un panel mobile accessible depuis l'application Jeedom. L'activer si besoin dans la configuration generale du plugin.
📋 Logs
| Log | Description |
|---|---|
uptimekuma | Log principal (polling, webhooks, synchronisation) |
uptimekuma_update | Installation des dependances |
Activer le mode Debug pour voir les echanges detailles avec l'API Uptime Kuma et le demon.
🆘 Support
En cas de probleme, utilisez le bouton Support Forum sur la page principale du plugin. Il genere automatiquement un post pre-rempli pour le forum Community Jeedom avec les informations de votre configuration (nombre de sources, moniteurs, parametres du demon).
🛠️ Depannage
Demon ne demarre pas
- Verifier les dependances (statut OK)
- Verifier que le port socket n'est pas deja utilise :
ss -tlnp | grep 55210
- Consulter le log
uptimekumaen mode Debug
Source deconnectee
- Verifier l'URL de l'instance Uptime Kuma
- Tester la connexion depuis la page de l'equipement source
- Verifier que l'instance est accessible depuis Jeedom :
curl -s -o /dev/null -w "%{http_code}" https://votre-uptime-kuma.fr
Webhooks ne fonctionnent pas
- Verifier que Jeedom est accessible depuis l'instance Uptime Kuma
- Verifier le token webhook dans les logs
- L'URL de callback utilise l'adresse interne de Jeedom — si Uptime Kuma est sur un autre reseau, configurer l'URL externe de Jeedom dans la configuration generale
Moniteurs orphelins
Si un moniteur est supprime dans Uptime Kuma, il sera marque orphelin a la prochaine synchronisation et desactive. Vous pouvez le supprimer manuellement dans Jeedom ou le reactiver si le moniteur est recree dans Uptime Kuma.
Dependances en erreur
# Verifier le venv
ls -la /var/www/html/plugins/uptimekuma/resources/venv/
# Reinstaller manuellement
cd /var/www/html/plugins/uptimekuma/resources
python3 -m venv venv
./venv/bin/pip install -r requirements.txt