Superviser ses services avec Uptime Kuma
Installez Uptime Kuma avec Docker Compose sur Debian ou Ubuntu, protégez son accès en HTTPS, créez vos sondes et notifications, puis gérez les mises à jour et les sauvegardes.
Sur cette page
Vos valeurs
Renseignez-les une fois, les commandes du guide se mettent à jour.
Uptime Kuma est un outil de supervision auto-hébergé. Il contrôle régulièrement vos sites, ports et services, conserve l'historique de leur disponibilité et vous prévient en cas de panne.
À la fin de ce guide, Uptime Kuma tourne dans Docker, n'écoute que sur l'adresse locale du serveur et répond en HTTPS derrière Caddy, avec un accès protégé. Vous avez créé une première sonde et une notification, et vous savez mettre à jour et sauvegarder l'instance.
Commander un serveur
Ce guide s'applique aux serveurs que vous administrez vous-même :
Prérequis
- Un serveur sous Debian 12 ou 13, ou Ubuntu 22.04 ou 24.04
- Un accès SSH avec un utilisateur disposant de
sudo - Docker Engine et Docker Compose, installés avec le guide Installer Docker Engine et Docker Compose
- Caddy, installé avec le guide Caddy en reverse proxy
- Un enregistrement A pour
uptime.votre-domaine.comversVOTRE_IP_SERVEUR - Un disque local pour les données : les partages réseau comme NFS ne sont pas pris en charge
Les commandes docker supposent que votre utilisateur appartient au groupe docker. Sinon, ajoutez sudo devant.
Ce guide utilise la version 2.5.12, la dernière version stable au moment de la rédaction. Contrôlez la version actuelle sur la page des versions d'Uptime Kuma. La branche 3 est encore en bêta : ne l'utilisez pas en production.
Ports utilisés
| Port | Sens | Rôle | À ouvrir |
|---|---|---|---|
| 80/tcp | Entrant | Certificat et redirection vers HTTPS, via Caddy | Oui |
| 443/tcp | Entrant | Accès HTTPS, via Caddy | Oui |
| 3001/tcp | Local | Interface d'Uptime Kuma, sur 127.0.0.1 |
Non |
Le serveur doit aussi pouvoir joindre, en sortie, les services surveillés et vos services de notification.
Étape 1 : créer le projet Compose
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yamlCollez cette configuration :
services:
uptime-kuma:
image: louislam/uptime-kuma:2.5.12
container_name: uptime-kuma
restart: unless-stopped
ports:
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/dataDémarrez le conteneur :
docker compose config --quiet
docker compose up -d
docker compose psLe conteneur doit apparaître comme démarré (Up). Son contrôle de santé peut rester à l'état starting pendant les premières minutes.
Étape 2 : créer le compte par un tunnel SSH
Le premier visiteur crée le compte administrateur. Faites-le donc avant de publier le site. Dans un terminal sur votre poste :
ssh -N -L 3001:127.0.0.1:3001 VOTRE_USER@VOTRE_IP_SERVEURLa commande reste active sans rien afficher. Ouvrez ensuite http://localhost:3001, puis :
- Choisissez votre langue.
- Sélectionnez la base SQLite, adaptée à une installation de taille modeste.
- Patientez pendant la préparation de la base.
- Créez le compte administrateur avec un mot de passe long et unique.
Étape 3 : renforcer le compte
Dans Settings (Paramètres) :
| Section | Réglage | Valeur |
|---|---|---|
| Security | 2FA Settings | Activez la double authentification avec une application TOTP |
| Security | Disable Auth | Ne l'activez pas |
| Reverse Proxy | Trust Proxy | Yes, car le service n'est joignable que par Caddy |
Trust Proxy permet d'afficher la véritable adresse des visiteurs dans les journaux. N'activez cette option que si le port 3001 reste limité à 127.0.0.1.
Étape 4 : publier l'interface avec Caddy
Choisissez le mode adapté à votre usage.
Accès restreint à votre adresse (recommandé)
Seule votre adresse IP atteint l'interface. Les URL /api/push/ restent accessibles, pour que vos tâches planifiées puissent envoyer leurs signaux. Ajoutez ce site dans /etc/caddy/Caddyfile :
uptime.votre-domaine.com {
@push path /api/push/*
@allowed client_ip VOTRE_IP
handle @push {
reverse_proxy 127.0.0.1:3001
}
handle @allowed {
reverse_proxy 127.0.0.1:3001
}
handle {
abort
}
}Si votre adresse change souvent, passez plutôt par WireGuard ou Tailscale.
Accès public avec page de statut
Une page de statut doit rester visible par vos utilisateurs. Dans ce cas, l'interface de connexion est elle aussi accessible : la double authentification de l'étape 3 devient indispensable.
uptime.votre-domaine.com {
reverse_proxy 127.0.0.1:3001
}Appliquer la configuration
Caddy transmet seul les WebSockets dont Uptime Kuma a besoin. Caddy étant installé sur le serveur et non dans Docker, UFW s'applique à ses ports :
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddyVérifier le résultat
Vous pouvez fermer le tunnel avec Ctrl+C. Ouvrez https://uptime.votre-domaine.com : la page de connexion doit s'afficher avec un certificat valide. Sur le serveur, contrôlez le port :
docker ps --filter name=uptime-kuma --format '{{.Names}} {{.Status}} {{.Ports}}'La sortie doit contenir 127.0.0.1:3001->3001/tcp. Depuis une autre machine, le port 3001 ne doit pas être ouvert :
nmap -Pn -p 3001 VOTRE_IP_SERVEUREn accès restreint, une connexion depuis une autre adresse que la vôtre doit être coupée.
Étape 5 : ajouter une première sonde
- Cliquez sur Add New Monitor.
- Dans Monitor Type, choisissez HTTP(s).
- Renseignez Friendly Name, puis l'adresse à surveiller dans URL, par exemple
https://www.votre-domaine.com. - Réglez Heartbeat Interval (l'intervalle entre deux contrôles) et Retries (le nombre de nouvelles tentatives avant l'alerte).
- Activez Certificate Expiry Notification pour être prévenu avant l'expiration du certificat.
- Cliquez sur Save.
Les types de sondes les plus utiles :
| Type | Usage |
|---|---|
| HTTP(s) | Site ou API, avec contrôle du code de réponse |
| HTTP(s) - Keyword | Présence d'un mot dans la page |
| TCP Port | Service qui écoute sur un port, comme SSH ou une base de données |
| Ping | Réponse réseau d'une machine |
| DNS | Résolution d'un nom de domaine |
| Push | Tâche planifiée qui signale elle-même son exécution |
Surveiller une tâche planifiée
Créez une sonde Push et copiez sa Push URL. Appelez-la à la fin de votre script, seulement si celui-ci réussit :
/usr/local/bin/ma-sauvegarde.sh && curl -fsS -m 10 --retry 3 "https://uptime.votre-domaine.com/api/push/VOTRE_JETON?status=up&msg=OK"Remplacez VOTRE_JETON par la valeur de votre URL. Si aucun signal n'arrive dans le délai prévu, la sonde passe à l'état DOWN. Considérez cette URL comme un secret.
Étape 6 : configurer les notifications
Ouvrez Settings > Notifications, puis cliquez sur Set Up Notification. Uptime Kuma prend en charge de nombreux services. L'exemple suivant utilise Telegram :
- Dans Telegram, écrivez à @BotFather, envoyez
/newbotet copiez le jeton obtenu. - Envoyez un message à votre nouveau bot.
- Dans Uptime Kuma, choisissez Telegram dans Notification Type.
- Collez le jeton dans Bot Token.
- Cliquez sur Auto Get pour renseigner Chat ID.
- Activez Default enabled pour l'appliquer aux prochaines sondes, et Apply on all existing monitors pour celles qui existent déjà.
- Cliquez sur Test. Si le message arrive, cliquez sur Save.
Pour un e-mail, choisissez Email (SMTP) et renseignez les paramètres fournis par votre service de messagerie, de préférence avec un compte dédié.
Une notification ne fonctionne que si elle est associée à la sonde. Vérifiez-le dans la colonne Notifications de la fiche de chaque sonde.
Créer une page de statut
Dans Status Pages, cliquez sur New Status Page, choisissez un nom et une adresse, puis ajoutez les sondes à afficher. La page devient accessible sous /status/nom-choisi. Elle est conçue pour être publique et ses données sont mises en cache pendant 5 minutes.
Avec l'accès restreint de l'étape 4, elle ne sera visible que depuis votre adresse. Pour la rendre publique, utilisez le second bloc Caddy.
Mettre à jour Uptime Kuma
Sauvegardez d'abord le dossier data et lisez les notes de version. Remplacez ensuite le tag dans compose.yaml, puis exécutez :
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose psRestez sur la branche 2 tant que vous n'avez pas lu le guide de migration vers la version 3. Cette migration modifie la base de données et ne permet pas de revenir en arrière sans sauvegarde.
Sauvegarder et restaurer
Le dossier data est le seul élément à sauvegarder, avec compose.yaml. C'est la méthode prise en charge par le projet : l'ancien export JSON a été retiré dans la version 2.
cd /opt/uptime-kuma
mkdir -p backups
docker compose stop
sudo tar -czf "backups/uptime-kuma-$(date +%F).tar.gz" data compose.yaml
docker compose start
sudo chmod 600 backups/*.tar.gzL'archive contient la base, les comptes et les jetons de notification. Copiez-la hors du serveur, dans un emplacement chiffré.
Pour restaurer une archive, en remplaçant AAAA-MM-JJ par sa date :
cd /opt/uptime-kuma
docker compose down
sudo mv data "data.ancien-$(date +%F)"
sudo tar -xzf backups/uptime-kuma-AAAA-MM-JJ.tar.gz
docker compose up -dUtilisez la même version d'image que lors de la sauvegarde, ou une version plus récente de la même branche.
En cas de problème
Cannot connect to the socket server
L'interface n'arrive pas à ouvrir sa connexion WebSocket. Vérifiez que le conteneur tourne et consultez ses journaux :
docker compose ps
docker compose logs --tail=50 uptime-kumaSi un autre proxy, comme Cloudflare, se trouve devant Caddy, vérifiez que les WebSockets y sont activés et que le nom de domaine d'origine est bien transmis.
Erreur 502 avec Caddy
Caddy ne joint pas l'application. Vérifiez le port local :
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50Une sonde indique DOWN alors que le service répond
Le contrôle part du conteneur, dont le réseau diffère de celui de votre poste. Testez depuis celui-ci, en adaptant l'adresse :
docker exec uptime-kuma node -e "fetch('https://www.votre-domaine.com').then(r => console.log(r.status)).catch(console.error)"Vérifiez aussi que le service surveillé ne bloque pas l'adresse du serveur, par exemple avec un pare-feu ou CrowdSec.
Une sonde IPv6 échoue
Par défaut, le réseau Docker du conteneur n'utilise pas IPv6. Si le service n'est joignable qu'en IPv6, ajoutez un réseau avec IPv6 à compose.yaml :
services:
uptime-kuma:
networks:
- uptime-kuma-net
networks:
uptime-kuma-net:
enable_ipv6: trueFusionnez ces clés avec votre service existant, puis relancez docker compose up -d.
Les signaux Push n'arrivent pas
Testez l'URL avec curl -i depuis la machine qui exécute la tâche. Une connexion coupée indique généralement que le bloc @push manque dans Caddy. La réponse doit contenir "ok":true.
Aucune notification n'arrive
Utilisez le bouton Test et lisez le message d'erreur. Vérifiez ensuite que la notification est bien activée sur la sonde. Pour un envoi SMTP, contrôlez l'hôte, le port et l'identifiant auprès de votre service de messagerie.
Mot de passe perdu ou double authentification inaccessible
Exécutez la commande adaptée, puis suivez les instructions affichées :
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fadatabase is locked ou base corrompue
Vérifiez que data se trouve sur un disque local et non sur NFS, et que l'espace disque est suffisant avec df -h. Si la base est endommagée, restaurez votre dernière sauvegarde.
port is already allocated
Un autre service occupe le port 3001. Identifiez-le avec sudo ss -ltnp | grep ':3001 '. Pour changer de port, modifiez seulement la partie gauche, par exemple 127.0.0.1:3002:3001, puis adaptez Caddy.