Blog / Article #191

Uptime Kuma : la sentinelle open-source qui sauve mes week-ends (et mon homelab)

On connaît tous ça : le service qui tourne en douce, qui rend l'âme sans prévenir, et vous le découvrez des heures plus tard parce que « quelqu'un » vous le signale. Dans un homelab, c'est encore pire. Pas de service client pour vous appeler, juste votre propre frustration face à un Plex injoignable ou un Nextcloud aux abonnés absents. Pendant longtemps, je me suis dit qu'il fallait une solution simple, mais je ne trouvais rien qui me convienne vraiment.

Les outils de monitoring, j'en ai vu passer. Des usines à gaz, des trucs moches, des trucs qui coûtent un bras. Et puis, un jour, je suis tombé sur Uptime Kuma. Et là, j'ai compris que ma quête était terminée. Un tableau de bord open-source, moderne, et qui fait le job sans chichis.

Uptime Kuma, la solution que j'attendais

Uptime Kuma, c'est un peu le gardien que vous n'avez jamais eu pour votre homelab. Créé par Louis Lam en 2021, ce projet open-source est né d'un constat simple : il manquait un outil de monitoring auto-hébergé, gratuit et avec une interface utilisateur digne de ce nom. Et croyez-moi, il a réussi son pari.

Le principe est simple : il vérifie la disponibilité de vos services à intervalles réguliers et vous alerte si quelque chose ne va pas. Sites web, API, serveurs, conteneurs Docker, bases de données... la liste est longue. Et le tout, dans une interface web qui ne donne pas envie de se crever les yeux.

Installation en 5 minutes avec Docker Compose

On va pas se mentir, l'installation, c'est souvent le moment où on lâche l'affaire. Mais avec Uptime Kuma et Docker Compose, c'est d'une simplicité déconcertante. Si vous avez déjà Docker sur votre machine, vous êtes à deux doigts d'avoir votre gardien personnel en place.

Créez un fichier docker-compose.yml quelque part sur votre serveur. Par exemple, dans un dossier uptime-kuma.

services:  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3000:3001" # Le port 3000 de l'hôte vers le port 3001 du conteneur
    volumes:
      - ./data:/app/data # Pour la persistance des données
    environment:
      - TZ=Europe/Paris # N'oubliez pas de mettre votre fuseau horaire préféré

Quelques points sur cette configuration : le port 3000:3001 signifie que vous accéderez à Uptime Kuma sur le port 3000 de votre machine hôte. Le volume ./data:/app/data est crucial : c'est là que toutes les données de Uptime Kuma (la base de données SQLite, les configurations) seront stockées. Si vous perdez ce volume, vous perdez tout. Pensez à le sauvegarder régulièrement ! Et la TZ pour l'heure, un détail qui fait la différence pour les logs.

Une fois le fichier enregistré, un simple docker compose up -d dans le même répertoire et hop, Uptime Kuma est lancé en arrière-plan. Vous devriez pouvoir y accéder via http://votre-ip-serveur:3000.

Pour info, il est aussi possible de l'installer sans Docker, avec Node.js et PM2, mais franchement, pour un homelab, Docker Compose c'est le combo gagnant. Moins de dépendances à gérer, plus de simplicité.

Ajouter vos premiers moniteurs

Maintenant que Uptime Kuma tourne, le vrai fun commence : ajouter vos services à surveiller. L'interface est super intuitive. Cliquez sur 'Add New Monitor' et choisissez votre type.

Quelques exemples concrets :

1. Un site web (HTTP/HTTPS)

Le grand classique. Vous voulez savoir si votre blog ou votre Nextcloud est en ligne ?

• Type : HTTP(s)
• Friendly Name : Mon Blog
• URL : https://kadur-arnaud.fr (ou l'URL de votre service)
• Interval : 20 secondes (ou plus, selon votre besoin)

Vous pouvez même vérifier un mot-clé dans la réponse ou le certificat SSL. Pratique pour s'assurer que le contenu est bien là et que le certificat n'est pas expiré.

2. Un service interne (Port TCP)

Votre base de données MySQL ou PostgreSQL tourne-t-elle ? Votre serveur SSH est-il accessible ?

• Type : Port TCP
• Friendly Name : PostgreSQL
• Hostname : 192.168.1.50 (l'IP de votre serveur DB)
• Port : 5432 (pour PostgreSQL)

C'est un excellent moyen de s'assurer que le service sous-jacent est vivant, même si l'application web devant est plantée.

3. Un conteneur Docker (via Socket)

Pour surveiller la santé de vos conteneurs Docker directement depuis Uptime Kuma, il faut monter le socket Docker. Dans votre docker-compose.yml, ajoutez cette ligne sous la section volumes existante :

      volumes: 
             - ./data:/app/data
             - /var/run/docker.sock:/var/run/docker.sock:ro # Pour monitoring Docker

Après un docker compose restart, vous pourrez ajouter un moniteur de type Docker Container et choisir un conteneur à surveiller. Magique pour voir si votre Plex est bien 'healthy'.

4. Un script critique (Push Monitor)

Vous avez une tâche cron de sauvegarde ? Un script qui doit tourner toutes les heures ? Le 'Push Monitor' est fait pour ça. Uptime Kuma vous donne une URL unique que votre script doit appeler à chaque exécution réussie. S'il ne reçoit pas de 'ping' dans le délai imparti, il alerte. Parfait pour les processus silencieux qui ne doivent pas l'être trop longtemps.

Ne ratez plus rien : Configuration des notifications

L'intérêt d'un outil de monitoring, c'est d'être alerté. Et là, Uptime Kuma est un champion. Il supporte plus de 90 services de notification. Oui, 90. De quoi trouver votre bonheur, c'est sûr.

Personnellement, j'utilise Telegram et Discord, c'est simple, rapide et je reçois les alertes directement sur mon téléphone.

Allez dans Settings > Notifications > Add Notification. Choisissez votre service (Telegram, Discord, Email, Webhook...). Remplissez les champs nécessaires (token, chat ID, etc.). Un petit bouton 'Test' vous permet de vérifier que tout fonctionne. N'oubliez pas d'assigner cette notification à vos moniteurs.

Le piège à éviter ici : ne pas tester vos notifications. Imaginez que votre serveur tombe, et que votre canal de notification est mal configuré. Vous ne saurez rien. Toujours tester !

Un tableau de bord clair et personnalisable

Une fois vos moniteurs en place, le tableau de bord principal devient votre centre de contrôle. D'un coup d'œil, vous voyez l'état de tous vos services : vert si tout va bien, rouge si ça chauffe. L'historique des pannes est aussi accessible, avec des graphiques qui vous montrent l'uptime sur les dernières 24h, 7 jours, 30 jours...

Vous pouvez même créer des 'Status Pages' publiques. Pratique si vous hébergez des services pour des amis ou de la famille et que vous voulez leur donner un aperçu de l'état sans qu'ils aient accès à votre interface complète. C'est personnalisable avec votre logo, vos couleurs, etc. Un petit plus sympa.

Mon verdict après quelques mois d'utilisation

J'utilise Uptime Kuma depuis quelques mois maintenant (la version actuelle est la 2.5.11). Et franchement, je ne reviendrais pas en arrière. C'est simple, efficace et ça fait exactement ce que ça promet.

Les points forts : l'interface utilisateur est un vrai plaisir, l'installation Docker est un jeu d'enfant, et le nombre de types de moniteurs supportés est impressionnant. Les intégrations de notifications sont aussi un gros plus. C'est du "set it and forget it".

Les petits défauts : il ne va pas vous donner des métriques ultra-poussées comme l'utilisation CPU ou RAM de vos machines, pour ça il faut aller voir Prometheus et Grafana. C'est vraiment un outil d'uptime monitoring pur et dur. Aussi, le fait de monitorer depuis la même machine que les services peut être un problème si cette machine tombe. Une solution serait de le faire tourner sur une petite VM chez un hébergeur pas cher, juste pour avoir un point de vue externe. Mais pour un homelab, ça fait très bien le boulot.

Louis Lam a fait un travail remarquable avec Uptime Kuma. C'est un outil que je recommande chaudement à tous ceux qui, comme moi, veulent dormir sur leurs deux oreilles sans craindre la panne silencieuse. C'est simple, c'est open-source, c'est efficace. Que demander de plus ?