FR

Applications

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.

10 min de lecture, mis à jour le 18 novembre 2026

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.com vers VOTRE_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

Terminal
sudo mkdir -p /opt/uptime-kuma
sudo chown "$USER": /opt/uptime-kuma
cd /opt/uptime-kuma
nano compose.yaml

Collez cette configuration :

YAML
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/data

Démarrez le conteneur :

Terminal
docker compose config --quiet
docker compose up -d
docker compose ps

Le 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 :

Terminal
ssh -N -L 3001:127.0.0.1:3001 VOTRE_USER@VOTRE_IP_SERVEUR

La commande reste active sans rien afficher. Ouvrez ensuite http://localhost:3001, puis :

  1. Choisissez votre langue.
  2. Sélectionnez la base SQLite, adaptée à une installation de taille modeste.
  3. Patientez pendant la préparation de la base.
  4. 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 :

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.

caddyfile
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 :

Terminal
sudo ufw allow 80,443/tcp comment 'Caddy'
sudo -u caddy caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy

Vé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 :

Terminal
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 :

Terminal
nmap -Pn -p 3001 VOTRE_IP_SERVEUR

En accès restreint, une connexion depuis une autre adresse que la vôtre doit être coupée.

Étape 5 : ajouter une première sonde

  1. Cliquez sur Add New Monitor.
  2. Dans Monitor Type, choisissez HTTP(s).
  3. Renseignez Friendly Name, puis l'adresse à surveiller dans URL, par exemple https://www.votre-domaine.com.
  4. Réglez Heartbeat Interval (l'intervalle entre deux contrôles) et Retries (le nombre de nouvelles tentatives avant l'alerte).
  5. Activez Certificate Expiry Notification pour être prévenu avant l'expiration du certificat.
  6. 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 :

Terminal
/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 :

  1. Dans Telegram, écrivez à @BotFather, envoyez /newbot et copiez le jeton obtenu.
  2. Envoyez un message à votre nouveau bot.
  3. Dans Uptime Kuma, choisissez Telegram dans Notification Type.
  4. Collez le jeton dans Bot Token.
  5. Cliquez sur Auto Get pour renseigner Chat ID.
  6. Activez Default enabled pour l'appliquer aux prochaines sondes, et Apply on all existing monitors pour celles qui existent déjà.
  7. 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 :

Terminal
cd /opt/uptime-kuma
nano compose.yaml
docker compose pull
docker compose up -d --force-recreate
docker compose ps

Restez 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.

Terminal
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.gz

L'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 :

Terminal
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 -d

Utilisez 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 :

Terminal
docker compose ps
docker compose logs --tail=50 uptime-kuma

Si 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 :

Terminal
curl -I http://127.0.0.1:3001
sudo journalctl -u caddy --no-pager -n 50

Une 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 :

Terminal
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 :

YAML
services:
  uptime-kuma:
    networks:
      - uptime-kuma-net

networks:
  uptime-kuma-net:
    enable_ipv6: true

Fusionnez 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 :

Terminal
docker exec -it uptime-kuma npm run reset-password
docker exec -it uptime-kuma npm run remove-2fa

database 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.

Références