Uptime Kuma : monitoring de disponibilité self-hosted

Vous gérez des services web et vous voulez être alerté immédiatement en cas de panne ? Ce guide vous permet de déployer Uptime Kuma en moins de 5 minutes et de configurer votre premier monitor. Vous apprendrez à surveiller vos services HTTP, TCP et DNS, à configurer des alertes sur Discord/Telegram/Slack, et à créer une page de statut publique pour vos utilisateurs.

À qui s'adresse ce guide ?

Ce guide est destiné aux administrateurs système, DevOps et développeurs qui souhaitent mettre en place un monitoring de disponibilité simple et efficace, sans dépendre de services SaaS payants.

Qu’est-ce que Uptime Kuma ?

Uptime Kuma est un outil de monitoring de disponibilité (uptime monitoring) open-source et self-hosted. Concrètement, c’est une application qui vérifie régulièrement que vos services (sites web, API, serveurs de base de données, etc.) répondent correctement.

Pour comprendre son utilité, imaginez un veilleur de nuit numérique : toutes les 20 secondes, il frappe à la porte de chacun de vos services pour vérifier qu’ils sont toujours là. S’il n’obtient pas de réponse, il vous envoie immédiatement une alerte sur votre téléphone.

Pourquoi surveiller la disponibilité ?

Un service en panne coûte cher, pas seulement en argent, mais aussi en confiance. Un site e-commerce inaccessible pendant une heure peut représenter des milliers d’euros de ventes perdues. Une API qui ne répond plus bloque les applications de vos clients. Et un certificat SSL expiré ? Les navigateurs modernes affichent un écran d’avertissement qui fait fuir les visiteurs.

Le problème, c’est que sans monitoring, vous découvrez la panne en même temps que vos utilisateurs — voire après eux. Uptime Kuma inverse cette dynamique : il détecte le problème avant qu’un humain ne s’en aperçoive.

Voici comment la différence se joue concrètement :

Situation	Impact sans monitoring	Avec Uptime Kuma
Site e-commerce inaccessible	Perte de ventes pendant des heures	Alerte en 20 secondes, intervention rapide
API down	Clients mécontents, plaintes	Notification immédiate, temps de résolution réduit
Certificat SSL expiré	Blocage navigateur, perte de confiance	Alerte 7 jours avant expiration

Glissez pour voir

Uptime Kuma vs solutions SaaS

Des solutions SaaS comme Pingdom ou UptimeRobot proposent un service clé en main : vous créez un compte, ajoutez une URL, et la surveillance commence. Alors pourquoi s’auto-héberger ?

La réponse tient en trois mots : coût, contrôle et confidentialité. Avec un service SaaS, vos données de monitoring (quels services vous avez, quand ils tombent) sont stockées chez un tiers. L’abonnement augmente avec le nombre de monitors. Et vous êtes limité aux fonctionnalités que le fournisseur veut bien offrir.

Uptime Kuma élimine ces contraintes. En contrepartie, c’est à vous de maintenir l’instance — mais avec Docker, cela se résume à une commande de mise à jour.

Critère	Uptime Kuma	Solutions SaaS (Pingdom, UptimeRobot)
Coût	Gratuit	7-50€/mois
Hébergement	Vos serveurs (contrôle total)	Cloud du fournisseur
Données	Restent chez vous	Sur les serveurs du fournisseur
Personnalisation	Totale (open-source)	Limitée
Intervalle minimum	20 secondes	60 secondes (souvent)
Nombre de monitors	Illimité	Limité selon forfait

Glissez pour voir

Fonctionnalités principales

Avant de passer à l’installation, voyons ce qu’Uptime Kuma sait faire. Cette vue d’ensemble vous aidera à identifier les fonctionnalités utiles pour votre cas d’usage et à planifier votre configuration.

Types de monitors supportés

Un monitor (ou sonde) est une vérification périodique d’un service. Chaque type de monitor correspond à un protocole réseau différent. Le plus courant est HTTP — il vérifie qu’une URL répond — mais Uptime Kuma va bien au-delà.

Par exemple, pour une application web classique, vous utiliserez un monitor HTTP pour vérifier la page d’accueil, un monitor TCP pour vous assurer que la base PostgreSQL accepte les connexions, et un monitor DNS pour garantir que votre domaine pointe toujours vers la bonne IP.

Voici l’ensemble des types disponibles :

• HTTP(S) : vérifie qu’une URL répond avec le code attendu (200, 301, etc.)
• HTTP(S) Keyword : vérifie qu’une page contient un mot-clé spécifique — utile pour détecter une page d’erreur qui renvoie un code 200
• HTTP(S) JSON Query : vérifie une valeur dans une réponse JSON — idéal pour les endpoints /healthz
• TCP : vérifie qu’un port est ouvert (base de données, serveur mail, etc.)
• Ping (ICMP) : vérifie qu’un serveur répond au ping — le test le plus basique
• DNS : vérifie les enregistrements DNS (A, AAAA, MX, TXT, etc.)
• Docker Container : vérifie l’état d’un conteneur Docker directement via le socket
• Steam Game Server : vérifie la disponibilité d’un serveur de jeu
• WebSocket : vérifie une connexion WebSocket — utile pour les applications temps réel
• Push : monitoring passif — c’est le service qui envoie un heartbeat à Uptime Kuma (parfait pour les tâches cron)

Notifications

Détecter une panne ne suffit pas : il faut en être informé immédiatement. Uptime Kuma s’intègre avec plus de 90 services de notification, ce qui signifie que vous recevrez l’alerte là où vous êtes déjà — que ce soit sur Discord pendant que vous codez, sur Telegram depuis votre téléphone, ou via PagerDuty si vous êtes d’astreinte.

Vous pouvez configurer plusieurs canaux simultanément : par exemple, une alerte Discord pour l’équipe et un SMS via ntfy pour le responsable d’astreinte. Les principaux canaux supportés :

• Chat : Discord, Slack, Telegram, Microsoft Teams, Mattermost
• Email : SMTP personnalisé (n’importe quel serveur mail)
• Mobile : Pushover, Pushbullet, Gotify, ntfy
• Webhooks : pour intégration personnalisée avec vos outils internes
• PagerDuty, Opsgenie : pour les rotations d’astreinte en entreprise

Autres fonctionnalités

Au-delà du monitoring pur, Uptime Kuma offre des fonctionnalités qui en font un outil complet. Les pages de statut par exemple permettent de créer une page publique (comme status.votresite.com) où vos utilisateurs consultent l’état de vos services par eux-mêmes, réduisant ainsi la charge de votre support. L’authentification 2FA protège votre instance contre les accès non autorisés.

• Pages de statut : pages publiques ou privées affichant l’état de vos services en temps réel
• Authentification 2FA : sécurisez l’accès avec une application TOTP (Google Authenticator, Bitwarden)
• Proxy support : pour monitorer des services internes accessibles uniquement via un proxy
• Certificats SSL : alerte automatique avant expiration (configurable : 7, 14, 30 jours)
• Interface multilingue : plus de 30 langues supportées, dont le français
• API REST : automatisez la création de monitors ou l’extraction de données pour vos tableaux de bord

Prérequis

Uptime Kuma est volontairement léger : il tourne sur un Raspberry Pi comme sur un serveur dédié. L’installation recommandée utilise Docker, ce qui vous permet de l’isoler du reste du système et de le mettre à jour en une seule commande. Si Docker n’est pas une option, une installation avec Node.js est également possible (voir plus bas).

Vérifiez que ces éléments sont en place avant de continuer :

• Docker installé sur votre serveur (guide Docker) — c’est la méthode recommandée car elle simplifie l’installation et la mise à jour
• 1 Go de RAM minimum — Uptime Kuma consomme environ 100 Mo au repos, mais la consommation augmente avec le nombre de monitors actifs
• Port 3001 disponible — c’est le port par défaut, modifiable dans la configuration Docker si un autre service l’utilise déjà
• Un serveur accessible depuis Internet si vous voulez monitorer des services externes (sinon, le monitoring fonctionne aussi sur un réseau local)

Alternative sans Docker

Uptime Kuma peut aussi s’installer avec Node.js >= 20.4 et PM2. Cette méthode est détaillée plus bas dans ce guide.

Installation avec Docker

1. Créez le répertoire et le fichier Docker Compose

   Nous allons utiliser Docker Compose pour une configuration propre et maintenable :

   mkdir -p ~/uptime-kuma
   cd ~/uptime-kuma

2. Créez le fichier compose.yaml

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

   Ce fichier configure :

   • L’image officielle version 2 (la plus récente)
   • Le redémarrage automatique sauf arrêt manuel
   • Le port 3001 exposé
   • Un volume local ./data pour la persistance

3. Lancez Uptime Kuma

   docker compose up -d

   Vérification : Le conteneur démarre en quelques secondes :

   docker compose ps

   Résultat attendu :

   NAME          STATUS                   PORTS
   uptime-kuma   Up 10 seconds (healthy)  0.0.0.0:3001->3001/tcp

4. Accédez à l’interface web

   Ouvrez votre navigateur à l’adresse : http://votre-ip:3001

   Lors du premier accès, vous devrez créer un compte administrateur.

Ne pas utiliser NFS

Uptime Kuma utilise SQLite comme base de données. Les systèmes de fichiers réseau comme NFS ne supportent pas correctement les verrous de fichiers SQLite, ce qui peut corrompre la base de données. Utilisez toujours un stockage local.

Installation avec Docker run (alternative)

Si vous préférez une commande simple sans fichier Compose :

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

Vérification :

docker ps --filter name=uptime-kuma

Installation avec MariaDB externe (production)

Pour les environnements de production avec de nombreux monitors, vous pouvez utiliser une base MariaDB externe plus performante que SQLite :

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "3001:3001"
    volumes:
      - ./data:/app/data
    networks:
      - kuma-network
    depends_on:
      - uptime-kuma-db

  uptime-kuma-db:
    image: mariadb:11
    container_name: uptime-kuma-db
    restart: unless-stopped
    networks:
      - kuma-network
    volumes:
      - ./mariadb-data:/var/lib/mysql
    environment:
      - MARIADB_ROOT_PASSWORD=changez-moi-root
      - MARIADB_DATABASE=uptimekuma
      - MARIADB_USER=uptimekuma
      - MARIADB_PASSWORD=changez-moi-kuma

networks:
  kuma-network:
    driver: bridge

Au premier lancement, choisissez “External MariaDB/MySQL” dans l’assistant et renseignez :

• Hostname : uptime-kuma-db (le nom du service Docker)
• Port : 3306
• Username : uptimekuma
• Password : changez-moi-kuma
• Database : uptimekuma

Changez les mots de passe

Les mots de passe ci-dessus sont des exemples. Utilisez des mots de passe forts et uniques en production.

Installation sans Docker (Node.js)

Linux/macOS

1. Installez les prérequis

   # Vérifiez la version de Node.js (>= 20.4 requis)
   node --version
   
   # Installez PM2 pour la gestion en arrière-plan
   npm install -g pm2
   pm2 install pm2-logrotate

2. Clonez et configurez Uptime Kuma

   git clone https://github.com/louislam/uptime-kuma.git
   cd uptime-kuma
   npm run setup

3. Démarrez l’application

   pm2 start server/server.js --name uptime-kuma
   pm2 save
   pm2 startup

   Vérification :

   pm2 status uptime-kuma

Windows

1. Installez les prérequis

   • Téléchargez et installez Node.js >= 20.4
   • Téléchargez et installez Git

2. Clonez et configurez

   Ouvrez PowerShell en administrateur :

   git clone https://github.com/louislam/uptime-kuma.git
   cd uptime-kuma
   npm run setup

3. Démarrez l’application

   npm install -g pm2
   pm2 start server/server.js --name uptime-kuma

Configuration initiale

Lors du premier accès à l’interface web (http://votre-ip:3001), Uptime Kuma vous guide à travers un assistant de configuration en plusieurs étapes. Contrairement à la version 1, la version 2 introduit un choix de base de données dès le départ.

1. Choisissez la langue

   L’interface est disponible en 30+ langues, dont le français. Sélectionnez votre langue dans le menu déroulant.

2. Sélectionnez le type de base de données

   C’est la grande nouveauté de la version 2. Uptime Kuma vous propose trois options :

   Option	Description	Quand l’utiliser
   SQLite	Base de données intégrée, aucune configuration	Recommandé pour débuter. Parfait pour < 100 monitors
   Embedded MariaDB	MariaDB installé automatiquement dans le conteneur	Performance accrue, mais plus de ressources
   External MariaDB	Connexion à un serveur MariaDB existant	Environnements de production, haute disponibilité

   Glissez pour voir

   Quel choix faire ?

   Pour 95% des utilisations, SQLite suffit largement. C’est le choix le plus simple : zéro configuration, les données sont stockées dans un seul fichier kuma.db. Choisissez MariaDB uniquement si vous avez plus de 100 monitors ou si vous avez besoin de haute disponibilité.

   Si vous choisissez External MariaDB, vous devrez renseigner :

   Paramètre	Exemple	Description
   Hostname	uptime-kuma-db	Nom d’hôte du serveur MariaDB
   Port	3306	Port par défaut de MariaDB
   Username	uptimekuma	Utilisateur de la base
   Password	votre-mot-de-passe	Mot de passe de l’utilisateur
   Database Name	uptimekuma	Nom de la base de données

   Glissez pour voir

3. Créez le compte administrateur

   

   Définissez un nom d’utilisateur et un mot de passe fort (minimum 8 caractères). Ce compte sera le seul à pouvoir gérer les monitors et les paramètres. Notez-le précieusement : la réinitialisation nécessite un accès en ligne de commande au serveur.

4. Découvrez le tableau de bord

   

   Après la création du compte, vous arrivez sur le tableau de bord (dashboard). Il est vide pour l’instant — c’est normal. La barre latérale gauche affichera la liste de vos monitors avec leur statut en temps réel.

Paramétrage initial recommandé

Avant de créer votre premier monitor, prenez 2 minutes pour configurer les paramètres essentiels. Ces réglages évitent les mauvaises surprises : une URL de base mal configurée, par exemple, génère des liens cassés dans toutes vos notifications. Cliquez sur l’icône engrenage en haut à droite pour accéder aux Settings (Paramètres).

Chaque paramètre ci-dessous a un impact direct sur l’expérience de monitoring. La Primary Base URL est particulièrement importante si vous accédez à Uptime Kuma via un domaine personnalisé : c’est cette URL qui apparaît dans les notifications et les pages de statut.

Paramètre	Où le trouver	Pourquoi le configurer
Langue	Settings > General	Interface en français
Primary Base URL	Settings > General	URL publique de votre instance (pour les liens dans les notifications)
Search Engine Visibility	Settings > General	Désactivez si vous ne voulez pas que les pages de statut soient indexées par Google
Fuseau horaire	Settings > General	Pour que les heures affichées correspondent à votre zone
Thème	Settings > Appearance	Choisissez entre clair, sombre ou automatique

Glissez pour voir

Activez la 2FA dès maintenant

Dans Settings > Security, activez l’authentification à deux facteurs (TOTP) avec une application comme Google Authenticator, Authy ou Bitwarden. Sans 2FA, quiconque devine votre mot de passe a accès à toute votre configuration de monitoring.

Créer votre premier monitor HTTP

Un monitor est une sonde qui vérifie périodiquement qu’un service répond. Chaque monitor a un type (HTTP, TCP, DNS…), une cible (URL, IP, domaine) et un intervalle de vérification. Commençons par le plus courant : surveiller un site web.

1. Cliquez sur “Add New Monitor”

   Sur le dashboard, cliquez sur le gros bouton ”+ Add New Monitor” en haut à gauche.

   

2. Configurez les paramètres de base

   Paramètre	Valeur exemple	Explication
   Monitor Type	HTTP(s)	Pour vérifier qu’une URL répond correctement
   Friendly Name	Blog Stéphane Robert	Nom affiché dans le dashboard (choisissez un nom parlant)
   URL	https://blog.stephane-robert.info	L’URL complète à surveiller
   Heartbeat Interval	60	Vérification toutes les 60 secondes (minimum 20s)

   Glissez pour voir

   Quel intervalle choisir ?

   • 20-30 secondes : services critiques (paiement, prod)
   • 60 secondes : sites web standards
   • 300 secondes (5 min) : services secondaires

   Plus l’intervalle est court, plus la détection est rapide, mais plus la charge sur votre instance augmente.

3. Configurez les options avancées

   Déroulez la section Advanced pour affiner le comportement :

   Paramètre	Valeur recommandée	Pourquoi
   Accepted Status Codes	200-299	Par défaut. Ajoutez 301, 302 si l’URL redirige
   Max Retries	3	Évite les faux positifs sur un pic de latence
   Retry Interval	20	Secondes entre chaque tentative
   Timeout	10	Temps max d’attente (en secondes)
   Certificate Expiry	14	Alerte 14 jours avant expiration du certificat SSL

   Glissez pour voir

4. Ajoutez le monitor à un groupe (optionnel)

   Dans la section Advanced, le champ Group vous permet d’organiser vos monitors. Cliquez sur ”+” pour créer un nouveau groupe (par exemple : “Production”, “Staging”, “APIs”). Les groupes rendent le dashboard bien plus lisible quand vous avez beaucoup de monitors.

5. Cliquez sur “Save”

   Le monitor commence immédiatement à fonctionner. Vous voyez apparaître :

   

   • Le statut actuel (UP en vert, DOWN en rouge)
   • Le graphique des temps de réponse sur les dernières heures
   • Le pourcentage d’uptime (disponibilité)
   • L’historique des événements (changements d’état)

Comment Uptime Kuma détecte une panne

Le processus est le suivant : Uptime Kuma envoie une requête HTTP → si la réponse n’arrive pas dans le délai du Timeout, ou si le code HTTP n’est pas dans les Accepted Status Codes, c’est compté comme un échec. Après le nombre de Max Retries atteint, le service passe en DOWN et les notifications sont envoyées.

Configurer les notifications

Un monitoring sans notification, c’est comme une alarme incendie sans sirène : vous ne saurez qu’il y a un problème qu’en le constatant vous-même. Configurez au moins un canal de notification pour recevoir des alertes automatiques.

Uptime Kuma supporte plus de 90 services de notification. Voici les deux plus populaires :

Exemple avec Discord

1. Créez un webhook Discord

   Dans Discord, allez dans Paramètres du serveur > Intégrations > Webhooks et créez un nouveau webhook. Copiez l’URL.

2. Ajoutez la notification dans Uptime Kuma

   Cliquez sur Settings > Notifications > Setup Notification :

   Paramètre	Valeur
   Notification Type	Discord
   Friendly Name	Alertes Discord
   Discord Webhook URL	L’URL copiée

   Glissez pour voir

3. Testez la notification

   Cliquez sur “Test”. Vous devriez recevoir un message dans votre channel Discord.

4. Associez à vos monitors

   Par défaut, les nouvelles notifications s’appliquent à tous les monitors. Vous pouvez aussi les configurer individuellement sur chaque monitor.

Exemple avec Telegram

1. Créez un bot Telegram

   Envoyez /newbot à @BotFather et suivez les instructions. Notez le token du bot.

2. Obtenez votre Chat ID

   Envoyez un message à votre bot, puis accédez à : https://api.telegram.org/bot<TOKEN>/getUpdates

   Le Chat ID apparaît dans la réponse JSON.

3. Configurez dans Uptime Kuma

   Paramètre	Valeur
   Notification Type	Telegram
   Bot Token	Le token de BotFather
   Chat ID	Votre Chat ID

   Glissez pour voir

Types de monitors avancés

Monitor TCP

Le monitoring TCP est utile pour vérifier qu’un port est ouvert et qu’un service écoute dessus. Contrairement au HTTP, il ne vérifie pas le contenu de la réponse — juste que la connexion s’établit.

Cas d’usage typiques :

• Base de données (PostgreSQL 5432, MySQL 3306, Redis 6379)
• Serveur SSH (port 22)
• Serveur mail (SMTP 25/587, IMAP 993)

Paramètre	Exemple	Usage
Hostname	192.168.1.100	IP ou nom d’hôte du serveur
Port	5432	Port du service à vérifier

Glissez pour voir

Monitor DNS

Le monitoring DNS vérifie que vos enregistrements DNS renvoient les bonnes valeurs. C’est essentiel pour détecter :

• Un détournement DNS (quelqu’un modifie vos enregistrements)
• Une propagation incomplète après un changement
• Un problème de résolveur DNS

Pour configurer un monitor DNS, vous devez préciser le domaine à surveiller, le type d’enregistrement à vérifier et la valeur attendue. Uptime Kuma interroge le resolveur DNS de votre choix à chaque vérification et compare la réponse avec la valeur attendue. Si la réponse diffère, le monitor passe en DOWN — signe qu’un changement non autorisé s’est produit.

Paramètre	Exemple	Usage
Hostname	blog.stephane-robert.info	Domaine à vérifier
Record Type	A	Type d’enregistrement (A, AAAA, MX, CNAME, TXT)
Expected Value	93.184.216.34	L’adresse IP attendue
DNS Resolver	1.1.1.1	Serveur DNS à interroger (Cloudflare, Google 8.8.8.8, etc.)

Glissez pour voir

Monitor Docker

Le monitoring de conteneurs Docker permet de vérifier qu’un conteneur est bien en cours d’exécution (running). C’est particulièrement utile pour surveiller des services critiques comme une base de données, un reverse proxy ou un service d’authentification.

Implications de sécurité du socket Docker

Monter le socket Docker (/var/run/docker.sock) donne à Uptime Kuma un accès de lecture à tous vos conteneurs. C’est sûr en lecture seule (:ro), mais soyez conscient que le conteneur peut lister et inspecter tous les autres conteneurs du système.

1. Ajoutez le socket Docker au compose.yaml

   Mettez à jour votre fichier pour monter le socket en lecture seule :

   services:
     uptime-kuma:
       image: louislam/uptime-kuma:2
       container_name: uptime-kuma
       restart: unless-stopped
       ports:
         - "3001:3001"
       volumes:
         - ./data:/app/data
         - /var/run/docker.sock:/var/run/docker.sock:ro

   Puis redémarrez :

   docker compose up -d

2. Configurez un Docker Host dans Uptime Kuma

   

   Allez dans Settings > Docker Hosts et cliquez sur ”+ Add Docker Host” :

   Paramètre	Valeur
   Friendly Name	Docker Local
   Connection Type	Socket
   Docker Daemon	/var/run/docker.sock

   Glissez pour voir

   Cliquez sur Save. Un message de succès confirme la connexion.

3. Créez un monitor Docker Container

   Cliquez sur ”+ Add New Monitor” :

   Paramètre	Valeur
   Monitor Type	Docker Container
   Friendly Name	Nginx Proxy
   Docker Host	Docker Local (celui créé à l’étape précédente)
   Container Name	nginx

   Glissez pour voir

   Le Container Name doit correspondre exactement au nom du conteneur (celui que vous voyez avec docker ps).

Monitor Push (Passive)

Le monitoring passif est utile pour les tâches cron ou les scripts :

1. Créez un monitor Push

   Uptime Kuma génère une URL unique, par exemple : https://votre-uptime-kuma.com/api/push/abcd1234

2. Appelez cette URL depuis votre script

   # À la fin de votre script cron
   curl -s "https://votre-uptime-kuma.com/api/push/abcd1234?status=up&msg=OK"

3. Configurez l’intervalle attendu

   Si Uptime Kuma ne reçoit pas de heartbeat dans l’intervalle défini, il déclare le service DOWN.

Créer une page de statut

Les pages de statut (status pages) sont des pages web publiques qui affichent l’état de vos services en temps réel. Elles sont utiles pour :

• Vos utilisateurs : ils vérifient eux-mêmes si un service est en panne (au lieu d’envoyer des tickets de support)
• Votre équipe : vue d’ensemble rapide de l’état de production
• La transparence : montrer que vous prenez la disponibilité au sérieux

1. Créez une nouvelle page

   Cliquez sur “Status Pages” dans la barre latérale, puis sur ”+ New Status Page”.

   Paramètre	Exemple	Description
   Name	Statut de mes services	Titre affiché en haut de la page
   Slug	status	Partie de l’URL : /status/status

   Glissez pour voir

2. Ajoutez des groupes et monitors

   

   Organisez vos monitors en groupes logiques. Par exemple :

   • Production : site web, API, base de données
   • Infrastructure : reverse proxy, DNS, monitoring
   • Outils internes : GitLab, wiki, ticketing

   Cliquez sur “Add a group”, nommez-le, puis ajoutez les monitors concernés.

3. Personnalisez l’apparence

   Vous pouvez personnaliser :

   • Logo : upload d’une image personnalisée
   • Description : texte d’introduction (supporte le Markdown)
   • Footer : mention légale ou lien vers votre site
   • Thème : clair ou sombre
   • Show Certificate Expiry : affiche les jours restants avant expiration SSL (uniquement pour les monitors HTTP)

4. Cliquez sur “Save”

   

   La page est accessible sans authentification à l’adresse : http://votre-ip:3001/status/status

Domaine personnalisé

Vous pouvez assigner un domaine personnalisé à une page de statut (par ex. status.monentreprise.com) via un reverse proxy. Chaque page de statut peut avoir son propre domaine.

Fenêtres de maintenance

Lorsque vous planifiez une maintenance (mise à jour serveur, migration de base de données, etc.), vous ne voulez pas recevoir de fausses alertes pendant l’intervention. Les fenêtres de maintenance servent exactement à cela.

1. Créez une maintenance

   Cliquez sur “Maintenance” dans la barre latérale, puis ”+ Schedule Maintenance”.

2. Configurez la fenêtre

   Paramètre	Description
   Title	Nom de la maintenance (ex: “Mise à jour PostgreSQL”)
   Strategy	Manual (déclenchement à la main) ou Scheduled (planifié)
   Date/Time	Pour les maintenances planifiées : date de début et de fin
   Affected Monitors	Sélectionnez les monitors concernés

   Glissez pour voir

3. Activez la maintenance

   Pendant la maintenance, les monitors affectés affichent un statut jaune (maintenance) au lieu de rouge (down). Aucune notification n’est envoyée.

Maintenance récurrente

Vous pouvez créer des maintenances récurrentes (tous les dimanches à 3h par exemple) pour les fenêtres de maintenance régulières.

Badges de statut

Les badges sont des petites images dynamiques (comme celles que vous voyez sur les projets GitHub : « build passing », « coverage 85% »). Uptime Kuma en génère automatiquement pour chacun de vos monitors. Intégrés dans un README ou une page de documentation, ils montrent le statut actuel du service sans que le lecteur ait besoin de se connecter à votre instance.

Trois types de badges sont disponibles : le statut (UP/DOWN), le pourcentage d’uptime sur une période et le temps de réponse moyen. L’image se met à jour automatiquement à chaque rafraîchissement de la page qui l’affiche.

Pour chaque monitor, Uptime Kuma fournit une URL de badge au format :

https://votre-uptime-kuma.com/api/badge/:monitorId/status
https://votre-uptime-kuma.com/api/badge/:monitorId/uptime
https://votre-uptime-kuma.com/api/badge/:monitorId/ping

Intégration dans un fichier Markdown :

![Statut](https://votre-uptime-kuma.com/api/badge/1/status)
![Uptime](https://votre-uptime-kuma.com/api/badge/1/uptime)
![Ping](https://votre-uptime-kuma.com/api/badge/1/ping)

Mise à jour

Uptime Kuma évolue vite : corrections de bugs, nouveaux types de monitors et nouvelles intégrations de notification arrivent régulièrement. Mettre à jour est important non seulement pour les fonctionnalités, mais aussi pour les correctifs de sécurité. Grâce à Docker, la mise à jour se résume à tirer la nouvelle image et à recréer le conteneur — vos données sont préservées dans le volume.

Toujours sauvegarder avant

Avant chaque mise à jour, sauvegardez le répertoire ./data (voir section Sauvegardes ci-dessous). En cas de problème, vous pourrez restaurer une version fonctionnelle.

Avec Docker Compose

La commande pull télécharge la dernière image, puis up -d recrée le conteneur avec la nouvelle version tout en conservant le volume de données :

cd ~/uptime-kuma
docker compose pull
docker compose up -d

Vérifiez ensuite que le conteneur est bien démarré avec docker compose ps et consultez les logs pour confirmer l’absence d’erreur : docker compose logs -f.

Avec Docker run

Avec docker run, il faut arrêter et supprimer l’ancien conteneur avant d’en créer un nouveau. Le volume nommé (uptime-kuma) persiste entre les recréations :

docker pull louislam/uptime-kuma:2
docker stop uptime-kuma
docker rm uptime-kuma
docker run -d --restart=unless-stopped -p 3001:3001 \
  -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:2

Sans Docker (Node.js)

Avec Node.js, la mise à jour passe par git pour récupérer le code source mis à jour, puis npm run setup réinstalle les dépendances et applique les migrations de base de données :

cd uptime-kuma
git fetch --all
git checkout 2.0.2  # Remplacez par la dernière version
npm run setup
pm2 restart uptime-kuma

Sauvegardes

Toute la configuration d’Uptime Kuma — monitors, notifications, pages de statut, historique de disponibilité — réside dans un seul endroit : le répertoire ./data (ou le volume Docker équivalent). Avec SQLite, c’est un simple fichier kuma.db. Si ce fichier disparaît ou se corrompt, vous perdez tout.

La sauvegarde est donc critique, surtout avant une mise à jour. La stratégie la plus simple : copier le répertoire ./data régulièrement vers un emplacement séparé.

Sauvegardez AVANT chaque mise à jour

Une mise à jour qui échoue en pleine migration de base de données peut corrompre les données. Prenez toujours une copie avant.

Sauvegarde manuelle

Arrêtez le conteneur avant la copie pour garantir la cohérence de la base SQLite. Si vous utilisez MariaDB, un dump SQL est préférable à une copie de fichiers :

# Avec Docker Compose
cd ~/uptime-kuma
docker compose stop
cp -r ./data ./data-backup-$(date +%Y%m%d)
docker compose start

Sans Docker, copiez simplement le fichier de base de données :

# Sans Docker
cp data/kuma.db data/kuma.db.backup-$(date +%Y%m%d)

Sauvegarde automatisée

Pour ne jamais oublier, programmez un cron job qui s’exécute chaque nuit. L’exemple ci-dessous copie le répertoire ./data tous les jours à 3h du matin. Pensez aussi à mettre en place une rotation (suppression des sauvegardes de plus de 30 jours) pour éviter de saturer le disque :

Automatisation

# Sauvegarde quotidienne à 3h
0 3 * * * cd ~/uptime-kuma && cp -r ./data ./backups/data-$(date +\%Y\%m\%d)
# Suppression des sauvegardes de plus de 30 jours
0 4 * * * find ~/uptime-kuma/backups -maxdepth 1 -mtime +30 -exec rm -rf {} \;

Reverse proxy (HTTPS)

En production, Uptime Kuma ne doit jamais être exposé directement sur Internet en HTTP. Un reverse proxy place un serveur web devant votre instance pour gérer le HTTPS (chiffrement TLS), la compression et éventuellement le cache.

Sans reverse proxy, les identifiants de connexion et les données de monitoring transitent en clair sur le réseau. N’importe qui entre votre navigateur et le serveur peut les intercepter.

Uptime Kuma utilise WebSocket pour les mises à jour en temps réel du dashboard. Votre reverse proxy doit donc transmettre les headers Upgrade et Connection. Les trois configurations ci-dessous prennent en charge ce point.

Choisissez le reverse proxy que vous utilisez déjà dans votre infrastructure :

Nginx

server {
    listen 443 ssl http2;
    server_name status.example.com;

    ssl_certificate /etc/letsencrypt/live/status.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/status.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik

# Labels dans docker-compose.yaml
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.uptime-kuma.rule=Host(`status.example.com`)"
  - "traefik.http.routers.uptime-kuma.entrypoints=websecure"
  - "traefik.http.routers.uptime-kuma.tls.certresolver=letsencrypt"
  - "traefik.http.services.uptime-kuma.loadbalancer.server.port=3001"

Caddy

status.example.com {
    reverse_proxy localhost:3001
}

WebSocket requis

Si le dashboard se fige ou affiche des données obsolètes, vérifiez que votre reverse proxy transmet bien les headers Upgrade et Connection. C’est la cause la plus fréquente de problèmes après la mise en place d’un reverse proxy.

Dépannage

Même avec une installation simple, vous pouvez rencontrer des problèmes. Cette section couvre les cas les plus fréquents. Le réflexe à avoir systématiquement : consultez les logs en premier. C’est là que se trouvent 90% des réponses.

Le conteneur ne démarre pas

Quand le conteneur refuse de démarrer ou redémarre en boucle, les logs Docker contiennent presque toujours la raison. Lancez cette commande pour les consulter :

docker logs uptime-kuma
# ou avec Docker Compose :
docker compose logs uptime-kuma

Les erreurs les plus courantes sont liées au port déjà utilisé, aux permissions ou à un problème de base de données. Voici comment les diagnostiquer et les résoudre :

Erreur	Cause	Solution
port is already allocated	Port 3001 déjà utilisé par un autre service	Changez le port : -p 3002:3001 dans votre compose
permission denied	Droits insuffisants sur le volume ./data	sudo chown -R 1000:1000 ./data
SQLITE_CORRUPT	Base de données corrompue	Restaurez une sauvegarde (voir section Sauvegardes)
ENOSPC	Disque plein	Libérez de l’espace : docker system prune

Glissez pour voir

Réinitialiser le mot de passe

Si vous avez perdu votre mot de passe administrateur, pas de panique : Uptime Kuma fournit une commande de réinitialisation. Elle nécessite un accès au serveur (SSH ou console Docker), ce qui garantit que seul un administrateur système peut l’utiliser :

# Avec Docker
docker exec -it uptime-kuma npm run reset-password

# Sans Docker
cd uptime-kuma
npm run reset-password

La commande vous demandera de saisir un nouveau mot de passe interactivement.

L’interface est lente

Une interface lente a généralement trois causes : ressources insuffisantes, trop de monitors avec un intervalle court, ou une base de données qui a grossi avec le temps. Identifiez d’abord la cause avec le diagnostic ci-dessous avant d’appliquer la solution :

Symptôme	Diagnostic	Solution
Lenteur générale	Vérifiez les ressources	docker stats uptime-kuma — si > 80% RAM, augmentez
Chargement long du dashboard	Trop de monitors	Augmentez l’intervalle des monitors non critiques
Base très grosse (> 500 Mo)	Historique accumulé	Settings > Delete Older Data

Glissez pour voir

Les notifications ne partent pas

Les notifications qui ne fonctionnent pas sont frustrantes, car vous ne le découvrez qu’au moment d’une vraie panne. Pour éviter cela, testez toujours une notification après l’avoir configurée. Voici les points à vérifier :

• Bouton “Test” : dans la configuration de la notification, cliquez dessus pour envoyer un message de test immédiat
• SMTP : vérifiez le port (587 pour TLS, 465 pour SSL) et les identifiants — les erreurs d’authentification sont la cause la plus fréquente
• Discord/Telegram : vérifiez que le webhook/token est toujours valide (un webhook supprimé côté Discord ne génère pas d’erreur visible)
• Firewall : assurez-vous que le serveur peut accéder à Internet sur le port 443 — curl -I https://discord.com permet de tester rapidement

Limites connues

Uptime Kuma est un excellent outil pour les petites et moyennes infrastructures, mais il a des limites qu’il faut connaître avant de le déployer en production. La principale : c’est une solution mono-instance. Si le serveur qui héberge Uptime Kuma tombe, vous perdez votre monitoring. C’est pourquoi il doit toujours être installé sur un serveur séparé des services qu’il surveille.

De même, Uptime Kuma ne fait pas de monitoring distribué : les vérifications partent d’un seul point géographique. Si vous avez besoin de tester la disponibilité depuis Paris, New York et Tokyo simultanément, une solution SaaS comme Pingdom ou Checkly sera plus adaptée.

Limitation	Impact	Alternative
Mono-utilisateur	Pas de gestion fine des droits (RBAC), un seul compte admin	Prometheus + Grafana pour les équipes avec rôles différenciés
Instance unique	Si le serveur Uptime Kuma tombe, plus de monitoring	Déployez sur un serveur séparé de la production
Pas de monitoring distribué	Un seul point de vérification géographique	Solutions SaaS pour le multi-région
API en développement	Automatisation limitée (la v2 améliore cela)	Utilisez l’interface web en attendant la stabilisation

Glissez pour voir

Bonne pratique

Ne déployez jamais Uptime Kuma sur le même serveur que les services qu’il monitorise. Si le serveur tombe, vous perdez à la fois vos services ET votre monitoring.

À retenir

• Uptime Kuma est un outil de monitoring de disponibilité open-source et self-hosted. Gratuit et sans limite de monitors, il remplace avantageusement les solutions SaaS pour les petites et moyennes infrastructures.
• Un monitor est une sonde qui vérifie périodiquement qu’un service répond. Uptime Kuma supporte de nombreux types : HTTP, TCP, DNS, Docker Container, Push, WebSocket, et bien d’autres.
• Le heartbeat est le battement de cœur du monitoring : à chaque intervalle (configurable dès 20 secondes), Uptime Kuma interroge le service et enregistre sa réponse.
• Les status pages sont des pages web publiques qui affichent l’état de vos services en temps réel. Elles réduisent les tickets de support en permettant aux utilisateurs de vérifier eux-mêmes la disponibilité.
• Le push monitor inverse la logique habituelle : au lieu qu’Uptime Kuma interroge le service, c’est le service (ou un script cron) qui envoie un signal à Uptime Kuma. Si le signal n’arrive pas dans le délai prévu, le service est déclaré DOWN.
• Les groupes organisent vos monitors par catégorie (Production, Staging, APIs) pour garder un dashboard lisible même avec des dizaines de monitors.
• Les fenêtres de maintenance suspendent les alertes pendant une intervention planifiée, évitant les fausses alarmes qui décrédibilisent le monitoring.
• Les badges sont des images dynamiques (comme sur GitHub) que vous intégrez dans vos README pour afficher le statut, l’uptime ou le temps de réponse d’un service.
• SQLite suffit pour la majorité des usages (jusqu’à ~100 monitors). Passez à MariaDB uniquement si vous avez besoin de haute disponibilité ou d’un grand nombre de monitors.

Prochaines étapes

Prometheus Collectez des métriques détaillées pour compléter le monitoring

Grafana Visualisez vos données de monitoring avec des dashboards

Traefik Configurez un reverse proxy moderne pour exposer Uptime Kuma

Docker Approfondissez Docker pour mieux gérer vos conteneurs

Plus d’infos

• Site officiel
• Documentation GitHub
• Démo en ligne
• Liste des notifications supportées

×

📖 Voir la documentation →