Beszel et Uptime Kuma, simple et efficace

Tout le monde n'a pas besoin d'une plateforme de supervision à trois étages. Pour une poignée de serveurs, un site et une messagerie, il faut surtout deux choses : être prévenu quand un service tombe, et comprendre rapidement pourquoi. Beszel et Uptime Kuma font exactement cela, s'installent en une heure, et ne demandent ensuite presque rien. C'est notre combinaison favorite pour les petites structures, et un excellent filet de secours sur les grosses.

01Deux regards complémentaires

Beszel regarde l'intérieur des machines. Un hub central reçoit les mesures de petits agents installés sur chaque serveur : processeur, mémoire, disques, réseau, températures, et consommation de chaque conteneur Docker ou Podman. Il garde l'historique et déclenche des alertes sur seuil.

Uptime Kuma regarde depuis l'extérieur, comme le ferait un client. Il interroge un site, un port, un nom DNS ou un certificat à intervalle régulier, et prévient dès que la réponse manque ou change.

02Où installer quoi

C'est la seule décision qui compte vraiment, et elle se prend avant toute installation.

• Uptime Kuma ne doit jamais tourner sur l'infrastructure qu'il surveille. Si le serveur tombe, la sonde tombe avec lui et personne n'est prévenu. Un petit VPS chez un autre hébergeur, ou un Raspberry Pi au bureau sur une autre connexion, fait parfaitement l'affaire.
• Le hub Beszel peut vivre sur l'infrastructure, dans une machine virtuelle ou un conteneur LXC dédié. S'il tombe, vous perdez les graphiques, pas l'alerte de disponibilité.
• Les deux se surveillent mutuellement. Uptime Kuma vérifie que le hub Beszel répond, et un agent Beszel installé sur la machine d'Uptime Kuma surveille ses ressources.

03Installer le hub Beszel

Le hub est un binaire unique qui embarque sa base de données et son interface. Nous le déployons en conteneur, avec une version épinglée plutôt que latest : une mise à jour doit être une décision, pas une surprise.

services:
  beszel:
    # epinglez la version relevee sur la page des releases du projet
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    ports:
      - "127.0.0.1:8090:8090"
    volumes:
      - ./beszel_data:/beszel_data

mkdir -p /opt/beszel && cd /opt/beszel
docker compose up -d
docker compose logs -f beszel

Le port n'est publié que sur l'interface locale : l'accès se fait par un proxy inverse qui porte le certificat TLS. Au premier accès, l'interface demande de créer le compte administrateur.

server {
    listen 443 ssl;
    http2 on;
    server_name beszel.exemple.fr;

    ssl_certificate     /etc/letsencrypt/live/beszel.exemple.fr/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beszel.exemple.fr/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8090;
        proxy_http_version 1.1;
        # les agents et l'interface utilisent des WebSocket
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

04Déployer les agents

Dans l'interface du hub, le bouton d'ajout d'un système affiche tout ce dont l'agent a besoin : la clé publique du hub et un jeton. Deux modes de connexion existent. Dans le premier, l'agent écoute sur le port 45876 et le hub vient le chercher. Dans le second, que nous préférons, l'agent ouvre lui-même une connexion WebSocket vers le hub : aucun port entrant à ouvrir sur les serveurs surveillés, ce qui simplifie le pare-feu et les sites distants.

Sur un serveur classique, en binaire

La boîte de dialogue fournit une commande d'installation complète, clé et jeton déjà renseignés. Elle télécharge le binaire, crée un utilisateur dédié et un service systemd. Copiez-la telle quelle depuis l'interface plutôt que de la reconstituer à la main.

systemctl status beszel-agent
journalctl -u beszel-agent -n 30 --no-pager

Sur un hôte Docker

services:
  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    # le mode hote est necessaire pour voir les interfaces reseau reelles
    network_mode: host
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./beszel_agent_data:/var/lib/beszel-agent
    environment:
      LISTEN: 45876
      KEY: "ssh-ed25519 AAAA... cle publique fournie par le hub"
      TOKEN: "jeton fourni par le hub"
      HUB_URL: "https://beszel.exemple.fr"

Sur un noeud Proxmox VE

Installez l'agent en binaire directement sur l'hôte, pas dans un conteneur : c'est le seul moyen de voir les vrais disques et les vraies interfaces. Beszel ne remplace pas une supervision de cluster, il ne sait rien du quorum ni de Ceph. Il donne en revanche une vue claire de la charge de chaque noeud, ce qui suffit sur un petit cluster.

05Les alertes de Beszel

Les alertes se règlent par système, depuis l'icône de cloche. Nous partons de ces seuils, puis nous les ajustons à la plateforme après une ou deux semaines d'observation.

Les notifications passent par des URL de service : Telegram, Discord, Slack, Matrix, Gotify, ntfy, courriel, ou un webhook générique. Une adresse par canal, et un bouton de test qui évite de découvrir une faute de frappe le jour de la panne.

06Installer Uptime Kuma 2

La version 2.0 est sortie en octobre 2025, après un long cycle de bêta. Elle apporte la prise en charge de MariaDB à côté de SQLite, le fonctionnement sans privilèges root dans Docker, et une interface nettement plus rapide au-delà d'une centaine de sondes. Une installation neuve part directement sur la 2.

services:
  uptime-kuma:
    # le tag majeur suit les correctifs de la 2.x sans sauter de version majeure
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./kuma_data:/app/data

Au premier lancement, l'assistant demande le moteur de base de données. Pour quelques centaines de sondes, SQLite suffit largement et ne demande aucune administration. Le MariaDB embarqué devient intéressant au-delà, ou si vous avez souffert des lenteurs de la version 1 sur un gros volume.

07Les sondes qui servent vraiment

Uptime Kuma propose une trentaine de types de sondes. Ce sont toujours les mêmes six qui font le travail.

La sonde push, l'outil le plus sous-estimé

Toutes les autres sondes vérifient que quelque chose répond. La sonde push vérifie que quelque chose s'est produit. Uptime Kuma attend un appel ; s'il ne vient pas dans le délai, c'est l'alerte. C'est le moyen le plus simple de savoir qu'une sauvegarde de nuit n'a pas tourné, plutôt que de le découvrir le jour où il faut restaurer.

#!/bin/sh
set -e

# ... la sauvegarde proprement dite ...
vzdump --all --storage pbs --mode snapshot --quiet 1

# n'est atteint que si tout ce qui precede a reussi, grace a set -e
curl -fsS -m 10 --retry 3 \
  "https://kuma.exemple.fr/api/push/JETON_DE_LA_SONDE?status=up&msg=OK" >/dev/null

08Notifications et page de statut

Uptime Kuma connaît plus de quatre-vingt-dix services de notification. Deux principes suffisent :

• Deux canaux indépendants, par exemple Telegram et un courriel envoyé par un service externe. Si votre serveur de messagerie fait partie de ce qui est surveillé, il ne peut pas être le seul canal d'alerte.
• Des nouvelles tentatives avant d'alerter. Trois essais à vingt secondes d'intervalle éliminent la plupart des fausses alertes dues à un hoquet réseau, pour une minute de délai seulement.

La page de statut publique est un bonus apprécié des clients. Elle affiche l'état de chaque service, l'historique de disponibilité et les annonces de maintenance. Publiée sur un sous-domaine du type statut.exemple.fr, elle épargne une bonne partie des appels « c'est en panne chez vous ? » lors d'un incident.

09Sauvegarde et mises à jour

# le plus sur : conteneur arrete, copie du dossier, redemarrage
cd /opt/uptime-kuma
docker compose stop
tar czf /srv/sauvegardes/kuma-$(date +%F).tar.gz kuma_data
docker compose start

cd /opt/beszel
docker compose stop
tar czf /srv/sauvegardes/beszel-$(date +%F).tar.gz beszel_data
docker compose start

# lire les notes de version d'abord, sauvegarder ensuite, mettre a jour enfin
docker compose pull
docker compose up -d
docker image prune -f

Côté agents Beszel installés en binaire, la commande beszel-agent update remplace le binaire, et le service redémarre. Gardez hub et agents dans des versions proches : le hub accepte des agents un peu plus anciens, mais pas indéfiniment.

10Quand passer à plus gros

Ce duo couvre très bien son terrain. Il devient trop juste dans quatre situations :

• plusieurs équipes doivent recevoir des alertes différentes, avec des escalades et des plages d'astreinte ;
• il faut superviser des équipements réseau en SNMP, des onduleurs, des baies de stockage ;
• le parc dépasse quelques dizaines de machines, et la configuration à la main devient une corvée ;
• vous avez besoin de corréler finement des métriques applicatives sur de longues périodes.

Les trois premiers cas mènent à Zabbix, le dernier à la pile Grafana. Dans les deux cas, gardez Uptime Kuma : une sonde externe, simple et indépendante, reste utile à côté de n'importe quelle plateforme.