Héberger soi-même Uptime Kuma pour des pages de statut et des alertes

Vous voulez savoir dès que votre site, votre API ou votre serveur tombe, et vous voulez une page de statut à montrer à vos clients sans payer un abonnement mensuel pour quelque chose qu’un seul conteneur peut faire. Uptime Kuma est un outil de surveillance libre qui fait les deux : il interroge vos points de terminaison selon un horaire, vous envoie une alerte dès qu’un test échoue, et vous donne une page de statut publique pour montrer le résultat. À la fin de ce guide, vous l’aurez en service sur votre propre serveur, accessible en HTTPS sur votre propre domaine, avec ses données qui survivent réellement à un redémarrage.

Ce qu’il vous faut

• Un petit serveur. Uptime Kuma est un seul processus Node.js avec une base de données SQLite, donc il ne demande pas grand-chose, mais lui donner au moins 1 Go de RAM évite les problèmes de mémoire insuffisante décrits dans la section dépannage plus bas. Un Basic Droplet DigitalOcean avec 1 Go de RAM, 1 vCPU et 25 Go de SSD coûte 6 $US/mois à la date d’aujourd’hui (vérifié sur la page de tarification de DigitalOcean). La gamme optimisée pour les coûts de Hetzner est une solution de rechange raisonnable si vous préférez comparer.
• Un domaine que vous contrôlez, avec la possibilité d’ajouter un enregistrement A.
• Docker et Docker Compose installés sur le serveur (l’étape 2 couvre ça).
• Quelques minutes à votre première visite pour créer le compte administrateur. Uptime Kuma n’a aucun identifiant par défaut : la première personne qui arrive à la page de configuration devient l’administrateur, donc ne laissez pas l’accès ouvert sur Internet avant d’avoir complété cette étape.

Étape 1 : pointez votre domaine vers le serveur

Créez d’abord le serveur, notez son adresse IP publique, puis ajoutez un enregistrement A pour le sous-domaine que vous voulez utiliser, par exemple status.votredomaine.com, qui pointe vers cette IP. La propagation DNS est habituellement rapide, mais peut prendre jusqu’à quelques heures selon les réglages de TTL de votre registraire.

Vous pouvez vérifier que ça s’est bien résolu avec :

dig +short status.votredomaine.com

Vous devriez voir l’adresse IP du serveur s’afficher. Si rien ne s’affiche encore, attendez un peu avant de continuer. Faire cette étape en premier donne le temps au DNS de se stabiliser avant que vous arriviez à l’étape du HTTPS.

Étape 2 : installez Docker

La documentation d’installation d’Uptime Kuma recommande de le faire tourner en conteneur, et c’est la configuration utilisée tout au long de ce guide. Connectez-vous en SSH à votre serveur et installez Docker avec le script officiel :

curl -fsSL https://get.docker.com | sh

Docker Compose est livré comme module avec les installations récentes de Docker, donc une étape d’installation séparée n’est habituellement pas nécessaire. Confirmez que les deux sont bien présents :

docker --version
docker compose version

Vous devriez voir un numéro de version s’afficher pour chacun. Si docker compose version échoue, votre installation de Docker est assez ancienne pour que Compose ne soit pas inclus, et vous devrez installer séparément le paquet docker-compose-plugin.

Étape 3 : écrivez le fichier Compose et lancez Uptime Kuma

Créez un répertoire pour l’application et un fichier compose.yml à l’intérieur :

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

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

volumes:
  uptime-kuma-data:

L’étiquette 1 suit la lignée de la version stable actuelle et se met à jour avec les versions correctives à chaque nouveau téléchargement, plutôt que de figer une version précise. L’élément important est le volume nommé uptime-kuma-data monté à /app/data : c’est là qu’Uptime Kuma garde sa base de données SQLite, et c’est ce qui fait que vos moniteurs, vos réglages de notification et vos pages de statut survivent à un redémarrage ou une reconstruction du conteneur. Sans ce volume, un docker compose down ou un redémarrage du serveur qui recrée le conteneur efface tous les moniteurs que vous avez configurés.

Lancez-le :

docker compose up -d

Vérifiez qu’il tourne :

docker compose ps

Vous devriez voir le service uptime-kuma listé comme running ou healthy. À ce stade, il n’est accessible que sur le port 3001, ce qui est normal, puisque l’étape 5 ajoute un proxy inverse devant.

Étape 4 : créez le compte administrateur et ajoutez votre premier moniteur

Avant même que le DNS et le HTTPS soient en place, vous pouvez quand même accéder à l’application directement par son port pour créer le compte administrateur le plus tôt possible, ce qui referme la fenêtre d’exposition de la page de configuration :

http://<ip-du-serveur>:3001

Le premier écran vous demande de créer un nom d’utilisateur et un mot de passe. Il n’y a aucun identifiant par défaut à changer, seulement une page vierge. Une fois connecté, ajoutez un moniteur depuis le tableau de bord : donnez-lui un nom, un type (HTTP(s), port TCP, ping, DNS, et d’autres sont pris en charge), et la cible à vérifier. Réglez l’intervalle de vérification (60 secondes est un défaut raisonnable pour la plupart des sites) et enregistrez.

Pendant que vous y êtes, allez dans Settings → Notifications et ajoutez au moins un canal de notification (courriel, Slack, Discord, un webhook générique, et des dizaines d’autres sont pris en charge). Utilisez le bouton Test sur la notification avant de vous y fier : une URL de webhook mal configurée ou un fournisseur de courriel qui rejette silencieusement le message est la façon la plus courante de découvrir, en pleine vraie panne, que vos alertes n’ont jamais été livrées.

Vous devriez voir le statut de votre nouveau moniteur passer au vert (ou au rouge, si vous avez pointé vers quelque chose d’inaccessible) après un intervalle de vérification.

Étape 5 : mettez Caddy devant pour le HTTPS

Faire tourner un tableau de bord de surveillance sur un simple port HTTP, sans certificat et sans domaine, convient pour tester mais pas pour quelque chose sur lequel vous comptez réellement. Caddy est un proxy inverse qui demande et renouvelle automatiquement un certificat Let’s Encrypt, sans configuration séparée de certbot.

Installez Caddy directement sur le serveur (en dehors du fichier Compose, pour qu’il puisse se lier proprement aux ports 80 et 443) :

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

Remplacez /etc/caddy/Caddyfile par :

status.votredomaine.com {
	reverse_proxy localhost:3001
}

Rechargez Caddy pour appliquer le changement :

sudo systemctl reload caddy

Caddy demande le certificat la première fois qu’il voit une requête pour ce nom d’hôte, ce qui ne fonctionne que si l’enregistrement A de l’étape 1 pointe déjà vers ce serveur. Vous devriez voir https://status.votredomaine.com afficher Uptime Kuma avec un cadenas valide, et les requêtes http:// vers le même nom d’hôte devraient être redirigées automatiquement vers HTTPS. Une fois que ça fonctionne, fermez l’accès direct au port 3001 au niveau du pare-feu pour que l’application ne soit accessible que par Caddy.

Étape 6 : sauvegardez le volume de données

Tout ce qui compte (moniteurs, réglages de notification, configuration des pages de statut, historique) vit dans le fichier SQLite à l’intérieur du volume uptime-kuma-data. Sauvegardez-le selon un horaire plutôt que de découvrir que vous en avez besoin en plein incident réel.

Une approche simple compatible avec cron, exécutée depuis l’hôte :

docker run --rm \
  -v uptime-kuma_uptime-kuma-data:/data \
  -v ~/uptime-kuma-backups:/backup \
  alpine tar czf /backup/uptime-kuma-$(date +%F).tar.gz -C /data .

Ajoutez ça comme tâche cron quotidienne (crontab -e) et gardez les archives de la dernière semaine ou deux. Vous devriez voir un nouveau fichier .tar.gz apparaître dans ~/uptime-kuma-backups après l’exécution. Pour restaurer, arrêtez le conteneur, extrayez l’archive dans le même chemin de volume, et relancez-le.

Étape 7 : les mises à jour plus tard

Comme le fichier Compose fixe l’étiquette mobile 1 plutôt qu’une version corrective précise, un nouveau téléchargement récupère la dernière version corrective de cette lignée :

docker compose pull
docker compose up -d

Docker recrée le conteneur avec la nouvelle image tout en laissant le volume nommé intact, donc vos données ne sont pas touchées. Vérifiez les notes de version sur la page des releases GitHub d’Uptime Kuma avant un passage à une version majeure en particulier, puisque celles-ci peuvent inclure des changements non rétrocompatibles qu’une version corrective n’aurait pas.

Le raccourci : faites-le avec Railyard

Tout ce qui précède est la voie manuelle complète, et c’est une façon raisonnable de faire tourner ceci si vous voulez posséder chaque pièce vous-même. Si vous préférez éviter l’approvisionnement du serveur, l’installation de Docker, le fichier Compose et la configuration du proxy inverse pour obtenir la même application en service, le gabarit Uptime Kuma de Railyard déploie la même image avec le volume de données déjà monté à /app/data et le HTTPS déjà pris en charge. Il n’y a rien à configurer après le déploiement : aucun identifiant par défaut non plus, vous créez le compte administrateur à votre première visite, exactement comme dans la voie manuelle. C’est la même application, la même étape de configuration, simplement sans la gestion du serveur entre les deux.

Si vous découvrez Railyard de façon générale, le démarrage rapide et le déploiement avec un bouton en un clic couvrent les bases, et les coûts d’hébergement détaillent ce qu’une petite application comme celle-ci coûte habituellement selon les fournisseurs.

Dépannage

« Bind for 0.0.0.0:3001 failed: port is already allocated ». Quelque chose d’autre sur le serveur utilise déjà le port 3001, souvent une tentative précédente de faire tourner le conteneur qui n’a pas été retirée correctement. Vérifiez avec docker ps -a et retirez le conteneur périmé, ou changez le côté hôte du mappage de port dans compose.yml (par exemple "3002:3001") et ajustez la cible du proxy inverse Caddy en conséquence.

Caddy n’arrive pas à émettre de certificat. C’est presque toujours une question de DNS, pas de Caddy. Si l’enregistrement A de l’étape 1 ne s’est pas encore propagé, ou pointe vers la mauvaise IP, la requête de validation de Let’s Encrypt n’atteint jamais votre serveur et la demande de certificat échoue silencieusement dans les journaux de Caddy (sudo journalctl -u caddy -n 50). Relancez la commande dig de l’étape 1 pour confirmer que l’enregistrement pointe vers la bonne IP avant de chercher ailleurs.

Les moniteurs ont disparu après un redémarrage ou un redéploiement. Ça veut dire que le conteneur tournait sans le volume nommé, ou avec le volume monté au mauvais chemin. /app/data est le seul chemin où Uptime Kuma écrit sa base de données. Si vous avez lancé un docker run rapide sans -v pour tester quelque chose, les données de ce conteneur disparaissent dès qu’il est retiré. Vérifiez que docker volume ls montre bien uptime-kuma_uptime-kuma-data et que c’est celui-là qui est monté dans votre fichier compose.

Les notifications n’arrivent pas vraiment. Uptime Kuma consigne un échec d’envoi de notification dans son propre journal d’événements, mais c’est facile à manquer si vous n’y portez pas attention. Utilisez toujours le bouton Test dans Settings → Notifications juste après avoir ajouté un canal, pas seulement au moment où vous configurez un moniteur. Des URL de webhook légèrement erronées, des fournisseurs de courriel qui exigent un mot de passe d’application plutôt que votre mot de passe habituel, et des jetons Slack expirés sont les causes les plus courantes.

Le conteneur redémarre sans cesse sur un très petit serveur. Sur un droplet de 512 Mo, le processus Node.js d’Uptime Kuma peut se faire tuer par manque de mémoire sous charge, surtout si vous ajoutez beaucoup de moniteurs avec des intervalles de vérification courts ou si vous activez des moniteurs qui utilisent un navigateur sans tête. dmesg | grep -i "out of memory" le confirmera. La solution, c’est plus de RAM, pas plus de réglages : un forfait de 1 Go est le minimum réaliste pour une exploitation confortable, sans surveillance constante.

FAQ

Est-ce qu’Uptime Kuma est gratuit ? Oui, c’est un logiciel libre (licence MIT) et auto-hébergé, donc il n’y a aucun abonnement. Vous payez seulement le serveur sur lequel il tourne.

Est-ce que j’ai besoin d’une base de données ? Non. Uptime Kuma utilise une base de données SQLite intégrée dans son propre volume de données, donc il n’y a rien d’autre à approvisionner ou à connecter.

Est-ce que je peux surveiller plus d’un site ou serveur à partir d’une seule instance ? Oui, une seule instance d’Uptime Kuma peut faire tourner n’importe quel nombre de moniteurs, chacun vérifié indépendamment selon son propre horaire et son propre type.

Est-ce que la page de statut est publique par défaut ? Les pages de statut sont quelque chose que vous créez et publiez de façon délibérée depuis le tableau de bord. Les moniteurs individuels ne sont pas exposés tant que vous ne les ajoutez pas à une page de statut que vous choisissez de rendre publique.

En quoi c’est différent d’UptimeRobot ou de Pingdom ? Ce sont des services hébergés que vous payez mensuellement et dont vous ne contrôlez pas l’infrastructure. Uptime Kuma vous donne le même ensemble de fonctionnalités de base (vérifications HTTP/TCP/ping, alertes, pages de statut publiques) en tournant sur un serveur que vous possédez, avec votre historique de surveillance qui reste dans votre propre base de données plutôt que chez un fournisseur.

Une fois en service et sauvegardé, c’est l’une des choses les moins exigeantes à héberger soi-même : ça surveille tout le reste à votre place, et ça ne vous demande quelque chose que lorsque quelque chose ne va vraiment pas.