Installer Uptime Kuma sur un VPS KVM avec Docker

Uptime Kuma est un outil libre de supervision : il interroge vos sites, API, ports ou noms de domaine à intervalle régulier, vous prévient quand l'un d'eux tombe et publie des pages de statut. Ce guide l'installe en version 2.5.10 avec Docker Compose, publié en HTTPS sur https://nom.vps.heberghub.app.

Un conseil avant de commencer : un outil de supervision ne peut pas signaler sa propre panne. Installez Uptime Kuma sur un autre VPS que les services qu'il surveille, ou surveillez-le à son tour depuis ailleurs.

Ce qu'il vous faut

• Un VPS KVM : Docker ne s'installe correctement que sur une machine virtuelle, pas sur un VPS LXC.
• Docker et Docker Compose installés : voir Installer Docker sur un VPS KVM.
• Un accès SSH par clé (Première connexion SSH) et un VPS sécurisé (Sécuriser un VPS Debian).
• Le port 80 libre.

Dans notre essai, Uptime Kuma occupait environ 150 Mo de mémoire au repos, sans sonde.

1. Le fichier compose.yaml

mkdir -p /opt/uptime-kuma && cd /opt/uptime-kuma
nano compose.yaml

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2.5.10
    restart: unless-stopped
    ports:
      - "80:3001"                # le frontal HTTPS arrive sur le port 80, Uptime Kuma écoute sur 3001
    volumes:
      - data:/app/data           # base SQLite et réglages : volume local, jamais un partage NFS

volumes:
  data:

• Seul le port 80 est publié. Docker contourne ufw : ne publiez pas d'autre port, en particulier pas le 3001.
• Le HTTPS est géré en amont. Le certificat de nom.vps.heberghub.app est géré par le frontal ; votre VPS reçoit le trafic en HTTP sur son port 80, avec l'en-tête X-Forwarded-Proto: https. N'installez pas de certificat dans le VPS pour ce nom.
• Le volume reste local. La base SQLite a besoin de verrous de fichiers fiables : la documentation du projet déconseille les partages réseau comme NFS.

2. Premier lancement

docker compose up -d
docker compose logs -f uptime-kuma

Quand le journal affiche Waiting for user action..., quittez avec Ctrl+C et ouvrez https://nom.vps.heberghub.app.

1. Quelle base de données souhaitez-vous utiliser ? Choisissez SQLite, qu'Uptime Kuma recommande pour les petits déploiements. L'image propose aussi une MariaDB intégrée ou une MariaDB externe, plus gourmandes. Le passage de SQLite à MariaDB n'est pas pris en charge ensuite : décidez dès maintenant.
2. Créer votre compte administrateur : nom d'utilisateur et mot de passe solide.
3. Ajouter une nouvelle sonde : type HTTP(s), l'adresse du site, un intervalle de vérification.

3. Derrière le frontal HTTPS

WebSocket. L'interface d'Uptime Kuma reçoit ses mises à jour par WebSocket. Le frontal les accepte : rien à configurer. Si la connexion est coupée, l'interface se reconnecte d'elle-même.

Adresse des visiteurs. Dans Paramètres > Proxy inverse, rubrique En-têtes HTTP, réglez Proxy de confiance sur Oui. Uptime Kuma lit alors les en-têtes X-Forwarded-*, comme le recommande sa documentation quand il n'est joint que par un proxy.

Adresse publique. Dans Paramètres > Général, renseignez URL principale avec https://nom.vps.heberghub.app.

Pages de statut sur votre domaine. Ajoutez un domaine dans l'espace client (TXT _heberghub-verify et CNAME vers nom.vps.heberghub.app, voir Relier un nom de domaine). Il arrive lui aussi en HTTP sur le port 80. Dans la page de statut, ajoutez ce nom sous Noms de domaine : https://statut.votredomaine.fr affiche directement la page. Uptime Kuma ne fonctionne pas dans un sous-dossier (/statut) : utilisez un nom de domaine ou un sous-domaine.

4. Recevoir les alertes

Les alertes se règlent dans Paramètres > Notifications, bouton Créer une notification.

Par e-mail. Sur votre VPS, le port 25 est fermé en sortie (anti-spam) ; les ports 465 et 587 sont ouverts, avec un nombre de connexions par minute limité. Choisissez le type Courriel (SMTP) et le serveur SMTP authentifié de votre messagerie ou d'un service d'envoi :

Le bouton Tester envoie un message d'essai. Si beaucoup de sondes tombent en même temps, la limite de connexions par minute peut retarder des e-mails : pour les alertes urgentes, doublez l'e-mail d'une notification par messagerie instantanée.

Par messagerie ou API. Uptime Kuma propose des dizaines de types de notification qui passent par HTTPS : Discord, Telegram, Matrix, Slack, ntfy, webhook, ainsi que plusieurs services d'envoi d'e-mails par API.

Cochez Activé par défaut pour les futures sondes, et Appliquer sur toutes les sondes existantes pour celles déjà créées.

5. Mettre à jour

Lisez les notes de version sur la page du projet, sauvegardez (section suivante), remplacez 2.5.10 par la nouvelle version dans compose.yaml, puis :

docker compose pull && docker compose up -d

6. Sauvegarder

Depuis la version 2, l'ancienne fonction d'export JSON a disparu : la sauvegarde du dossier de données est la seule méthode prise en charge. Arrêtez le conteneur le temps de l'archive, pour que la base soit refermée proprement :

cd /opt/uptime-kuma
docker compose stop
tar -czf uptime-kuma-$(date +%F).tar.gz -C /var/lib/docker/volumes/uptime-kuma_data/_data .
docker compose start

Le chemin vaut pour le dossier /opt/uptime-kuma (docker volume ls donne le nom du volume). Les VPS ne sont pas sauvegardés automatiquement : copiez l'archive et compose.yaml hors du VPS. L'archive contient kuma.db, vos sondes, vos notifications avec leurs identifiants SMTP : gardez-la dans un endroit protégé. Pour restaurer, arrêtez le conteneur, videz le volume, décompressez-y l'archive, puis relancez.

Mot de passe oublié

Uptime Kuma n'envoie pas d'e-mail de réinitialisation. Depuis le VPS :

cd /opt/uptime-kuma
docker compose exec uptime-kuma npm run reset-password

Saisissez deux fois le nouveau mot de passe ; les autres sessions ouvertes sont déconnectées.

Plusieurs applications sur le VPS

Si une autre application doit répondre sur le port 80, placez un relais (Caddy, nginx ou Traefik) sur ce port : il répartit par nom de domaine, et Uptime Kuma ne publie plus de port. Le relais doit transmettre les en-têtes Upgrade et Connection, sans quoi l'interface ne se connecte pas. Voir Installer Docker sur un VPS KVM.

Problèmes fréquents

Besoin d'aide ?

Ouvrez un ticket depuis votre espace client avec le nom du VPS, la sortie de docker compose ps et les dernières lignes de docker compose logs uptime-kuma, sans mot de passe ni identifiant SMTP.