Uptime Kuma + Docker : monitoring en 5 min chrono

Tu as un site, une API, un petit serveur à la maison, un reverse proxy qui fait le malin... et tu veux juste savoir quand ça tombe. Pas « peut être ». Pas « j’ai un doute ». Juste un truc simple, visuel, qui te dit UP ou DOWN. Et surtout qui te prévient.

Uptime Kuma, c’est exactement ça. Et avec Docker, tu peux le mettre en route en quelques minutes, sans te lancer dans une installation pénible qui te casse tout au prochain update.

On va faire simple et concret. À la fin, tu as :

• 1 stack Docker Compose
• 1 Surveillance de tableau de bord
• 3 utilitaires de surveillance (site, API, port)
• 1 alerte qui arrive quand ça casse
• 1 vérifier HTTPS propre

Pourquoi uptime kuma (et pourquoi avec Docker)

Uptime Kuma est un outil open source d’uptime monitoring. Tu lui donnes des cibles, il les check à intervalle régulier, et il te montre un état clair. Et oui, ça ressemble un peu à UptimeRobot, mais auto hébergé, donc chez toi.

Ce qu’il sait surveiller, entre autres :

• HTTP(s) : code de statut, temps de réponse, redirections
• ping
• TCP : un port qui répond ou pas
• DNS : résolution, enregistrements
• Mot-clé : « Je veux voir le mot ok dans la réponse »
• et quelques autres modes pratiques selon les cas

Pourquoi Docker ici. Parce que c’est le combo parfait pour ce genre d’outil :

• installation rapide, identique partout
• reproductible : tu réinstalles ailleurs, c’est la même
• rollback facile : tu changes un tag d’image, tu redémarres
• isolation : ça ne pollue pas ta machine
• mises à jour propres : pull, up, terminé

Pour qui c’est fait. Clairement pour :

• Hébergement automatique, Homelab
• freelances et projets parallèles
• petites équipes
• PME qui veulent un monitoring simple sans usine à gaz

Et l’objectif de cet article, c’est pas de faire un roman sur « l’observabilité moderne ». C’est de livrer un setup qui marche. Tout de suite.

Avant de commencer : prérequis et 2 minutes de préparation

Prérequis minimum :

• une machine : VPS, NAS, Raspberry Pi, mini PC, serveur dédié
• Docker + Docker Compose (le compose v2, intégré à Docker)
• un accès SSH si c’est une machine distante

Ports :

• 3001 : interface web Uptime Kuma
• ensuite, selon ce que tu surveilles, tu n’as rien à ouvrir en plus côté Kuma. Kuma sort vers tes services. Mais si tu veux accéder au dashboard depuis l’extérieur, là oui, c’est une autre histoire.

/app/datadocker compose down

Mode d’accès :

• local uniquement : parfait si tu as un VPN, Tailscale, ou juste accès LAN
• reverse proxy : si tu veux une URL et du HTTPS propre

Petit check rapide côté Docker :

bash docker --version docker compose version

Si ces deux commandes répondent, tu es bon.

Installation express : uptime kuma avec Docker Compose (la méthode la plus simple)

On va faire ça propre. Un dossier, un fichier compose, un volume, et c’est fini.

/opt

bash sudo mkdir -p /opt/uptime-kuma cd /opt/uptime-kuma

Pourquoi un dossier projet. Parce que tu veux que ce soit clair, rangé, et facile à sauvegarder. Typiquement tu auras :

• docker-compose.yml
• data/

Ensuite on crée le fichier compose.

Exemple de docker-compose.yml minimal et propre

docker-compose.yml

yaml services: uptime-kuma: image: louislam/uptime-kuma:1 container_name: uptime-kuma ports: - "3001:3001" volumes: - ./data:/app/data restart: unless-stopped

Deux détails importants ici :

• ./data:/app/data
• restart: unless-stopped

:1:latestlatest:1

Démarrage :

bash docker compose up -d

Puis vérifie que le conteneur tourne :

bash docker ps

Accès à l’interface :

• http://IP_DE_TA_MACHINE:3001

Au premier lancement, Uptime Kuma va te demander de créer un compte admin. Fais le maintenant, et mets un vrai mot de passe.

Configuration en 5 minutes : créer ses premiers monitors (ce qui compte vraiment)

Le piège, c’est de surveiller 25 trucs inutiles et d’oublier le principal.

Priorité. Toujours :

1. le parcours utilisateur : ton site, ton app, ton endpoint public
2. les dépendances : API interne, base, reverse proxy, DNS

Objectif immédiat : 3 monitors utiles.

Monitor 1 : HTTP(s) pour ton site

Dans l’UI, bouton « add new monitor ».

• Monitor type : HTTP(s)
• PROD site https://exemple.com
• https://exemple.com
• Heartbeat interval : 60 s (pour démarrer)
• Timeout : 10 s (ou 5 s si c’est censé répondre vite)
• Accepted status codes : 200 à 299 (tu peux laisser par défaut si ça colle)

Petit conseil. Si ton site redirige HTTP vers HTTPS, surveille directement l’URL finale en HTTPS. Sinon tu peux te retrouver avec des « down » bizarres à cause des redirections.

Monitor 2 : API healthcheck + keyword

Si tu as une API, le mieux c’est un endpoint du style :

• /health
• /status
• /ready
• /live

{"status":"ok"}ok

Dans Kuma :

• Monitor type : HTTP(s) Keyword
• PROD api /health
• https://api.exemple.com/health
• ok
• Interval : 30 s ou 60 s selon ton besoin
• Timeout : 5 s à 10 s

Pourquoi keyword. Parce qu’un status code 200 ne veut pas toujours dire « tout va bien ». Tu peux avoir un 200 avec une page d’erreur HTML servie par un proxy. Keyword te sauve de ça.

Monitor 3 : TCP pour un port critique

Tu veux vérifier qu’un port répond. Typiquement :

• 443 : reverse proxy ou service HTTPS
• 5432 : Postgres
• 6379 : Redis
• 22 : SSH (pas toujours utile, mais parfois)

Dans Kuma :

• Monitor type : TCP Port
• PROD infra tcp 443
• exemple.com
• 443
• Interval : 60 s
• Timeout : 5 s

Ça ne teste pas « l’app fonctionne », ça teste « quelque chose répond sur ce port ». C’est complémentaire, pas un remplacement du check HTTP.

3 monitors « templates » à copier (site, API, base/port)

Tu peux reprendre ces modèles tels quels.

1) Site vitrine

• Type : HTTP(s)
• PROD site https://tondomaine.tld
• https://tondomaine.tld
• Intervalle : 60 s
• Timeout : 10 s
• Codes attendus : 200 à 299

2) API

• Type : HTTP(s) Keyword
• PROD api https://api.tondomaine.tld/health
• https://api.tondomaine.tld/health
• ok
• Intervalle : 60 s
• Timeout : 5 s

3) Infra port

• Type : TCP Port
• PROD tcp tondomaine.tld:443
• tondomaine.tld
• 443
• Intervalle : 60 s
• Timeout : 5 s

Si tu hésites sur quoi surveiller en premier, surveille ce que ton utilisateur fait. La page d’accueil, la page de login, l’endpoint qui sert l’app. Après seulement, le reste.

Alertes : recevoir une notification dès qu’un service tombe

Un dashboard sans alertes, c’est joli. Mais inutile.

Tu ne vas pas ouvrir Kuma toutes les 10 minutes pour vérifier que tout va bien. Donc il faut une notification.

Canaux populaires :

• email via SMTP
• Telegram
• Discord
• Slack
• Gotify
• webhook (souvent le plus flexible)

Dans Uptime Kuma : section « notifications », puis « setup notification ».

Je ne vais pas te faire 15 tutos différents ici. Le principe est toujours le même :

• tu ajoutes un canal
• tu testes l’envoi
• tu l’associes à tes monitors

Dans la plupart des cas, Telegram ou Discord, c’est le plus rapide. Email marche très bien aussi, mais nécessite un SMTP fiable.

Nommage des monitors, détail qui change tout. Ajoute des préfixes :

• PROD
• STAGING
• WEBAPIINFRA

PROD WEB https://exemple.comPROD API /health

Quand tu reçois l’alerte à 3 h du matin, tu veux comprendre en 2 secondes ce qui est cassé.

Réglages anti-spam et messages actionnables

Deux trucs à régler pour ne pas te faire détester par ton propre monitoring :

• retries : évite d’alerter au premier faux négatif
• intervalle d’alerte : selon le canal, tu peux éviter de spammer toutes les minutes

Un réglage raisonnable :

• considérer « down » après 2 ou 3 échecs consécutifs
• vérifier toutes les 60 secondes
• timeout pas trop agressif (si tu mets 1 s, tout va « down » un jour ou l’autre)

Et dans le message, assure toi d’avoir :

• nom du service
• URL ou host:port
• statut (down, up)
• timestamp
• lien vers ton dashboard

Kuma fait déjà une bonne partie de ça, donc surtout, teste les notifications. Vraiment. Clique sur « test » et vérifie que tu reçois bien quelque chose.

Rendre l’accès propre et sécurisé (sans compliquer)

Le minimum vital :

• compte admin avec mot de passe fort
• ne pas exposer l’UI publiquement si tu n’en as pas besoin

Option A, la plus simple, et franchement la meilleure pour beaucoup de gens :

• accès local uniquement
• via VPN, Tailscale, WireGuard, ou juste le réseau interne

3001

https://status.tondomaine.tld

Points d’attention :

• Uptime Kuma utilise des websockets pour l’UI temps réel
• ton proxy doit les laisser passer
• et évidemment tu veux le TLS géré par le proxy, pas par Kuma

Option rapide : mettre uptime kuma derrière un reverse proxy

Principe :

• Kuma écoute en interne sur 3001
• le reverse proxy termine le HTTPS, gère le certificat, et redirige vers Kuma

Infos dont tu as besoin :

• status.tondomaine.tld
• 3001
• HostX-Forwarded-Proto

Que tu sois sur Traefik ou Nginx, la logique est la même. Si ton UI charge mais ne se met jamais à jour, ou si tu vois des erreurs websocket, c’est souvent là que ça coince.

Et si tu veux rester tranquille. Fais simple : accès via VPN. Ça règle 90 pour cent des soucis.

Ajouter une status page (utile pour soi… et pour les utilisateurs)

Uptime Kuma peut publier une status page. C’est une page qui agrège des monitors et affiche l’état global.

Tu peux la faire :

• publique : si tu as un produit, des clients, une communauté
• privée : juste pour ton équipe, ou toi, ou un lien non listé

Dans Kuma : « status pages », puis « new status page ».

Tu peux :

• changer le titre
• ajouter un logo
• associer des monitors
• WebAPIInfra

Le truc cool : tu peux regrouper intelligemment. Exemple :

• Web : site, app front
• API : healthcheck, endpoint principal
• Infra : reverse proxy, base, DNS

Et tu peux activer un badge de statut, pratique pour un README GitHub ou une doc interne.

Quand la publier. Si tu as des utilisateurs externes, ça évite 50 messages du type « c’est down chez moi ». Et côté interne, ça évite aussi le flou.

Maintenance : mises à jour, sauvegardes et migration sans stress

Bonne nouvelle. La maintenance d’Uptime Kuma en Docker, c’est simple.

Mettre à jour :

bash cd /opt/uptime-kuma docker compose pull docker compose up -d

louislam/uptime-kuma:1

Sauvegardes. Le point crucial.

./data

Exemples simples :

• backup via rsync
• snapshot VPS
• sauvegarde NAS
• ou même un zip régulier si tu fais ça en mode artisanal

Après une mise à jour, fais un mini check :

• est ce que Kuma démarre
• est ce que 1 ou 2 monitors critiques sont OK
• est ce que la notification de test marche

Checklist maintenance mensuelle (5 minutes)

Une fois par mois, fais juste ça :

1. docker compose pull
2. docker compose up -d
3. test notification (bouton « test »)
4. vérifie 1 ou 2 monitors critiques
5. data/

C’est bête, mais c’est exactement ce qui évite les surprises.

Erreurs fréquentes (et comment les résoudre vite)

Quelques classiques. Et comment tu t’en sors sans y passer la nuit.

Port 3001 déjà utilisé

Symptôme : le conteneur ne démarre pas, erreur de binding.

Solution : change le mapping.

yaml ports:

• "3002:3001"

http://IP:3002

Données perdues après redémarrage

Symptôme : tu redémarres, plus de monitors.

Cause : pas de volume monté, ou mauvais chemin.

Solution : vérifie ton compose :

• ./data:/app/data
• data/

Monitors en down alors que le service marche

Ca arrive. Souvent c’est un détail :

• DNS différent depuis le conteneur
• proxy qui redirige ou bloque
• TLS : certificat invalide ou chaîne incomplète
• firewall : la machine qui héberge Kuma n’a pas accès à la cible
• redirections HTTP vers HTTPS mal gérées

Astuce rapide : teste depuis la machine hôte.

bash curl -I https://exemple.com curl -s https://api.exemple.com/health

Et si la cible est interne, vérifie la résolution DNS et la route réseau depuis le serveur Kuma, pas depuis ton PC.

Notifications qui ne partent pas

Ca aussi c’est fréquent.

• mauvais token, mauvais webhook
• restrictions réseau sortant (VPS verrouillé, règles firewall)
• DNS sortant cassé

Solution : utilise le bouton « test ». Et regarde les logs du conteneur :

bash docker logs uptime-kuma --tail 200

Latence, timeout, faux down

Si tu mets un timeout trop bas, tu vas générer des faux positifs.

• intervalle trop agressif
• serveur saturé
• endpoint lent

Solution : augmente un peu le timeout. Et surveille le temps de réponse moyen affiché par Kuma, c’est une info simple mais super utile.

Conclusion : le combo moderne pour un monitoring simple et fiable

En pratique, le setup minimal qui change tout, c’est :

• Docker Compose
• 3 monitors : site, API, port
• 1 notification active

Et tu as déjà un monitoring opérationnel en 5 minutes. Pas « demain ». Pas « quand j’aurai le temps ». Maintenant.

Prochaine étape logique, si tu veux améliorer sans te compliquer :

• mettre Kuma derrière un reverse proxy avec HTTPS
• publier une status page si tu as des utilisateurs
• ajouter des checks plus fins : keyword, DNS, endpoints critiques

Et garde une routine simple : mise à jour et backup. C’est ça qui rend l’ensemble fiable sur la durée.

Action simple pour finir. Installe Uptime Kuma maintenant, puis ajoute ton service le plus critique en premier. Le truc qui, s’il tombe, te coûte vraiment quelque chose. Le reste viendra tout seul.

Questions fréquemment posées

Qu'est-ce qu'Uptime Kuma et à quoi sert-il ?

Uptime Kuma est un outil open source d'uptime monitoring auto-hébergé qui permet de surveiller l'état de vos sites, API ou serveurs en temps réel. Il vous indique simplement si vos services sont UP (en ligne) ou DOWN (hors ligne) et vous prévient immédiatement en cas de problème.

Pourquoi utiliser Docker pour installer Uptime Kuma ?

Docker facilite grandement l'installation et la gestion d'Uptime Kuma grâce à une installation rapide, reproductible et isolée. Avec Docker Compose, vous pouvez déployer un stack complet en quelques minutes, bénéficier de mises à jour propres, et effectuer des rollbacks facilement sans polluer votre machine hôte.

Quels types de services peut-on surveiller avec Uptime Kuma ?

Uptime Kuma peut surveiller plusieurs types de services tels que HTTP(s) (avec vérification du code status, temps de réponse, redirections), ping, TCP (ports), DNS (résolution et enregistrements), ainsi que la présence de mots-clés spécifiques dans les réponses. Cela couvre la plupart des besoins courants en monitoring.

Quels sont les prérequis pour installer Uptime Kuma avec Docker Compose ?

Il vous faut une machine (VPS, NAS, Raspberry Pi, mini PC ou serveur dédié) avec Docker et Docker Compose installés (compose v2 intégré à Docker). Un accès SSH est nécessaire si la machine est distante. Le port 3001 doit être disponible pour accéder à l'interface web d'Uptime Kuma.

Comment assurer la persistance des données dans Uptime Kuma avec Docker ?

Pour ne pas perdre vos configurations, monitors et notifications au redémarrage du conteneur, il est essentiel de monter un volume Docker qui mappe le dossier local ./data vers /app/data dans le conteneur. Sans ce volume persistant, toutes les données seraient perdues lors d'un arrêt ou redéploiement.

Comment accéder à l'interface web d'Uptime Kuma depuis l'extérieur ?

Par défaut, Uptime Kuma écoute sur le port 3001 localement. Pour un accès externe sécurisé, il est recommandé d'utiliser un reverse proxy configuré avec HTTPS afin d'exposer l'interface via une URL publique sécurisée. Sinon, l'accès peut être limité au réseau local ou via VPN/Tailscale.