Uptime Kuma

À quoi ça sert

Tu déploies une API, un site, une base de données. Tout marche le jour où tu lances. Trois semaines plus tard, le serveur a redémarré, le certificat SSL a expiré, ou ton conteneur s'est crashé en silence. Tu t'en aperçois… quand un utilisateur te le signale.

Uptime Kuma règle ça avec quatre briques :

• Monitors — chaque service à surveiller (URL HTTP, port TCP, ping, DNS, conteneur Docker, certificat SSL…). Un check configurable toutes les n secondes.
• Notifications — plus de 90 canaux supportés : e-mail, Discord, Slack, Telegram, webhook, ntfy, SMS…
• Status pages — une page publique (par ex. status.tonprojet.fr) qui montre l'état de chaque service, avec historique. Tu la partages aux utilisateurs.
• Maintenance windows — pour ne pas être spammé pendant que tu déploies.

Un exemple d'usage

Tu as déployé ton API FastAPI sur https://api.monprojet.fr et un dashboard Streamlit sur https://demo.monprojet.fr. Tu veux :

• vérifier que les deux répondent en HTTP 200 toutes les minutes ;
• recevoir une notif Discord si une URL ne répond plus pendant 2 minutes d'affilée ;
• une page publique status.monprojet.fr partageable avec ta promo, qui montre l'état des deux en temps réel.

Avec Uptime Kuma, ces trois choses se font en cliquant dans l'UI, sans écrire une ligne de code. Total : 10 minutes.

How-to : installer et utiliser Uptime Kuma

1. Lancer Uptime Kuma avec Docker

   Un seul conteneur, une seule commande :

   bash Copier

   docker run -d --name uptime-kuma \
     -p 3001:3001 \
     -v uptime-kuma-data:/app/data \
     --restart unless-stopped \
     louislam/uptime-kuma:1

   Le volume uptime-kuma-data garde tes monitors et ton historique : ne l'oublie pas, sinon tout disparaît au prochain docker rm. Ouvre http://localhost:3001 et crée le compte admin (gardé en local, dans une SQLite, pas envoyé sur internet).

   Épingle la version majeure

   Utilise louislam/uptime-kuma:1 plutôt que :latest. La v2 introduit des changements de schéma ; mieux vaut décider toi-même quand tu migres.

2. Avec docker-compose (recommandé)

   Si tu as déjà un docker-compose.yml pour ton projet, ajoute Uptime Kuma à côté :

   yaml Copier

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

   docker compose up -d uptime-kuma et c'est prêt.

3. Créer ton premier monitor

   Dans l'UI, clique Add New Monitor. Les champs qui comptent vraiment :

   • Monitor Type — HTTP(s) pour une URL, TCP Port pour une base de données ou un broker, Ping pour une machine, Docker Container pour un conteneur local.
   • Friendly Name — ce que tu veux voir dans l'UI.
   • URL — ex. https://api.monprojet.fr/health. Pointe vers un endpoint léger, pas la home complète.
   • Heartbeat Interval — 60 s par défaut, tu peux descendre à 20 s.
   • Retries — combien de checks ratés avant de déclarer l'incident. 2 ou 3 évite les fausses alertes.
   Endpoint /health

   Sur ton API FastAPI, ajoute une route ultra-simple : @app.get("/health") def health(): return {"ok": True}. C'est elle que tu monitores : pas de logique métier, pas de base de données touchée, donc un check rapide et fiable.

4. Brancher une notification

   Menu Settings → Notifications → Setup Notification. Choisis ton canal — Discord est le plus simple pour démarrer :

   1. Sur ton serveur Discord : Paramètres du salon → Intégrations → Webhooks → Nouveau webhook, copie l'URL.
   2. Dans Uptime Kuma, colle l'URL dans le champ Discord Webhook URL, donne un nom, Test pour vérifier, puis Save.
   3. Coche Default enabled pour qu'elle s'applique automatiquement à tous les nouveaux monitors.

   Maintenant, dès qu'un monitor passe en DOWN pendant le nombre de retries configuré, tu reçois un message. Idem au retour en UP.

5. Créer une page de statut publique

   Menu Status Pages → New Status Page. Donne-lui un slug (ex. monprojet) — l'URL publique sera http://localhost:3001/status/monprojet. Choisis les monitors à afficher, range-les en groupes (« API », « Front », « Base de données »), et coche Published.

   La page montre pour chaque service : statut courant, uptime % sur 24 h / 30 j, et un graphe de l'historique. Aucune authentification requise — pratique à partager.

6. Mettre une fenêtre de maintenance

   Avant un déploiement prévu : menu Maintenance → New Maintenance. Tu choisis les monitors concernés, la durée (ponctuelle ou récurrente), et pendant ce créneau les checks sont ignorés et la page de statut affiche « Under Maintenance ». Pas de fausse alerte Discord à 22 h.

7. Surveiller des services internes (Docker)

   Pour qu'Uptime Kuma puisse joindre tes autres conteneurs par leur nom (ex. http://api:8000/health), mets-les sur le même réseau Docker. Avec un docker-compose.yml commun, c'est automatique.

   Pour monitorer le statut d'un conteneur (« est-il en cours d'exécution ? ») sans HTTP, utilise le type Docker Container : Uptime Kuma se branche sur le socket Docker. Il faut alors monter /var/run/docker.sock dans le conteneur Uptime Kuma (attention, ça donne un accès large à Docker — à n'utiliser qu'en local ou sur ta machine perso).

8. Sauvegarder ses monitors

   Menu Settings → Backup → Export télécharge un JSON avec tous tes monitors et leurs réglages. Commit-le (sans tokens sensibles !) ou garde-le ailleurs : si le volume Docker disparaît, Import tout remettra en place en quelques secondes.

Aide-mémoire

# Lancer
docker run -d --name uptime-kuma -p 3001:3001 \
  -v uptime-kuma-data:/app/data --restart unless-stopped \
  louislam/uptime-kuma:1

# Logs
docker logs -f uptime-kuma

# Mettre à jour (épinglé sur la v1)
docker pull louislam/uptime-kuma:1
docker stop uptime-kuma && docker rm uptime-kuma
# puis relancer la commande run avec le même volume

HTTP(s)            # une URL, code de retour 2xx
HTTP Keyword       # vérifie qu'un mot précis est dans la réponse
HTTP JSON Query    # cible un champ JSON (ex. {"status":"ok"})
TCP Port           # une base, un broker
Ping               # ICMP vers une machine
DNS                # résolution d'un nom
Docker Container   # conteneur en cours d'exécution
Push (Heartbeat)   # c'est le job qui ping Uptime Kuma (cron, batch)

Uptime Kuma et le reste de l'écosystème

• Prometheus + Grafana — voir l'encart en haut de page. Uptime Kuma répond à « ça marche ? », Prometheus/Grafana à « ça marche bien ? ». Bonus : Uptime Kuma expose une API /metrics compatible Prometheus depuis la v1.18, donc tu peux aussi tracer son uptime dans Grafana.
• Docker — un seul conteneur, un volume, c'est l'installation officielle. Idéal pour intégrer dans un docker-compose.yml de projet.
• Kubernetes — un Helm chart communautaire existe, mais sur un cluster en prod on préfère souvent l'opérateur kube-prometheus-stack + blackbox exporter pour les checks HTTP, qui s'intègre mieux à l'écosystème.
• FastAPI — ajoute une route /health légère et pointe Uptime Kuma dessus. Pour aller plus loin, fais un check qui teste la base de données et renvoie 503 si elle ne répond pas — Uptime Kuma le détectera comme un DOWN.
• CI/CD — utilise un monitor de type Push pour vérifier qu'un job batch (ré-entraînement, export quotidien) tourne bien. Le job fait un curl https://kuma/api/push/<token> à la fin ; Uptime Kuma s'attend à recevoir ce ping toutes les n heures et alerte sinon.
• MLflow — surveille simplement l'URL de ton MLflow server avec un monitor HTTP. Utile si toute ton équipe en dépend pour logger ses runs.

Pour aller plus loin

• Site officiel : uptime.kuma.pet
• Démo en ligne : demo.uptime.kuma.pet
• Repo GitHub : github.com/louislam/uptime-kuma
• Documentation : le wiki du repo