Pourquoi self-héberger Uptime Kuma sur un VPS
Les services de monitoring SaaS facturent souvent au nombre de moniteurs ou à la fréquence de vérification, et plafonnent l'intervalle à 1 ou 5 minutes sur les offres gratuites. En déployant Uptime Kuma sur votre propre VPS, vous supervisez autant de sites que vous voulez, d'API, de ports TCP, de conteneurs Docker ou de serveurs DNS, avec des intervalles aussi courts que 20 secondes. Héberger la sonde sur un VPS distinct de vos serveurs de production est un atout : si votre serveur applicatif tombe, le VPS de monitoring reste debout et déclenche l'alerte. Uptime Kuma propose en plus une page de statut publique que vous pouvez exposer à vos clients, et plus de 90 canaux de notification (Telegram, e-mail, Discord, webhook). Tout reste sur votre infrastructure, sans envoyer vos URL internes à un tiers.
Les bénéfices concrets de ce template
- Moniteurs sans plafond : HTTP(s), TCP, ping, DNS, conteneurs Docker, certificats SSL et mots-clés de page.
- Alertes multi-canaux (Telegram, e-mail, Discord, Slack, webhook) avec plus de 90 intégrations.
- Page de statut publique personnalisable à partager avec vos clients ou votre équipe.
- Surveillance de l'expiration des certificats SSL pour ne plus jamais être pris au dépourvu.
- Historique et statistiques d'uptime conserves localement, sans rétention payante.
- Vérifications jusqu'à toutes les 20 secondes, impossible sur la plupart des offres gratuites.
Prérequis pour l'héberger
Uptime Kuma est très frugal : un VPS 1 vCPU avec 512 Mo à 1 Go de RAM suffit largement pour surveiller plusieurs dizaines de moniteurs. La base de données SQLite embarquée occupe peu d'espace, comptez 2 à 5 Go de disque selon l'historique conservé. Il vous faut Docker installé, un nom de domaine ou sous-domaine (status.mondomaine.com) pointe sur le VPS, et les ports 80/443 ouverts pour le reverse proxy et le SSL. Pour une supervision fiable, hébergez de préférence Uptime Kuma sur un VPS distinct de vos serveurs de production.
Déployer Uptime Kuma avec Docker et SSL
Créer le volume et lancer le conteneur
Sur le VPS, créez un volume persistant puis démarrez le conteneur :
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1. L'interface est accessible sur le port 3001.Configurer le compte administrateur
Ouvrez
http://IP_DU_VPS:3001et créez le compte admin à la première connexion. Choisissez un mot de passe fort : cette interface aura accès à toutes vos URL surveillées.Mettre un reverse proxy et le SSL devant
Configurez Nginx ou Caddy pour exposer
status.mondomaine.comverslocalhost:3001. Avec Caddy, deux lignes suffisent pour obtenir un certificat Let's Encrypt automatique :status.mondomaine.com { reverse_proxy localhost:3001 }.Ajouter vos premiers moniteurs
Créez des moniteurs HTTP(s) pour vos sites, un moniteur TCP pour votre base de données, un check SSL pour surveiller l'expiration des certificats et un mot-clé pour détecter les pages d'erreur servies en HTTP 200.
Brancher les notifications et la page de statut
Dans Paramètres > Notifications, ajoutez Telegram ou e-mail et testez l'envoi. Activez ensuite une page de statut publique regroupant vos services clients, avec un nom de domaine dédié si besoin.
Se connecter la première fois
Ouvrez l'URL sans tarder : le tout premier écran vous demande de créer le compte administrateur (nom d'utilisateur + mot de passe), puis vous accédez au tableau de bord. Il n'existe aucun identifiant par défaut.
Pour éviter les fausses alertes lors d'un micro-incident réseau, configurez le champ Retries (par exemple 3 échecs consécutifs avant alerte) et un Heartbeat Interval adapté. Combinez-le avec une notification de groupe : Uptime Kuma peut envoyer un message agrégé plutôt qu'une alerte par moniteur, ce qui évite de noyer votre canal Telegram lors d'une panne réseau globale qui fait tomber dix services d'un coup.
Ce que le moniteur Docker ne voit pas
Le moniteur de type Docker Container interroge le moteur Docker et lit l'état du conteneur. C'est pratique, mais cet état décrit le processus, pas le service. Une issue ouverte sur le dépôt de l'outil (#7956, signalée sur la version 1.23.17) en donne un cas net : un conteneur lancé avec une politique de redémarrage (restart: always, unless-stopped, ou l'option --restart=always de la commande de déploiement ci-dessus) qui plante en boucle est affiché UP avec le message « restarting ». Le rapporteur relie ce comportement au test sur State.Running, qui reste vrai pendant le délai entre deux redémarrages. Le moniteur reste vert, aucune notification ne part, et votre application ne répond plus. À la relecture du fil, l'issue était toujours ouverte, sans correctif fusionné : seuls des patchs proposés y figurent. Le moniteur Docker répond à la question « le conteneur tourne-t-il ? », pas à « l'application sert-elle correctement ses utilisateurs ? ».
Pourquoi un seul signal ne suffit pas
- Le processus tourne, le service non — un conteneur peut démarrer, planter deux secondes plus tard et redémarrer : à chaque sondage, le moteur Docker peut le décrire comme en cours d'exécution.
- Pas de healthcheck, pas de verdict — sans instruction
HEALTHCHECKdans l'image ni blochealthcheckdans votre fichier compose, le moteur n'a que l'état brut à transmettre à Uptime Kuma. - Unhealthy n'alerte pas partout — d'après le fil de l'issue, le traitement de l'état « unhealthy » comme DOWN a été fusionné pour la branche 2.1.0 (PR #6292), alors que la branche 1.x laisse ce cas en attente (PENDING), donc sans alerte. Le déploiement ci-dessus utilise l'image
louislam/uptime-kuma:1. - La politique de redémarrage masque la panne —
restart: alwaysest utile pour se remettre d'un incident isolé, mais elle transforme une panne franche en panne intermittente, que les sondages espacés ne voient pas. - Un outil de supervision peut avoir ses propres angles morts — une fonction qui marche un mois peut régresser à la mise à jour suivante : vérifiez vos alertes par un test réel, pas seulement par la lecture de l'interface.
Compléter le moniteur Docker avec plusieurs signaux
Surveiller l'application elle-même
Ajoutez un moniteur HTTP(s), ou « HTTP(s) - Keyword » si la page doit contenir un mot précis, sur l'URL de l'application (publique ou interne au VPS). Un conteneur en boucle de plantage ne répond pas : ce moniteur passe en échec alors que le moniteur Docker reste vert. Gardez Retries à 3 pour éviter les fausses alertes.
Déclarer un healthcheck dans le compose
Dans le service surveillé, ajoutez par exemple
healthcheck: test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/ || exit 1"]avecinterval: 10s,timeout: 3s,retries: 3etstart_period: 30s. Adaptez le port et l'outil : l'image doit contenirwgetoucurl. Docker affiche alors l'état healthy ou unhealthy, que vous lisez dansdocker ps.Lire le compteur de redémarrages
Sur le VPS,
docker ps --filter status=restartingliste les conteneurs en cours de redémarrage, etdocker inspect mon-app | grep -E "RestartCount|Status"donne le nombre de redémarrages et l'état. UnRestartCountqui grimpe d'un contrôle à l'autre signale une boucle, même si l'état affiché est running.Envoyer un battement avec un moniteur Push
Créez un moniteur de type Push dans Uptime Kuma, puis lancez par cron sur le VPS un petit script qui lit le
RestartCountet n'appelle l'URL Push que s'il n'a pas bougé depuis le contrôle précédent. Si le compteur grimpe, le battement manque et le moniteur passe DOWN : l'alerte repose sur un fait que le moniteur Docker ne regarde pas.Tester la chaîne d'alerte pour de vrai
Lancez un conteneur qui plante volontairement :
docker run -d --name crash-test --restart unless-stopped alpine sh -c "sleep 2; exit 1". Créez un moniteur Docker surcrash-test: s'il reste UP pendant quedocker ps --filter status=restartingle liste, vous reproduisez le cas décrit dans l'issue. Vérifiez que votre moniteur HTTP ou Push, lui, déclenche bien la notification, puis supprimez le conteneur avecdocker rm -f crash-test.
Le Retry d'un moniteur TCP : un cas corrigé, à vérifier sur votre version
Une seconde issue (#7979) concernait le champ Retries. Sur la version 2.5.6, un moniteur de type TCP Port configuré avec SSL ou StartTLS ignorait ce réglage : au premier échec, il passait directement en rouge, alors que les moniteurs HTTP(s) avec le même nombre de tentatives passaient d'abord en attente. Le cas est plus étroit que l'intitulé ne le laisse croire : il touche la variante TCP avec TLS, pas tous les moniteurs TCP. L'issue a été fermée avec la correction de la PR #7989, que les notes de version 2.5.7 listent. Si vous surveillez un port TLS (messagerie, XMPP, base de données chiffrée) avec une version antérieure, vous recevez des alertes sur chaque échec isolé. Mettez l'outil à jour, puis vérifiez le comportement en coupant le service testé : le moniteur doit passer en attente avant de tomber. Autre précision tirée du fil : le champ Down Count est un compteur lié au renvoi des notifications, pas un compteur de tentatives.
Une alerte, plusieurs signaux
Rattachez le moniteur HTTP, le moniteur Push et le moniteur Docker à la même notification de groupe, et réservez le message d'urgence au signal applicatif : une page qui ne répond plus est une panne, un RestartCount qui monte est un avertissement à traiter dans l'heure. Ainsi, une défaillance d'un seul moniteur ne laisse plus votre canal Telegram silencieux.
La documentation officielle
Pour la configuration avancée et les options propres à l'outil, référez-vous à la documentation officielle de Uptime Kuma. Ce guide couvre la mise en ligne sur VPS ; la doc éditeur reste la référence pour les réglages fins, les mises à jour majeures et les cas d'usage spécifiques.
