Uptime Kuma : surveiller la disponibilité de vos services

Un site web qui ne répond plus, un certificat TLS expiré pendant le week-end, une API interne qui renvoie des erreurs depuis deux heures sans que personne ne s’en aperçoive : ces incidents ont un point commun, ils auraient pu être détectés en quelques secondes. Avant même de déployer une plateforme de supervision complète, la première question à se poser est simple : mes services sont-ils joignables, et suis-je prévenu dès qu’ils ne le sont plus ?

C’est exactement le terrain d’Uptime Kuma, un outil de supervision de disponibilité open source et auto-hébergé, devenu en quelques années l’un des projets de monitoring les plus populaires sur GitHub (plus de 90 000 étoiles). Dans cet article, nous verrons ce qu’est Uptime Kuma, comment il fonctionne, comment l’installer et le configurer, comment il se positionne face aux alternatives, et quelles bonnes pratiques appliquer pour l’exploiter sereinement en production.

Qu’est-ce qu’Uptime Kuma ?

Uptime Kuma est un outil de supervision « fancy » et auto-hébergé, créé par Louis Lam et publié sous licence MIT. Il se présente comme une alternative auto-hébergée aux services SaaS de type « uptime monitoring » : vous l’installez sur votre propre serveur, vous déclarez les ressources à surveiller, et il vous alerte dès qu’une sonde échoue.

Ses principales fonctionnalités, telles que décrites par le projet :

Sondes variées : HTTP(s), TCP, mot-clé HTTP(s), requête JSON sur une réponse HTTP(s), WebSocket, Ping, enregistrement DNS, Push, serveurs de jeux Steam et conteneurs Docker.
Notifications vers plus de 90 services : Telegram, Discord, Gotify, Slack, Pushover, e-mail (SMTP), etc.
Intervalles de vérification descendant jusqu’à 20 secondes.
Pages de statut multiples, avec association à un nom de domaine dédié.
Graphiques de latence et informations sur les certificats TLS.
Support des proxys, authentification à deux facteurs et interface multilingue (dont le français).

La branche 2.x, sortie en version stable en octobre 2025, a apporté le support de MariaDB en plus de SQLite, une image Docker pouvant tourner sans privilèges root, des modèles de notification et une interface modernisée. À la date de rédaction, la dernière version publiée est la 2.5.8 (octobre 2026), qui corrige notamment une vulnérabilité d’exécution de code exploitable par un compte administrateur : raison de plus pour maintenir votre instance à jour.

Architecture et fonctionnement

Uptime Kuma est une application Node.js monolithique : un même processus embarque le serveur web (interface Vue.js), le moteur d’ordonnancement des sondes et la gestion des notifications. L’interface communique avec le serveur en temps réel via WebSocket (Socket.IO), ce qui explique l’affichage instantané des changements d’état… et la nécessité de configurer correctement le support WebSocket si vous placez l’outil derrière un reverse proxy.

Chaque élément surveillé est un « monitor » : une sonde d’un type donné, exécutée à intervalle régulier, avec un nombre de tentatives avant de déclarer l’incident et un intervalle de nouvelle tentative. Le résultat de chaque vérification (un « heartbeat ») est enregistré en base. Lors de l’assistant d’installation de la version 2, trois choix de stockage sont proposés :

SQLite : le choix le plus simple, adapté aux petites et moyennes installations ;
MariaDB embarquée : gérée directement par Uptime Kuma ;
MariaDB/MySQL externe : une base que vous installez et administrez vous-même, pertinente pour les déploiements comptant des centaines de sondes.

Un mode de fonctionnement mérite une mention particulière : le monitor Push. Ici, ce n’est pas Uptime Kuma qui interroge la cible, c’est la cible qui appelle une URL unique à intervalle régulier. Si l’appel n’arrive pas dans le délai prévu, l’alerte se déclenche. C’est idéal pour surveiller une tâche planifiée (sauvegarde nocturne, script cron) ou un service situé derrière un pare-feu qui ne peut pas être sondé de l’extérieur.

Installation avec Docker

La méthode recommandée par le projet est le déploiement via Docker. Les données (base SQLite, configuration, certificats éventuels) sont stockées dans le répertoire /app/data du conteneur, qu’il faut impérativement persister dans un volume. L’interface est ensuite accessible sur le port 3001. Le projet fournit également un fichier compose.yaml prêt à l’emploi pour Docker Compose :

# Option 1 : Docker Compose (fichier fourni par le projet)
mkdir uptime-kuma
cd uptime-kuma
curl -o compose.yaml https://raw.githubusercontent.com/louislam/uptime-kuma/master/compose.yaml
docker compose up -d

# Option 2 : conteneur unique
docker run -d --restart=always -p 3001:3001 \
  -v uptime-kuma:/app/data \
  --name uptime-kuma louislam/uptime-kuma:2

# Mise à jour ultérieure (Compose)
docker compose pull && docker compose up -d

Une fois le conteneur démarré, rendez-vous sur http://<votre-serveur>:3001 : l’assistant vous demande de choisir le type de base de données puis de créer le compte administrateur. Si vous débutez avec les conteneurs, notre cours d’introduction à Docker couvre les notions de volumes, de ports et de Compose utilisées ici.

Attention à un point souligné par la documentation : les systèmes de fichiers réseau de type NFS ne sont pas supportés pour le volume de données, en raison des risques de corruption de la base SQLite. Utilisez un volume local.

Installation sans Docker

Uptime Kuma peut aussi être installé directement sur l’hôte. Les prérequis sont Node.js 20.4 ou supérieur et Git, sur une distribution Linux courante (Debian, Ubuntu, Fedora, Arch…) ou sur Windows 10 / Windows Server 2012 R2 (x64) et versions ultérieures. FreeBSD, OpenBSD et NetBSD ne sont pas supportés. Pour exécuter le service en arrière-plan et le relancer automatiquement, le projet recommande PM2 :

git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setup

# Lancement au premier plan (test)
node server/server.js

# Lancement en arrière-plan avec PM2
npm install pm2 -g && pm2 install pm2-logrotate
pm2 start server/server.js --name uptime-kuma
pm2 save && pm2 startup

Pour les mises à jour d’une installation manuelle, il suffit de récupérer la nouvelle version via Git puis de relancer npm run setup afin de reconstruire les dépendances, avant de redémarrer le processus.

Prise en main : sondes, alertes et pages de statut

La configuration se fait entièrement depuis l’interface web. Un parcours type pour une PME ou un service informatique ressemble à ceci :

Déclarer les notifications d’abord : dans les paramètres, configurez au moins deux canaux (par exemple une messagerie d’équipe et l’e-mail), puis associez-les par défaut aux nouveaux monitors.
Créer les monitors : HTTP(s) pour les sites et API (avec vérification d’un mot-clé ou d’une valeur JSON pour s’assurer que la page renvoie le bon contenu, pas seulement un code 200), TCP pour les ports applicatifs (SMTP, RDP, bases de données), Ping pour les équipements réseau, DNS pour vérifier qu’un enregistrement n’a pas changé.
Surveiller les certificats : activez la notification d’expiration TLS sur les monitors HTTPS pour être prévenu avant l’échéance.
Planifier les maintenances : les fenêtres de maintenance évitent les fausses alertes pendant une intervention prévue et l’affichent sur les pages de statut.
Publier une page de statut : regroupez les services par catégorie, associez éventuellement un sous-domaine (status.votre-domaine.fr) et partagez-la avec vos utilisateurs ou clients pour réduire les sollicitations du support lors d’un incident.

Uptime Kuma expose en outre ses données au format Prometheus via l’endpoint /metrics, protégé par clé d’API. Vous pouvez ainsi intégrer l’état et la latence de vos sondes dans une stack Prometheus existante et les visualiser dans vos tableaux de bord.

Uptime Kuma face aux alternatives

Uptime Kuma ne prétend pas remplacer une plateforme de supervision d’infrastructure. Il répond à une question précise, la disponibilité vue de l’extérieur, et c’est là qu’il excelle :

Face à Zabbix ou Centreon : ces solutions supervisent en profondeur (CPU, mémoire, disques, services, SNMP, agents, découverte automatique) mais demandent un vrai effort de déploiement et d’administration. Uptime Kuma s’installe en cinq minutes et ne collecte aucune métrique interne aux serveurs. Les deux approches sont complémentaires : beaucoup d’équipes utilisent Uptime Kuma comme « sonde externe » qui surveille aussi… le serveur de supervision principal.
Face à Prometheus et Blackbox Exporter : la combinaison offre des sondes HTTP, TCP, ICMP et DNS très configurables, mais tout se définit en fichiers YAML et nécessite Alertmanager pour les alertes. Uptime Kuma privilégie la simplicité de l’interface graphique.
Face aux services SaaS (UptimeRobot, Better Stack, Pingdom…) : ils sondent depuis plusieurs régions du monde et ne dépendent pas de votre infrastructure, mais vos données et la liste de vos services partent chez un tiers, avec des limites selon l’offre. Uptime Kuma garde tout en interne, sans limite de nombre de sondes.
Face à Gatus : autre outil open source de surveillance de disponibilité, configuré en YAML (approche « as code »), apprécié dans les environnements Kubernetes. Uptime Kuma reste plus accessible pour les équipes qui préfèrent une configuration graphique.

Bonnes pratiques

Hébergez-le en dehors de ce qu’il surveille : une instance installée sur le même hôte ou le même réseau que vos services tombera en même temps qu’eux. Un petit VPS externe, ou deux instances qui se surveillent mutuellement, est la configuration la plus fiable.
Ne l’exposez pas tel quel sur Internet : placez l’interface d’administration derrière un reverse proxy en HTTPS (avec support WebSocket), activez la 2FA sur le compte administrateur et, si possible, restreignez l’accès par VPN ou liste d’adresses IP. Seules les pages de statut ont vocation à être publiques.
Mettez à jour régulièrement : suivez les releases GitHub, en particulier les correctifs de sécurité comme celui de la version 2.5.8. Lisez les notes de version, la branche 2.x ayant introduit plusieurs changements incompatibles.
Sauvegardez le répertoire data : depuis la version 2, l’export/import JSON a été supprimé ; la sauvegarde du répertoire de données (ou de la base MariaDB) est la seule méthode supportée.
Réglez finement les tentatives : pour les services sensibles aux micro-coupures, configurez une ou deux nouvelles tentatives avant alerte afin d’éviter la fatigue d’alerte. Depuis la v2, la valeur par défaut est de zéro tentative.
Privilégiez les sondes « métier » : un code HTTP 200 ne garantit pas que l’application fonctionne. Vérifiez la présence d’un mot-clé ou d’une valeur JSON significative, et utilisez les monitors Push pour vos tâches planifiées critiques.

Conclusion

Uptime Kuma coche les cases attendues d’un bon outil d’exploitation : gratuit, open source, rapide à déployer, et immédiatement utile. En quelques minutes, il vous donne une vision claire de la disponibilité de vos sites, API, ports et certificats, avec des alertes sur les canaux que vos équipes consultent réellement et des pages de statut prêtes à partager. Il ne remplace pas une supervision d’infrastructure complète, mais il en constitue le complément idéal, et souvent le premier pas, pour toute organisation qui veut cesser d’apprendre ses pannes par ses utilisateurs.

Partagez cet article !