Uptime Kuma : savoir que son site est tombé avant ses utilisateurs

Il y a une sensation désagréable que tous ceux qui hébergent quelque chose connaissent : apprendre qu'un site est en panne parce qu'un utilisateur vous l'écrit. Pas parce qu'un outil vous a prévenu. Le site est tombé un dimanche soir, et c'est le lundi matin, en lisant un message un peu agacé, que vous le découvrez.

Uptime Kuma règle exactement ça. Il regarde vos services depuis l'extérieur, comme le ferait un visiteur, et vous prévient en moins d'une minute quand quelque chose ne répond plus. Je l'utilise en complément de Beszel, et je vous explique ici comment je l'ai installé et configuré, de la première sonde aux réglages avancés.

Beszel regarde dedans, Uptime Kuma regarde dehors

Dans mon article sur Beszel, je surveille l'intérieur des machines : processeur, mémoire, disques, conteneurs. C'est indispensable, mais ça ne répond pas à la question qui compte vraiment pour un utilisateur : est-ce que le site répond ?

Un serveur peut avoir 10 % de CPU et de la mémoire libre, et servir pourtant une erreur 502 parce qu'un conteneur a redémarré en boucle ou qu'un certificat a expiré. Uptime Kuma fait de l'hypervision : il teste chaque service de bout en bout, et donne une vue d'ensemble de toutes les applications d'un seul coup d'œil.

Étape 1 : l'installation

Un seul conteneur, un volume pour les données. Comme tous mes services, il passe derrière Traefik :

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - uptime-kuma:/app/data
    networks: [traefik_web]
    labels:
      - traefik.enable=true
      - traefik.http.routers.kuma.rule=Host(`status.monsite.fr`)
      - traefik.http.routers.kuma.entrypoints=websecure
      - traefik.http.routers.kuma.tls.certresolver=letsencrypt
      - traefik.http.services.kuma.loadbalancer.server.port=3001

volumes:
  uptime-kuma:

networks:
  traefik_web:
    external: true

On ouvre l'adresse, on crée le compte administrateur, et c'est prêt. Si vous n'avez pas de reverse proxy, publiez simplement le port 3001:3001 pour commencer.

Étape 2 : la première sonde

« Ajouter une sonde », type HTTP(s), l'URL du site, un intervalle de 60 secondes. Quelques secondes plus tard, une barre verte apparaît.

Pour chaque sonde, le tableau de bord affiche le temps de réponse en continu, et le pourcentage de disponibilité sur 24 heures et 30 jours. Ce dernier chiffre est très parlant : 99,9 % sur 30 jours, c'est environ 43 minutes d'indisponibilité dans le mois. Le voir écrit change la façon dont on considère les « petites coupures ».

Bien plus que des sites web

Uptime Kuma sait tester presque tout ce qui a une adresse :

Port TCP : une base de données, un serveur SMTP, un SSH ;
Ping : la machine répond-elle ?
DNS : l'enregistrement renvoie-t-il bien la bonne IP ?
Conteneur Docker : tourne-t-il ?
Mot-clé et requête JSON : la page contient-elle ce qu'elle devrait ?
et d'autres : gRPC, MQTT, Steam, bases de données (MySQL, PostgreSQL, Redis, MongoDB)…

Niveau intermédiaire : le mot-clé, plus fiable qu'un code 200

C'est, à mon avis, le réglage qui apporte le plus de fiabilité. Un site peut répondre 200 OK tout en affichant une page d'erreur : « Erreur de connexion à la base de données », une page de maintenance oubliée, ou la page par défaut de l'hébergeur.

Avec une sonde HTTP(s) – Mot-clé, Uptime Kuma vérifie que la page contient bien un texte attendu, par exemple le nom du site dans le pied de page. Et pour une API, la sonde JSON Query lit une valeur précise dans la réponse :

URL       : https://api.monsite.fr/health
Requête   : status
Attendu   : ok

Les certificats HTTPS

Pour chaque sonde HTTPS, Uptime Kuma affiche la date d'expiration du certificat, et peut vous prévenir plusieurs jours avant (7, 14, 21 jours…). Même si Traefik renouvelle tout automatiquement, c'est l'alarme qui vous sauve le jour où le renouvellement échoue en silence (un enregistrement DNS modifié, une limite de Let's Encrypt atteinte).

Étape 3 : les notifications

Plus de 90 services de notification sont disponibles : e-mail, Telegram, Discord, Slack, Teams, Gotify, Ntfy, Pushover, Matrix, webhook générique… On configure une notification une fois, puis on l'active sur les sondes de son choix (ou par défaut sur toutes les nouvelles).

J'utilise Discord, comme pour Beszel : un salon #alertes sur un serveur privé, un webhook, et les notifications arrivent sur mon téléphone. Uptime Kuma envoie un message quand le service tombe, et un autre quand il revient, avec la durée de la coupure.

Éviter les fausses alertes

Une seule requête qui échoue ne veut pas dire que le site est en panne : un pic de latence, une micro-coupure réseau. Dans chaque sonde, réglez les nouvelles tentatives : par exemple 3 essais à 20 secondes d'intervalle avant de déclarer le service hors ligne. Une alerte qui sonne pour rien deux fois par semaine, c'est une alerte qu'on finit par ignorer, y compris le jour où elle est vraie.

Étape 4 : la page de statut

Uptime Kuma génère des pages de statut publiques : vous choisissez les services à afficher, les regroupez par catégorie, ajoutez un logo, et partagez l'URL. Vous pouvez même lui donner son propre domaine (statut.monsite.fr).

Pendant un incident, on y publie un message (« Ralentissements sur le paiement, nous enquêtons »). Ça évite de recevoir vingt fois la même question, et ça montre aux utilisateurs que vous êtes au courant.

Les maintenances

Une intervention prévue ? Déclarez une maintenance (ponctuelle ou récurrente, par exemple chaque dimanche de 3 h à 4 h) sur les sondes concernées. Pendant ce créneau, les alertes se taisent, et la page de statut indique « En maintenance » plutôt que « Hors ligne ».

Niveau expert

Les sondes push : surveiller ce qui ne se voit pas

C'est ma fonctionnalité préférée. Cette fois, ce n'est pas Kuma qui vérifie : c'est votre script qui appelle une URL secrète à chaque exécution réussie. Si l'appel n'arrive pas dans le délai prévu, Kuma vous alerte.

#!/bin/bash
# /usr/local/bin/backup.sh, lancé chaque nuit par cron
set -e
restic backup /srv/data
curl -fsS "https://status.monsite.fr/api/push/AbC123xYz?status=up&msg=OK" > /dev/null

Avec le set -e, si la sauvegarde échoue, le curl n'est jamais appelé. Le lendemain matin, au lieu de découvrir trois mois plus tard qu'aucune sauvegarde ne tournait, vous avez une alerte. C'est l'outil idéal pour tout ce qui tourne en arrière-plan : sauvegardes, tâches cron, synchronisations.

Surveiller les conteneurs Docker

En donnant à Kuma l'accès au socket Docker, il peut vérifier qu'un conteneur tourne, même s'il n'expose aucun port (un worker, un agent de sauvegarde) :

    volumes:
      - uptime-kuma:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro

Pour des hôtes distants, on peut aussi déclarer un hôte Docker joignable en TCP (idéalement via le réseau WireGuard plutôt qu'exposé sur Internet).

Prometheus et badges

Uptime Kuma expose ses métriques sur /metrics (protégé par une clé d'API), pour ceux qui ont déjà un Grafana. Et il génère des badges (statut, disponibilité, temps de réponse, expiration du certificat) à afficher dans un README ou une documentation.

La sécurité

Activez la double authentification dans les paramètres : c'est une interface qui connaît toute votre infra.
Placez-le derrière un reverse proxy en HTTPS (Traefik, Nginx).
Si vous montez le socket Docker, en lecture seule.

Les bonnes pratiques que j'applique

Héberger Kuma ailleurs que ce qu'il surveille. C'est la règle la plus importante. Si Kuma tourne sur le même serveur que votre site et que ce serveur tombe, Kuma tombe avec lui… et ne vous prévient de rien. Faites-le tourner sur une autre machine, idéalement chez un autre hébergeur.
Sauvegarder son volume de données : l'historique et toute la configuration des sondes y sont.
Pas de stockage NFS pour ce volume : la base SQLite n'aime pas du tout les systèmes de fichiers réseau (corruption, verrous).
Des nouvelles tentatives avant chaque alerte, pour ne pas réveiller toute l'équipe pour une micro-coupure.

À retenir

Uptime Kuma surveille vos services depuis l'extérieur. Des sondes HTTP, mot-clé, ping, Docker ou push. Des notifications vers vos outils, une page de statut publique, des maintenances pour les interventions prévues. Associé à Beszel pour l'intérieur des machines, on a une vision complète de son infra avec deux conteneurs légers.