Uptime Kuma sur un VPS : installer la surveillance des sites et des serveurs

30/08/20268 min de lecture

Tropic

Uptime Kuma sur un VPS : installer la surveillance des sites et des serveurs

Uptime Kuma : installer sa propre surveillance de sites sur un VPS

Un site peut être en panne tout en continuant à répondre 200 OK. Une sauvegarde peut également cesser de s’exécuter sans afficher d’erreur évidente. Uptime Kuma détecte ces deux situations : il vérifie les sites, les API, les ports et les tâches en arrière-plan, puis envoie une notification en cas de problème.

Nous allons voir où héberger la surveillance, de quel VPS elle a besoin et comment installer Uptime Kuma 2, activer HTTPS, connecter Telegram et créer une page d’état.

Uptime Kuma en sept étapes

Prévoir un petit VPS séparé des projets surveillés.
Faire pointer vers lui un sous-domaine, par exemple monitor.example.com.
Installer Docker et démarrer Uptime Kuma 2.
Fermer le port interne 3001 vers l’extérieur et activer HTTPS.
Créer des moniteurs HTTP, DNS, TCP ou Push.
Configurer Telegram et, si nécessaire, une page d’état.
Mettre en place les mises à jour et une sauvegarde externe du répertoire de données.

Qu’est-ce qu’Uptime Kuma ?

Uptime Kuma est un outil auto-hébergé, gratuit et open source. Le tableau de bord et l’historique des vérifications sont conservés sur votre propre serveur.

Il peut surveiller HTTP(S), les ports TCP, le ping, DNS, WebSocket, le texte et le JSON présents dans une réponse, les signaux Push ainsi que les conteneurs Docker. L’intervalle minimal entre deux vérifications est de 20 secondes. Il propose aussi des dizaines de canaux de notification, la 2FA, des graphiques de latence, le suivi des certificats TLS et plusieurs pages d’état.

Comment détecter une panne derrière un `200 OK`

Une vérification HTTP classique ne voit que le code de réponse. Pourtant, un serveur web peut afficher une page vide ou un écran d’erreur de l’application tout en renvoyant un statut de réussite.

Pour un contrôle plus précis, utilisez :

Keyword — recherche une expression attendue, par exemple le nom du site ou le texte « Espace client » ;
JSON Query — vérifie une valeur dans la réponse d’une API, par exemple status: healthy.

La surveillance confirme ainsi non seulement que le port est accessible, mais aussi qu’au moins un élément essentiel de l’application fonctionne correctement.

Moniteur Push pour les sauvegardes et les tâches cron

Un moniteur Push n’interroge pas le service. Il attend au contraire que celui-ci lui envoie régulièrement un signal. Un script de sauvegarde ou une tâche cron appelle une URL unique après une exécution réussie. Si le signal n’arrive pas à temps, Uptime Kuma signale l’échec.

Cela permet de repérer un problème « silencieux » : le site fonctionne toujours, mais la sauvegarde quotidienne n’est plus créée depuis plusieurs jours.

Ce qu’Uptime Kuma ne remplace pas

Uptime Kuma surveille principalement la disponibilité et le temps de réponse. Pour le CPU, la RAM, le disque, les journaux et les métriques des conteneurs, complétez-le avec Prometheus, Netdata, Zabbix ou un autre système : Kuma détecte le problème depuis l’extérieur, tandis que les métriques aident à en trouver la cause.

Pourquoi héberger la surveillance sur un VPS séparé

Si Uptime Kuma est installé avec le site, une panne du VPS, du réseau ou du centre de données peut rendre indisponibles à la fois le projet et la surveillance. La notification risque alors de ne jamais partir.

Placez le tableau de bord sur un VPS distinct et, pour les projets importants, dans une autre région ou chez un autre fournisseur. Il est également utile de surveiller Kuma lui-même avec un service externe : le système de surveillance doit lui aussi être surveillé.

Configuration serveur requise par Uptime Kuma

Le projet ne fixe pas de minimum officiel strict pour le CPU et la RAM. Pour une petite installation, une configuration de départ pratique est la suivante :

1 vCPU ;
1 Go de RAM ;
10 Go de SSD ;
Ubuntu 24.04 LTS ;
IPv4 ;
un domaine ou un sous-domaine pour HTTPS.

Cette configuration suffit généralement pour quelques dizaines de vérifications simples. Pour des centaines de moniteurs, un long historique ou des vérifications via navigateur, choisissez 2 Go de RAM ou plus.

Comment installer Uptime Kuma sur un VPS

Cet exemple utilise Ubuntu 24.04 et le sous-domaine monitor.example.com.

1. Configurer DNS et le pare-feu

Créez un enregistrement DNS A pointant vers l’adresse IPv4 du VPS. Connectez-vous en SSH et ouvrez les ports nécessaires :

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Ne fermez pas la session SSH actuelle avant d’avoir testé une nouvelle connexion.

2. Installer Docker et Docker Compose

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Démarrer Uptime Kuma 2

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

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

Utilisez le tag :2 : latest reste associé à l’ancienne branche v1. Le répertoire /app/data doit se trouver sur un disque local ou dans un Docker volume classique. NFS et les stockages qui ne gèrent pas correctement le verrouillage des fichiers peuvent endommager la base de données.

Le port 3001 n’est accessible que sur 127.0.0.1. Un proxy inverse avec HTTPS publiera le tableau de bord vers l’extérieur.

4. Activer HTTPS avec Caddy

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Si DNS pointe vers le VPS, Caddy demandera automatiquement un certificat TLS et transmettra les connexions WebSocket. Placez le tableau de bord à la racine d’un domaine ou d’un sous-domaine : une adresse comme example.com/kuma n’est pas prise en charge.

5. Créer le compte administrateur

Ouvrez https://monitor.example.com, créez un compte avec un mot de passe long et unique, puis activez l’authentification à deux facteurs.

Comment ajouter le premier moniteur

Cliquez sur Add New Monitor et sélectionnez HTTP(s) :

Indiquez un nom et l’URL complète.
Définissez un intervalle, par exemple 60 secondes.
Ajoutez deux nouvelles tentatives pour éviter les fausses alertes dues à des incidents réseau ponctuels.
Sélectionnez un canal de notification.
Enregistrez le moniteur et vérifiez que les requêtes réussies commencent à apparaître.

Pour le site principal, les vérifications HTTP et Keyword sont utiles. Pour une API, utilisez un endpoint de santé et JSON Query. N’exposez pas une base de données ou un port d’administration à Internet uniquement pour la surveillance : passez par un réseau de confiance ou un VPN.

Exemple de moniteur Push pour une sauvegarde

Après avoir créé un moniteur de type Push, ajoutez son URL unique à la fin du script :

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

La requête ne sera exécutée qu’après une sauvegarde réussie. Traitez le token Push comme un mot de passe : toute personne connaissant l’URL peut envoyer un faux signal de réussite.

Comment connecter Telegram

Créez un bot avec @BotFather, envoyez-lui un message, puis ouvrez Settings → Notifications → Telegram. Saisissez le Bot Token et le Chat ID, cliquez sur Test, puis associez le canal aux moniteurs. Pour les services critiques, ajoutez un second canal, par exemple l’e-mail.

Comment créer une page d’état

Dans Status Pages, vous pouvez regrouper les moniteurs, afficher l’état actuel et l’historique de disponibilité, attribuer un domaine et annoncer les opérations planifiées avec Maintenance. Ne publiez pas les adresses IP internes ni les URL techniques : les clients ont seulement besoin de composants tels que « Site », « API », « Espace client » et « Paiements ».

Mise à jour et sauvegarde

Avant une mise à jour importante, arrêtez le conteneur et sauvegardez le répertoire de données :

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

Transférez l’archive vers un autre appareil ou un stockage externe. Une copie située sur le même VPS ne protège ni contre la suppression du serveur ni contre une panne de disque.

Pour une mise à jour ordinaire :

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Après le démarrage, vérifiez docker compose ps, le tableau de bord et une notification de test.

Quel VPS choisir pour Uptime Kuma ?

Pour une petite installation, un VPS Linux avec 1 vCPU et 1 Go de RAM suffit. L’indépendance compte davantage que la puissance : le moniteur doit continuer à fonctionner lorsque le projet principal est indisponible.

Vous pouvez installer Uptime Kuma sur un VPS de tropic.host si les services surveillés se trouvent sur une autre plateforme ou un nœud indépendant. Ubuntu, Docker et une IP fixe permettent de lancer rapidement le tableau de bord, puis d’augmenter les ressources lorsque le nombre de vérifications progresse.

Si la production fonctionne déjà dans la même infrastructure, choisissez un autre nœud ou ajoutez un moniteur externe de secours. Séparer les domaines de panne est plus utile qu’ajouter un cœur de processeur.

Erreurs fréquentes

Erreur	Pourquoi est-ce un problème ?	Meilleure solution
La surveillance est installée avec le projet	Une panne commune fait disparaître le service et les notifications	Utiliser un VPS ou une région distincts
Le port `3001` est exposé publiquement	Le tableau de bord est accessible sans proxy inverse ni HTTPS	Lier le port à `127.0.0.1`
Seul le code `200` est vérifié	Une erreur de l’application peut sembler être une réussite	Ajouter Keyword ou JSON Query
Le tag `latest` est utilisé	Il pointe vers l’ancienne branche v1	Utiliser `louislam/uptime-kuma:2`
La sauvegarde reste sur le même VPS	Elle disparaîtra avec le serveur	Copier le répertoire `data` vers l’extérieur

En bref

Uptime Kuma transforme un petit VPS en centre de surveillance autonome pour les sites, les API, DNS, les ports, les certificats et les tâches en arrière-plan. Keyword aide à repérer une page cassée, JSON Query détecte une réponse d’API incorrecte et Push révèle une sauvegarde ou une tâche cron interrompue.

Pour une installation fiable, séparez la surveillance de la production, fermez le port 3001, activez HTTPS et la 2FA, puis configurez deux canaux de notification. Mettez ensuite en place une sauvegarde externe du répertoire de données et une vérification indépendante d’Uptime Kuma lui-même.

FAQ

Uptime Kuma est-il gratuit ?

Oui. Le projet est open source et distribué sous licence MIT. Seuls l’infrastructure, le domaine et les sauvegardes externes sont payants.

De combien de RAM Uptime Kuma a-t-il besoin ?

Pour une petite installation, 1 Go de RAM constitue un point de départ raisonnable. Pour des centaines de vérifications, un long historique ou Browser Engine, prévoyez 2 Go ou plus.

Peut-on installer Uptime Kuma sans Docker ?

Oui, avec Node.js et PM2. Toutefois, Docker Compose est généralement plus simple à mettre à jour, à migrer et à restaurer sur un VPS.

Peut-on utiliser Uptime Kuma sans domaine ?

Techniquement oui, via l’adresse IP ou un tunnel SSH. Pour un accès permanent depuis Internet, un sous-domaine avec HTTPS est plus sûr.

Uptime Kuma affiche-t-il l’utilisation du CPU, de la RAM et du disque ?

Pas comme un système complet de métriques serveur. Pour surveiller les ressources du serveur, complétez-le avec Prometheus, Netdata, Zabbix ou un autre outil spécialisé.

Retour au blog