Uptime Kuma : installer un monitoring auto-hébergé

Ce que vous allez mettre en place

Un conteneur léger qui surveille vos autres serveurs et sites web depuis l’extérieur, puis vous avertit dès que l’un d’eux ne répond plus, par e-mail, Telegram, Discord ou webhook. Uptime Kuma est un processus Node qui utilise un fichier SQLite. Il fonctionne donc confortablement avec 256-512 MB de RAM et fournit un tableau de bord en temps réel, des graphiques d’historique ainsi qu’une page d’état publique. L’installation tient dans un fichier Compose de dix lignes. Le point réellement important est l’endroit où vous l’exécutez et le fait d’avoir vérifié que vos alertes se déclenchent lors d’un test. Un monitor dont vous n’avez jamais prouvé qu’il pouvait vous joindre est pire que pas de monitor du tout : il vous donne l’impression d’être protégé alors qu’il ne surveille rien.

Exécutez le monitor à un endroit que la panne ne peut pas atteindre

Cette décision conditionne toute la fiabilité du dispositif. Elle doit donc être prise en premier. N’exécutez pas Uptime Kuma sur le même serveur que les services surveillés. Si le monitor s’exécute sur le serveur qu’il surveille, l’événement que vous voulez détecter — l’arrêt du serveur ou l’épuisement de sa mémoire — arrête aussi le monitor. Vous ne recevez alors aucune alerte : le silence d’un monitor arrêté est identique à « tout va bien ». Un problème plus subtil peut survenir alors que le serveur fonctionne encore : un monitor qui vérifie localhost partage le CPU avec la charge de travail. Une hausse de charge peut donc faire expirer son propre contrôle et faire passer la cible à l’état down, ce qui produit une fausse alerte, alors que les utilisateurs continuent d’accéder correctement au service.

Exécutez donc Uptime Kuma sur un VPS différent de celui qu’il surveille, si possible chez un autre fournisseur ou dans une autre région. Il doit accéder à vos services comme vos utilisateurs : via Internet public et par leur nom d’hôte. Une petite instance à bas coût suffit. Un seul petit VPS de monitoring peut surveiller tous vos serveurs. Cette séparation est particulièrement importante pour les applications lourdes que vous hébergez. Par exemple, une bibliothèque photo PhotoPrism ou Immich peut utiliser le CPU pendant plusieurs heures lors de l’indexation d’un nouvel import. Un monitor qui partage ce matériel signalerait alors à tort qu’un service est down, alors qu’il est simplement très sollicité. Pour détecter également l’arrêt de Kuma lui-même, ajoutez un heartbeat push exécuté par un cron situé ailleurs.

Prérequis et dimensionnement

• Un VPS Ubuntu 24.04 fraîchement installé, avec Docker Engine et le plugin Compose v2, installés depuis le dépôt apt officiel de Docker, et non depuis le paquet de distribution docker.io, qui est moins à jour.
• 256 MB de RAM suffisent pour quelques monitors. 512 MB à 1 GB offrent une marge confortable pour plusieurs dizaines de monitors et le reverse proxy. Le processeur est presque inactif entre les vérifications.
• Un domaine et un enregistrement DNS A, par exemple status.example.com pointant vers le VPS, uniquement si vous voulez utiliser TLS et publier une page de statut. Une instance privée peut se passer de DNS et utiliser un VPN ou un tunnel SSH.
• Un accès réseau sortant vers les services qui reçoivent les alertes : SMTP vers votre fournisseur de messagerie, ou HTTPS vers Telegram et Discord.

Le fichier Compose

Placez ce contenu dans /srv/uptime-kuma/compose.yaml.

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - kuma-data:/app/data

volumes:
  kuma-data:

Démarrez le conteneur et surveillez le premier démarrage :

sudo mkdir -p /srv/uptime-kuma
# save the file above as /srv/uptime-kuma/compose.yaml, then:
cd /srv/uptime-kuma && sudo docker compose up -d
sudo docker compose logs -f uptime-kuma

Un démarrage correct journalise Listening on 3001, puis cesse d’écrire. Trois éléments de ce fichier sont intentionnels.

127.0.0.1:3001:3001, et non 3001:3001. Docker publie les ports avec des règles DNAT évaluées avant qu’ufw ne voie le paquet. Une valeur 3001:3001 seule expose donc votre tableau de bord sur Internet, quelle que soit votre configuration du pare-feu. La liaison à loopback le garde privé et n’expose que le reverse proxy. Une instance privée peut se passer du proxy et accéder à 3001 via un VPN WireGuard auto-hébergé.

Un volume nommé dans /app/data. Tout ce qu’Uptime Kuma mémorise y est stocké : la base SQLite, vos monitors, les paramètres de notification et les logos des pages d’état. Si vous le perdez, vous repartez d’un écran d’administration vide. C’est le seul élément que vous devez sauvegarder.

L’image est figée sur le tag majeur :2. Il s’agit de la branche stable actuelle. Consultez Docker Hub pour vérifier le dernier tag majeur avant de le copier. Ne suivez jamais un tag mobile comme latest, que le projet déconseille. Le passage à une version majeure de cette image est une migration de base de données irréversible. Vous devez la déclencher volontairement, et non la subir lors d’un pull courant.

Une réserve : /app/data doit se trouver sur un système de fichiers prenant en charge les verrous de fichiers POSIX. Un volume Docker local convient. Sur NFS, la base SQLite est corrompue et vous obtenez SQLITE_BUSY et database disk image is malformed. N’utilisez donc jamais un partage réseau.

Première exécution : créer le compte administrateur

Accédez à l’instance via votre proxy à l’adresse https://status.example.com, ou utilisez un tunnel SSH : exécutez ssh -L 3001:127.0.0.1:3001 user@your-vps, puis ouvrez http://localhost:3001. La première page contient le formulaire de configuration du nom d’utilisateur et du mot de passe de l’administrateur. Aucun identifiant par défaut n’est configuré. Choisissez un mot de passe robuste : ce dashboard voit les adresses internes et les tokens de tous les éléments que vous surveillez. Vous l’avez oublié ? Réinitialisez-le depuis l’hôte, pas depuis le navigateur :

sudo docker compose exec uptime-kuma npm run reset-password

Ajoutez d’abord vos canaux de notification et testez-les

Configurez les alertes avant d’ajouter les monitors, afin de pouvoir associer un canal lors de la création de chacun. Accédez à Settings then Notifications then Setup Notification, puis utilisez le bouton Test de chaque canal pour vérifier que le message arrive bien. Une notification non testée est la deuxième cause la plus fréquente d’échec silencieux d’une configuration.

Email (SMTP). Renseignez l’hôte, le port, le chiffrement, le nom d’utilisateur, le mot de passe, un champ From et un champ To. Les deux combinaisons fonctionnelles sont 465 avec Secure réglé sur TLS/SSL, ou 587 avec STARTTLS. Pour Gmail et la plupart des fournisseurs utilisant l’authentification à deux facteurs, vous devez générer un app password ; un mot de passe de compte normal renvoie Error: Invalid login: 535-5.7.8 Username and Password not accepted.

Telegram. Envoyez le message @BotFather, envoyez /newbot, puis copiez le bot token. Pour obtenir votre chat ID, envoyez d’abord un message au nouveau bot, ouvrez https://api.telegram.org/bot<token>/getUpdates et relevez chat.id dans le JSON. Un bot auquel vous n’avez jamais envoyé de message a un getUpdates vide et ne sait pas où envoyer les notifications.

Discord. Dans le canal, ouvrez Edit Channel then Integrations then Webhooks then New Webhook, copiez l’URL, puis collez-la comme notification Discord.

Webhook générique. Pour les autres services, comme un incoming webhook Slack, un endpoint personnalisé ou un hook de domotique, le type Webhook envoie une charge utile JSON en POST à l’URL indiquée. L’intégration Apprise fournie prend en charge la plupart des quelque quatre-vingt-dix autres services de la liste. Si vous préférez qu’aucun tiers ne s’interpose entre une panne et votre téléphone, choisissez le type ntfy intégré et pointez-le vers un serveur ntfy que vous gérez vous-même. Il envoie alors les notifications sur votre téléphone via un canal que vous contrôlez de bout en bout.

Ajouter les monitors, un type à la fois

Cliquez sur Add New Monitor, choisissez un type, puis définissez le Friendly Name, le Check Interval (60 seconds est un réglage raisonnable), les Retries (nombre d’échecs consécutifs avant de considérer le service comme « down » ; utilisez 2 ou 3 pour qu’un paquet perdu ne déclenche pas d’alerte) et les notifications à envoyer. Les types que vous utiliserez sont les suivants :

• HTTP(s). Une URL complète. Le service est considéré comme disponible si le code de statut est accepté (200-299 par défaut ; élargissez cette plage dans Accepted Status Codes si 301 ou 401 est normal dans votre cas). C’est le monitor principal pour les sites web et les API.
• HTTP(s) - Keyword. La même requête, mais le service est considéré comme disponible uniquement si une chaîne est présente dans le corps de la réponse, ou absente avec Invert. Ce contrôle détecte le cas où le site renvoie 200 OK tout en affichant « Error establishing a database connection », ce qu’un simple contrôle HTTP considère comme normal. Il convient également à une interface web qui communique avec un backend distinct, par exemple une interface de boutique vidéo Halcyon au-dessus de Jellyfin, dont la page renvoie correctement 200 alors que le media server auquel elle se connecte est inaccessible.
• TCP Port. Une simple connexion TCP à un hôte et à un port, pour les services qui n’utilisent pas HTTP : SSH sur 22, Postgres sur 5432, un serveur SMTP sur 25 ou un serveur de jeu.
• Ping. Un echo ICMP pour vérifier rapidement l’accessibilité et la latence. Cependant, de nombreux réseaux et cloud firewalls bloquent ICMP. Un monitor ping en erreur peut donc signifier que l’hôte est indisponible ou que le fournisseur bloque le ping ; confirmez avec un monitor TCP.
• DNS. Résout un enregistrement (A, AAAA, MX, TXT, etc.) auprès du resolver que vous indiquez et peut vérifier la réponse. Vous détectez ainsi rapidement une panne du registrar ou du DNS.
• Push. Le monitor inversé, présenté dans la section suivante.

Surveiller un cron job avec un monitor push (heartbeat)

Tous les monitors précédents interrogent votre service depuis l’extérieur. Un monitor push fonctionne dans l’autre sens : Uptime Kuma attend, et votre job l’appelle pour signaler qu’il s’est exécuté. C’est la seule façon fiable de surveiller un backup ou un cron : un contrôle HTTP sait qu’une URL répond, mais seul le job sait qu’il s’est terminé.

Créez un monitor de type Push. Uptime Kuma génère une URL unique telle que :

https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=OK&ping=

Définissez l’Heartbeat Interval sur la fréquence d’exécution du job, en ajoutant une petite marge. Ajoutez ensuite une ligne à la fin du script, afin qu’elle ne soit exécutée qu’en cas de succès :

#!/usr/bin/env bash
set -euo pipefail
# ... your backup or job runs here; set -e aborts on any failure ...
curl -fsS --retry 3 "https://status.example.com/api/push/j8Xa2Kd9Qe?status=up&msg=backup+ok&ping="

Si le job échoue, set -e s’arrête avant l’appel à curl. Si le serveur est indisponible, le job ne s’exécute pas non plus. Dans les deux cas, le heartbeat s’arrête. Une fois le délai correspondant à l’intervalle augmenté du nombre de retries écoulé, Uptime Kuma passe le monitor à down et vous alerte. Considérez ce push token comme un secret : toute personne qui le possède peut simuler un heartbeat sain.

Créer une page d’état publique

Une page d’état est la vue destinée aux clients : elle indique quels services sont opérationnels et affiche leur historique récent, sans exposer votre tableau de bord. Accédez à Status Pages puis New Status Page, donnez-lui un nom et un slug (le chemin public, par exemple /status/main), puis faites glisser les monitors voulus dans des groupes tels que « Websites » et « APIs ». Ajoutez un logo et une courte description, puis cliquez sur Save. Vous pouvez également associer la page à son propre domaine afin que status.example.com la serve directement.

Deux précautions s’imposent : n’ajoutez que les monitors que vous acceptez de rendre publics, car une page d’état révèle qu’un service existe et indique s’il est opérationnel ; le tableau de bord reste protégé par votre authentification, tandis que la page d’état est volontairement publique et ne nécessite aucune authentification.

Placez-le derrière un reverse proxy avec TLS et n’oubliez pas les WebSockets

Pour une instance publique, placez un reverse proxy devant le conteneur lié à loopback afin de gérer TLS et un nom d’hôte. Le point qui pose le plus souvent problème est le suivant : l’interface d’Uptime Kuma est une application Socket.IO dynamique. Le proxy doit donc mettre à niveau la connexion WebSocket. Si vous oubliez cette configuration, la page se charge mais ne se connecte jamais ; le tableau de bord reste bloqué sur « Connecting... », les heartbeats ne se mettent jamais à jour et la console du navigateur affiche WebSocket connection to 'wss://.../socket.io/...' failed.

Installez nginx et certbot, puis créez le vhost qui relaie les requêtes vers le port loopback. Utilisez le port 80 pour le moment et laissez ensuite certbot ajouter TLS ; le challenge, le timer de renouvellement et les cas d’échec sont décrits dans émettre des certificats Let's Encrypt avec certbot et nginx.

sudo apt install -y nginx certbot python3-certbot-nginx

Enregistrez ce contenu dans /etc/nginx/sites-available/status.example.com ; les deux lignes WebSocket sont les plus importantes :

server {
    listen 80;
    server_name status.example.com;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600s;
    }
}

Activez le site, testez la configuration, puis laissez certbot modifier le bloc pour écouter sur 443, installer le certificat et ajouter une redirection HTTP vers HTTPS :

sudo ln -s /etc/nginx/sites-available/status.example.com /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d status.example.com

Le couple Upgrade et Connection "upgrade" est essentiel, tandis que proxy_read_timeout 3600s empêche nginx de fermer la socket persistante ; certbot recopie ces deux directives dans le bloc 443 qu’il génère. Si vous exécutez déjà plusieurs conteneurs derrière un même proxy, les acheminer via Traefik avec TLS automatique permet d’obtenir le même résultat avec des labels de conteneur et transmet les mises à niveau WebSocket par défaut.

Ne protégez pas tout le vhost avec une authentification basique, car cela bloquerait également la page d’état publique et le endpoint /api/push. Conservez la connexion intégrée d’Uptime Kuma, ajoutez fail2ban pour surveiller les échecs de connexion répétés si le service est exposé à Internet et, si le tableau de bord n’a jamais besoin d’être public, supprimez le proxy et accédez-y via un VPN.

Surveillez correctement l’expiration des certificats

Un monitor HTTP(s) peut également vous avertir avant l’expiration d’un certificat TLS : activez Certificate Expiry Notification et Uptime Kuma vous alertera le nombre de jours défini à l’avance. Deux erreurs peuvent fausser le résultat. Configurez le monitor avec le nom d’hôte, pas l’adresse IP. Une requête sans SNI reçoit le certificat par défaut du serveur, et vous obtenez Hostname/IP does not match certificate's altnames. N’activez pas non plus Ignore TLS/SSL Error sur un monitor dont vous voulez recevoir les alertes d’expiration. Cette option sert aux hôtes internes utilisant des certificats autosignés (unable to verify the first certificate, DEPTH_ZERO_SELF_SIGNED_CERT), mais elle empêche Uptime Kuma de vérifier le certificat, y compris sa date d’expiration.

Sauvegardes : un seul répertoire

Comme tout se trouve dans /app/data, une sauvegarde consiste à copier ce volume lorsque le conteneur est arrêté. Le fichier SQLite est ainsi cohérent :

cd /srv/uptime-kuma
sudo docker compose stop
sudo docker run --rm \
  -v uptime-kuma_kuma-data:/data \
  -v /var/backups/kuma:/backup \
  alpine tar czf /backup/kuma-$(date -u +%Y%m%dT%H%M%SZ).tgz -C /data .
sudo docker compose start

Vérifiez d’abord le nom réel du volume avec docker volume ls | grep kuma, car Compose le préfixe avec le répertoire du projet. Copiez ensuite l’archive tar hors du serveur. Une sauvegarde stockée sur le même VPS est une copie, pas une sauvegarde. La restauration suit le processus inverse : arrêtez la stack, extrayez l’archive dans un volume /app/data vide, puis démarrez-la.

Mises à niveau

Les mises à niveau consistent à récupérer une image :

cd /srv/uptime-kuma
sudo docker compose pull
sudo docker compose up -d

Le nouveau conteneur exécute les migrations de base de données lors du premier démarrage ; surveillez docker compose logs -f. Effectuez la sauvegarde indiquée plus haut avant de récupérer l’image et restez dans la même version majeure : passer de :1 à :2 est une migration irréversible. Effectuez donc d’abord une sauvegarde et consultez les notes de version.

Modes de défaillance et messages affichés

Fausse alerte « down » avec un monitor pointant vers localhost. Le monitor passe au rouge avec timeout of 48000ms exceeded ou connect ETIMEDOUT, alors que le service répond depuis votre laptop. S’il cible le même hôte que celui où Uptime Kuma s’exécute, un pic de CPU ou de mémoire a empêché le check de s’exécuter correctement. Le problème ne vient pas de la cible. Déplacez le monitor sur un VPS distinct et ciblez le hostname public.

connect ECONNREFUSED 127.0.0.1:443 (ou n’importe quel port). Aucun processus n’écoutait sur ce port. Soit le service est arrêté, soit vous avez monitoré localhost depuis l’intérieur du conteneur, où 127.0.0.1 désigne le conteneur, et non votre serveur. Monitorez le hostname public, pas la boucle locale.

Invalid login: 535-5.7.8 Username and Password not accepted lors d’un test d’e-mail. Les identifiants SMTP sont incorrects, ou le fournisseur exige un mot de passe spécifique à l’application et vous avez fourni le mot de passe de votre compte. Générez un mot de passe d’application et utilisez-le.

connect ETIMEDOUT ou queryA ETIMEDOUT <host> lors d’un test d’e-mail. Le port est incorrect ou le fournisseur bloque le SMTP sortant. Vérifiez que 465 ou 587 correspond au paramètre Secure/STARTTLS, puis effectuez un test depuis l’hôte avec nc -vz smtp.example.com 587. De nombreux fournisseurs bloquent les connexions sortantes sur 25. Certains bloquent aussi les ports de submission tant que vous ne leur en avez pas fait la demande.

self signed certificate ou unable to verify the first certificate lors d’un test d’e-mail. Votre serveur SMTP présente un certificat que Node ne considère pas comme fiable. Corrigez le certificat du serveur de messagerie au lieu de désactiver cette vérification.

Le dashboard reste bloqué sur « Connecting... » et la console affiche WebSocket connection ... failed. Le reverse proxy ne met pas à niveau la connexion WebSocket. Ajoutez les en-têtes Upgrade et Connection "upgrade" dans nginx, ou utilisez un proxy qui les transmet par défaut, comme Traefik ou Caddy. Le HTML se charge, car il s’agit d’un GET HTTP normal. Seule la socket persistante nécessite cette mise à niveau.

Le monitor d’expiration des certificats n’émet jamais d’alerte ou émet de fausses alertes. Soit l’option Ignore TLS/SSL Error est cochée, ce qui désactive la vérification des certificats, soit le monitor cible une adresse IP et reçoit le mauvais certificat parce que le SNI est absent. Il affiche alors Hostname/IP does not match certificate's altnames. Désélectionnez l’option d’ignorance des erreurs et monitorez le service avec son hostname.

SQLITE_BUSY ou database disk image is malformed dans les journaux. Le volume /app/data se trouve sur un système de fichiers sans verrouillage correct, généralement NFS. Déplacez-le vers un volume Docker local et restaurez les données depuis une sauvegarde.

FAQ

Où dois-je exécuter mon outil de surveillance de disponibilité ?

Sur un serveur différent de ceux qu’il surveille, idéalement chez un autre fournisseur ou dans une autre région. Il doit les contacter par leur nom d’hôte sur Internet public, comme le font vos utilisateurs. Si l’outil de surveillance partage un serveur avec ses cibles, la panne qui arrête le serveur arrête aussi l’outil. Un hôte surchargé peut également le faire signaler comme « down » des services qui fonctionnent correctement. Un petit VPS séparé évite ces deux problèmes.

Comment recevoir des alertes sur Telegram ou par e-mail ?

Ajoutez le canal dans Settings puis Notifications, puis associez-le à chaque outil de surveillance. Pour Telegram, créez un bot avec @BotFather et récupérez chat.id depuis https://api.telegram.org/bot<token>/getUpdates. Pour les e-mails, utilisez 465 pour SSL ou 587 pour STARTTLS, avec un mot de passe d’application si votre fournisseur utilise l’authentification à deux facteurs. Cliquez sur Test et vérifiez que le message arrive avant de vous y fier.

Uptime Kuma peut-il surveiller une tâche cron ou un script de sauvegarde ?

Oui. Il s’agit du monitor Push : Uptime Kuma vous fournit une URL et vous devez appeler curl à la fin du script, afin que la notification soit envoyée uniquement en cas de succès. Si la tâche échoue ou si le serveur est arrêté, le heartbeat n’arrive jamais et vous recevez une alerte une fois l’intervalle écoulé. C’est la seule méthode fiable pour vérifier qu’une tâche planifiée s’est réellement exécutée, car un contrôle externe ne peut pas voir ce qui se passe à l’intérieur.

Uptime Kuma ou Zabbix : lequel dois-je utiliser ?

Uptime Kuma répond en dix minutes à la question « le service est-il disponible depuis l’extérieur et ai-je reçu l’alerte ? », avec très peu de ressources et une page d’état. Il ne collecte pas de métriques détaillées comme les tendances du CPU, de la mémoire et de l’espace disque, ni les seuils à l’échelle d’un parc. Pour cela, un serveur de surveillance Zabbix complet est l’outil plus lourd, basé sur des agents, et beaucoup de personnes utilisent les deux. Vous ne savez toujours pas quoi auto-héberger ? notre tour d’horizon des services à auto-héberger en 2026 remet la surveillance dans son contexte.