Uptime Kuma : surveiller vos services avec Docker et intégrations avancées

Une application peut sembler active alors que son site ne répond plus, qu’une API est bloquée ou qu’un certificat HTTPS approche de l’expiration. Avec Uptime Kuma et Docker, vous pouvez mettre en place une surveillance de services auto-hébergée, recevoir des alertes ciblées et publier le statut de vos services, sans déployer une plateforme de monitoring complexe.

Uptime Kuma et Docker : à quoi sert la surveillance de services ?

Uptime Kuma est un outil libre de monitoring que vous hébergez sur votre propre serveur. À intervalles réguliers, il vérifie si une ressource répond : page web, API, port réseau, nom de domaine ou tâche automatisée. Si le résultat ne correspond pas aux attentes, il peut envoyer des alertes par différents canaux.

Cette vérification apporte un repère concret : un conteneur peut être « en marche » alors que l’application qu’il contient ne répond plus. Une petite boutique en ligne, par exemple, peut surveiller sa page d’accueil en HTTP et son service de paiement avec une sonde TCP. Elle repère ainsi plus vite la différence entre un site accessible et un service réellement fonctionnel.

Contrairement à une offre hébergée, l’auto-hébergement laisse les données de surveillance sur votre infrastructure et évite de dépendre d’un abonnement pour ajouter des moniteurs. En contrepartie, il faut maintenir l’instance, la protéger et prévoir ses sauvegardes. L’outil convient particulièrement aux homelabs, sites indépendants et petites infrastructures.

Quels services Uptime Kuma peut-il surveiller ?

Chaque contrôle, appelé moniteur, correspond à une cible et à une méthode de vérification. HTTP(S) teste une URL, TCP vérifie si un port accepte une connexion, tandis que DNS permet de contrôler la résolution d’un domaine. Ping mesure la réponse d’un hôte, et le contrôle par mot-clé peut détecter une page d’erreur qui renvoie malgré tout un code HTTP normal.

• HTTP(S) : vérifiez une page, une API ou un point de santé applicatif.
• TCP : testez un port de base de données, de messagerie ou SSH.
• DNS : comparez la réponse d’un domaine à la valeur attendue.
• Push : faites envoyer un signal périodique par un script ou une tâche planifiée.
• Docker : suivez l’état d’un conteneur, en tenant compte des risques liés au socket Docker.

Le choix du contrôle dépend de ce que vous voulez réellement valider. Pour une API, vérifier qu’un port répond ne garantit pas que les données renvoyées sont correctes ; un test HTTP sur une route de santé ou une vérification de contenu apporte alors une information plus pertinente.

Installer Uptime Kuma avec Docker Compose

Docker Compose permet de décrire le service dans un fichier de configuration et de le relancer de manière prévisible. Avant de commencer, vérifiez que Docker et le plugin Docker Compose sont disponibles sur le serveur, qu’un espace de stockage est réservé aux données et que le port choisi n’est pas déjà utilisé.

Créez un répertoire dédié, par exemple uptime-kuma, puis préparez un fichier compose.yaml. Il doit définir le service à partir de l’image officielle Uptime Kuma, publier le port 3001 et monter un répertoire local, tel que ./data, vers /app/data. Ce volume conserve la configuration lorsque le conteneur est remplacé.

1. Créez le dossier de travail avec la commande mkdir -p ~/uptime-kuma, puis placez-vous dedans avec cd ~/uptime-kuma.
2. Dans le fichier Compose, configurez le port sous la forme 3001:3001, le volume ./data:/app/data et une règle de redémarrage automatique telle que unless-stopped.
3. Lancez le service avec docker compose up -d, puis contrôlez son état avec docker compose ps.
4. Ouvrez http://adresse-du-serveur:3001 sur un réseau de confiance et créez le compte administrateur.

Pour un déploiement durable, choisissez une version publiée de l’image et consultez les notes de mise à jour avant de changer de version. Évitez de publier directement l’interface d’administration sur Internet en HTTP : un accès distant devrait passer par HTTPS et un proxy inverse correctement configuré.

Élément	Réglage courant	Rôle
Port du conteneur	3001	Accéder à l’interface web
Volume de données	./data vers /app/data	Préserver la configuration et l’historique
Redémarrage	unless-stopped	Relancer le service après un redémarrage du serveur
Proxy inverse	Nginx, Caddy ou équivalent	Gérer HTTPS et l’accès par nom de domaine

Un lancement avec docker run est possible pour un test rapide, en publiant le port et en montant un volume persistant. Compose reste généralement plus pratique dès que l’installation doit être maintenue ou intégrée à d’autres services.

Réglages initiaux à vérifier après l’installation

Après la création du compte, vérifiez le fuseau horaire et l’adresse principale de l’instance. Le fuseau horaire rend les historiques d’incidents plus faciles à lire ; l’adresse principale permet d’insérer des liens cohérents dans les notifications et les pages de statut.

Choisissez un mot de passe robuste et activez l’authentification à deux facteurs si elle est disponible dans votre version. Si l’interface est placée derrière un proxy inverse, configurez les paramètres de proxy avec prudence : les en-têtes transmis doivent provenir de votre proxy de confiance, et non d’une source arbitraire.

Un intervalle de contrôle d’une minute constitue souvent un point de départ raisonnable pour les services ordinaires. Réservez des vérifications plus fréquentes aux fonctions réellement critiques : multiplier les sondes rapprochées augmente l’activité, le volume d’historique et le risque d’alertes déclenchées par une simple variation temporaire du réseau.

Configurer les moniteurs, alertes et intégrations avancées

Commencez par ajouter un moniteur HTTP(S) pour un site ou une API. Attribuez-lui un nom explicite, indiquez l’URL complète et définissez les codes de réponse attendus. Pour une page qui renvoie une erreur personnalisée avec un code 200, ajoutez si nécessaire un contrôle de mot-clé ou utilisez une route de santé dédiée.

Les paramètres avancés permettent de limiter les faux positifs. Plusieurs nouvelles tentatives avant de déclarer un service indisponible peuvent éviter qu’un bref pic de latence ne déclenche immédiatement une alerte. Les groupes, comme « Production », « API » ou « Outils internes », gardent le tableau de bord lisible à mesure que le nombre de contrôles augmente.

Recevoir des notifications sur Telegram, Discord, Slack ou par courriel

Uptime Kuma propose de nombreuses intégrations de notifications : messageries, courriel SMTP, applications mobiles et webhooks. Telegram et Discord sont pratiques pour une équipe réduite ; Slack ou Microsoft Teams peuvent mieux s’intégrer à un espace de travail existant. Les options disponibles évoluent selon les versions : consultez la liste dans votre interface avant de choisir un canal.

Dans les paramètres, créez le canal voulu et fournissez les informations demandées, comme l’URL d’un webhook Discord ou le jeton d’un bot Telegram. Envoyez un message de test avant d’associer le canal à vos moniteurs. Une notification de test confirme le trajet entre Uptime Kuma et la plateforme, sans garantir à elle seule que toutes les règles d’alerte sont adaptées.

Pour éviter qu’une panne générale ne provoque une rafale de messages, configurez les notifications en fonction des services concernés et des personnes qui doivent intervenir. Un canal d’équipe peut recevoir les alertes de production, tandis que les contrôles moins urgents restent visibles dans le tableau de bord.

Publier le statut des services sans exposer l’administration

Une page de statut rassemble les informations de disponibilité que vous choisissez de rendre visibles. Elle peut aider les utilisateurs à vérifier si un site ou une API rencontre un incident, plutôt que de contacter le support pour chaque interruption. Organisez les contrôles en groupes et ne publiez que ceux qui peuvent être communiqués.

La page publique doit être distincte de l’interface d’administration, protégée par son propre accès et idéalement servie en HTTPS. Pensez aussi à vérifier les réglages d’indexation : un tableau de statut destiné à des clients n’a pas nécessairement vocation à apparaître dans les résultats d’un moteur de recherche.

Pour les tâches planifiées, un moniteur de type Push suit une logique différente : le script envoie périodiquement un signal à Uptime Kuma. Si le signal attendu n’arrive pas dans le délai configuré, une alerte peut être générée. C’est utile, par exemple, pour repérer un export nocturne qui ne s’est pas exécuté.

Sécuriser et maintenir une instance Uptime Kuma

L’installation est légère, mais elle reste un service d’administration. Pour un accès depuis l’extérieur, placez-la derrière un proxy inverse configuré en HTTPS et vérifiez qu’il prend en charge les connexions WebSocket nécessaires à l’actualisation de l’interface. Gardez également le système, Docker et l’image Uptime Kuma à jour.

Le socket Docker : une intégration à manier avec précaution

Le moniteur de conteneurs peut nécessiter l’accès à /var/run/docker.sock. Or ce socket donne au conteneur accès au démon Docker, qui peut alors permettre des actions très étendues sur l’hôte. Le montage avec le suffixe :ro ne constitue pas une protection suffisante : il ne restreint pas les commandes envoyées au démon par cette interface.

Avant d’activer cette fonction, évaluez le risque pour votre serveur. Si vous souhaitez seulement savoir si une application répond, un contrôle HTTP ou TCP sur le service rendu peut suffire. Pour un accès au démon, un proxy de socket limitant les opérations autorisées est préférable à un accès direct lorsque votre environnement le permet.

Sauvegarder les données et planifier les mises à jour

La configuration, les moniteurs et l’historique sont conservés dans les données persistantes de l’instance. Sauvegardez régulièrement le répertoire monté sur /app/data vers un autre emplacement, puis vérifiez que la copie peut être restaurée. Une sauvegarde stockée uniquement sur le même disque ne protège pas d’une panne de ce disque.

Avec Compose, la mise à jour suit généralement deux étapes : récupérer l’image choisie, puis recréer le conteneur avec docker compose pull et docker compose up -d. Avant une mise à jour importante, consultez les notes de version et réalisez une sauvegarde ; après le redémarrage, vérifiez l’état du conteneur et ses journaux avec docker compose logs.

Avant une intervention planifiée, utilisez une fenêtre de maintenance pour les moniteurs concernés si cette fonction est disponible dans votre version. Vous éviterez ainsi de traiter comme une panne réelle les interruptions provoquées par une mise à jour ou une migration volontaire.

Limites du monitoring auto-hébergé et bonnes pratiques

Uptime Kuma observe les services depuis le point où il est installé. Si le serveur qui l’héberge tombe, il ne peut plus vous prévenir par lui-même ; il est donc judicieux de le placer à part des services surveillés ou de prévoir un contrôle externe complémentaire pour son propre accès.

Une instance unique ne fournit pas à elle seule une surveillance depuis plusieurs régions géographiques. Elle convient bien à de nombreux usages personnels et à des infrastructures de taille modeste, mais une organisation qui doit comparer la disponibilité depuis plusieurs pays ou gérer des rôles avancés peut avoir besoin d’outils complémentaires.

Enfin, un statut « en ligne » ne prouve pas toujours que l’expérience utilisateur est satisfaisante. Complétez les contrôles de disponibilité par des tests adaptés à vos enjeux : réponse d’une API, présence d’un contenu attendu ou bon fonctionnement d’une tâche automatisée. La qualité du suivi dépend autant de la question posée que de l’outil choisi.

• Commencez par les services essentiels : surveillez le site, l’API et les dépendances dont ils ont besoin.
• Testez chaque notification : vérifiez la réception avant de compter sur elle en situation réelle.
• Protégez l’accès : privilégiez HTTPS, un mot de passe robuste et une authentification renforcée.
• Gardez une copie restaurable : sauvegardez les données en dehors du serveur hébergeant Uptime Kuma.
• Réduisez les faux positifs : adaptez les intervalles et les nouvelles tentatives à la criticité du service.

Un dispositif de surveillance utile ne cherche pas à tout contrôler de la même manière : il rend visibles les pannes importantes et aide à réagir sans multiplier les alertes inutiles.

Uptime Kuma est-il gratuit ?

Oui, Uptime Kuma est un logiciel libre que vous pouvez auto-héberger. Il n’y a pas de forfait de service à payer pour l’utiliser, mais l’hébergement, la maintenance et les sauvegardes restent à votre charge.

Docker Compose est-il nécessaire pour installer Uptime Kuma ?

Non. Une commande Docker peut suffire pour un essai rapide. Docker Compose facilite toutefois la gestion de la configuration, des volumes persistants et des mises à jour.

Quels services peut-on surveiller avec Uptime Kuma ?

Selon le type de moniteur, vous pouvez vérifier des sites et API HTTP(S), des ports TCP, des réponses DNS, des hôtes par Ping, des conteneurs Docker ou des tâches qui envoient un signal Push.

Peut-on recevoir les alertes sur Telegram ou Discord ?

Oui. Uptime Kuma propose des intégrations de notifications, notamment Telegram et Discord. Configurez les identifiants ou le webhook requis, puis envoyez un test avant d’associer le canal aux moniteurs.

Le montage du socket Docker en lecture seule est-il sûr ?

Non, le suffixe :ro ne limite pas suffisamment les commandes envoyées au démon Docker. Ce montage peut donner au conteneur des capacités importantes sur l’hôte ; préférez un proxy de socket à permissions limitées ou un contrôle HTTP ou TCP lorsque cela répond au besoin.