Héberger Checkmate sur un VPS infogéré, c'est garder la surveillance de vos sites et de vos serveurs sur une machine à vous, que nos équipes tiennent à jour et supervisent jour et nuit. Checkmate est une application libre de supervision, sous licence AGPL-3.0 : disponibilité, temps de réponse, incidents, alertes et pages de statut. Ce guide suit son image Docker officielle, à la version v4.0.0, et nous avons lancé chaque commande sur un VPS Simafri avant de l'écrire : l'installation avec Docker Compose, HTTPS, le premier compte, les sondes et les alertes, les sauvegardes et les mises à jour.
Par Simon Vasconcelos Lee
Publié le 17 novembre 2026Lecture : 12 minutes
ghcr.io/bluewave-labs/checkmate et MongoDB 8.0, avec le port publié sur 127.0.0.1 derrière un proxy inverse en HTTPS.JWT_SECRET, ENCRYPTION_KEY et votre adresse publique dans CLIENT_HOST, et ajoutez NODE_ENV=production, que le fichier de référence omet.mongodump et gardez votre fichier .env, puis mettez à jour en changeant l'étiquette de l'image : les migrations se lancent seules au démarrage.Checkmate interroge vos services à intervalles réguliers, enregistre chaque réponse et son temps de réponse, et vous alerte quand quelque chose ne répond plus. Son éditeur, BlueWave Labs, le présente comme un outil auto-hébergé pour suivre en temps réel le matériel des serveurs, la disponibilité, les temps de réponse et les incidents.
Checkmate est publié sous la GNU Affero General Public License, version 3 (AGPL-3.0). Vous pouvez l'utiliser gratuitement, pour vous, votre entreprise ou vos clients, le copier et le modifier.
Sa clause particulière porte sur l'usage en réseau : si vous modifiez Checkmate et laissez d'autres personnes utiliser votre version modifiée par le réseau, vous devez leur proposer son code source. Faire tourner l'image officielle sans la modifier, comme dans ce guide, ne crée aucune obligation de ce type. Le logiciel est fourni sans garantie.
La documentation fixe un plancher modeste : n'importe quel VPS Linux doté d'au moins 1 Go de mémoire vive. Elle ajoute que MongoDB occupe environ 400 Mo sur une instance qui interroge plus de 300 serveurs chaque minute.
La taille du serveur dépend donc du nombre de sondes, de leur intervalle et de l'historique que vous gardez. Sur un VPS infogéré, décrivez-nous votre usage, et nous vous recommandons la taille qui convient.
Depuis la version 3.10, Checkmate se livre en une seule image, ghcr.io/bluewave-labs/checkmate, qui sert à la fois l'interface et l'API. MongoDB tourne à côté, dans son propre conteneur. Sur un serveur doté de Docker Engine et de son extension Compose, installés depuis le dépôt de Docker pour Ubuntu, créez un dossier comme /opt/checkmate et placez-y ce compose.yaml, qui reprend le fichier de référence du projet :
services:
checkmate:
image: ghcr.io/bluewave-labs/checkmate:v4.0.0
restart: always
ports:
- "127.0.0.1:52345:52345"
environment:
- DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
- CLIENT_HOST=https://status.example.com
- JWT_SECRET=${JWT_SECRET:?set JWT_SECRET in .env}
- ENCRYPTION_KEY=${ENCRYPTION_KEY:?set ENCRYPTION_KEY in .env}
- NODE_ENV=production
stop_grace_period: 60s
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
interval: 15s
timeout: 3s
start_period: 60s
start_interval: 2s
retries: 3
depends_on:
mongodb:
condition: service_healthy
mongodb:
image: mongo:8.0
restart: always
command: ["mongod", "--quiet", "--bind_ip_all"]
volumes:
- mongo-data:/data/db
healthcheck:
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/27017"]
interval: 5s
timeout: 30s
start_period: 0s
start_interval: 1s
retries: 30
volumes:
mongo-data:
Les deux secrets vont dans un fichier .env posé à côté, que Docker Compose lit de lui-même. Créez-le lisible par root seul, puis démarrez la pile :
umask 077
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -base64 32)" > .env
umask 022
docker compose up -d
docker compose ps
127.0.0.1 : le fichier de référence le publie sans adresse, et Docker l'ouvre alors sur toutes les adresses du serveur. Publié en local, il ne s'atteint que par le proxy inverse.CLIENT_HOST est l'adresse que tapent vos utilisateurs, avec https://. Checkmate s'en sert pour les contrôles entre origines et pour les liens de ses alertes et de ses e-mails.NODE_ENV=production : le README la demande sur les vrais déploiements. Sans elle, l'application tourne en mode développement, ce qui désactive la limitation de débit de l'API.ENCRYPTION_KEY est facultative dans le fichier de référence. Elle chiffre les secrets que Checkmate enregistre, et la v4.0.0 l'exige pour les sondes Docker en TLS et pour Checkmate Connect. Posez-la dès le départ : c'est plus simple que de l'ajouter ensuite.latest et la tire à chaque démarrage. Une version complète, ici v4.0.0, vous laisse choisir le moment de chaque mise à jour.mongo-data garde toutes vos données : sondes, contrôles, utilisateurs et réglages.Le premier démarrage lance les migrations de la base ; sur notre VPS de test, l'application s'est déclarée en bonne santé en moins de dix secondes. Pour vérifier qu'elle répond :
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:52345/
curl -s http://127.0.0.1:52345/api/v1/auth/users/superadmin
La première commande répond 200. La seconde répond "data":false tant qu'aucun compte n'existe, et true une fois le Superadmin créé.
Checkmate n'a aucun compte par défaut. La première personne qui s'inscrit devient Superadmin : créez donc le vôtre juste après le premier démarrage, avant d'ouvrir l'adresse au public. Un tunnel SSH fait apparaître le port 52345 du serveur sur votre poste, à l'adresse http://localhost:52345 ; ajoutez -p et le port SSH affiché dans votre espace client.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345 : Checkmate affiche sa page d'inscription.Dès lors, l'inscription publique est fermée : sur notre VPS de test, chaque nouveau visiteur était renvoyé vers la page de connexion, et l'adresse d'inscription y menait aussi. Les autres personnes rejoignent l'instance sur invitation, depuis la section Team des réglages du compte, avec le rôle User ou Admin. L'invitation part par e-mail, elle demande donc les réglages SMTP présentés plus bas, et son lien expire au bout d'une heure.
| Rôle | Ce qu'il peut faire |
|---|---|
| User | Voir toutes les sondes, le tableau de bord, les contrôles, les incidents, les pages de statut et les réglages, sans rien modifier |
| Admin | Tout ce que peut un User, plus les sondes, les canaux de notification, les incidents, les fenêtres de maintenance, les pages de statut, les invitations et les réglages généraux, SMTP compris |
| Superadmin | Tout ce que peut un Admin, plus la création directe de comptes, la modification d'un autre utilisateur, le changement d'un rôle ou d'un mot de passe |
Depuis la v4.0.0, les étiquettes, les pages de statut et les proxys relèvent du rôle Admin : un User qui pouvait les gérer auparavant perd cet accès après la mise à jour.
Le conteneur sert Checkmate en HTTP, sur le port 52345. HTTPS se règle sur un proxy inverse placé devant : la documentation cite Caddy, Traefik et nginx. Nous avons testé Caddy, installé depuis son dépôt officiel pour Debian et Ubuntu : il obtient lui-même le certificat Let's Encrypt, le renouvelle, et transmet par défaut l'en-tête Host et les en-têtes X-Forwarded-*.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST doit porter la même adresse en https:// que le proxy. Après l'avoir changée, lancez docker compose up -d pour recréer le conteneur.Les alertes par e-mail et les invitations passent par une connexion SMTP commune à tout le serveur, réglée dans « Settings », onglet « Email » : serveur, port, utilisateur, mot de passe et adresse d'expédition, puis « Save » et « Test ». Sur un VPS Simafri, utilisez un serveur SMTP authentifié, sur le port 587 ou 465 : celui de la messagerie de votre domaine, ou d'un service d'envoi. Créez ensuite une notification par e-mail avec les adresses à alerter, et rattachez-la à vos sondes.
Slack, Discord, Teams, Telegram et les autres canaux se créent de la même façon, dans « Notifications », chacun avec son adresse de webhook ou son jeton, et chacun avec un bouton « Test ».
Une sonde Heartbeat surveille une tâche qui tourne seule, comme une sauvegarde de nuit. Générez la clé de ping de l'équipe dans « Settings », onglet « Monitoring » (elle ne s'affiche qu'une fois), créez une sonde Heartbeat avec un slug et une fenêtre d'alerte, puis appelez son URL de ping à la fin de la tâche :
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"
Ajouter /fail, ou le code de sortie de la tâche, à l'URL fait passer la sonde en panne aussitôt, sans attendre la fin de la fenêtre.
Dans « Status pages », un Admin publie une page qui liste les sondes choisies et leur disponibilité, pour vos clients ou votre équipe. Depuis la v4.0.0, chaque page de statut a un fuseau horaire, UTC par défaut.
Tout vit à deux endroits : la base MongoDB, dans le volume mongo-data, et votre fichier .env. Gardez ce dernier à l'abri : ENCRYPTION_KEY sert à lire les secrets enregistrés dans la base, et JWT_SECRET garde vos utilisateurs connectés. L'image MongoDB contient mongodump :
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak
Planifiez cette copie et envoyez-la hors du serveur ; une sonde Heartbeat peut vous prévenir si elle cesse un jour de tourner. Posées sur le disque, les archives entrent aussi dans les sauvegardes de nuit du serveur.
Sur la même installation ou sur une nouvelle, avec le même .env, arrêtez l'application, chargez l'archive, puis redémarrez-la :
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate
Nous avons testé le cycle complet sur notre VPS : sauvegarde, base réellement supprimée, restauration. La sonde et le compte sont revenus, et la connexion a de nouveau fonctionné aussitôt.
Checkmate v4.0.0 propose aussi des sauvegardes chiffrées dans le cloud par Checkmate Connect, un service facultatif, gratuit pendant sa bêta, qui demande ENCRYPTION_KEY et un Superadmin pour inscrire l'installation. Les copies ci-dessus fonctionnent sans lui.
Lisez les notes de version, faites une sauvegarde, changez l'étiquette de l'image dans le compose.yaml, puis tirez la nouvelle image et recréez le conteneur. Les migrations de la base se lancent seules au démarrage :
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump et mongorestore. Aucune nouvelle variable d'environnement n'est requise.checkmate-client, checkmate-backend et checkmate-mongo, qui ne sont plus mises à jour. Passez à ghcr.io/bluewave-labs/checkmate en gardant votre service MongoDB et son volume ; les variables UPTIME_APP_* ne sont plus lues.Checkmate envoie un rapport anonyme par jour : un identifiant d'installation, la version, le mode d'installation et le nombre de sondes de chaque type, jamais vos URL ni vos résultats. Il l'annonce dans son journal au démarrage. Pour la désactiver, ajoutez TELEMETRY_ENABLED=false à l'environnement du service checkmate, puis lancez docker compose up -d.
L'auto-hébergement demande de tenir le serveur en plus de l'application. Sur un VPS infogéré, nos équipes prennent le serveur en main et suivent votre instance de manière proactive ; Checkmate reste votre logiciel, avec ses sondes et vos réglages.
| Sujet | Nos équipes | Vous |
|---|---|---|
| Le serveur | Mises à jour du système et de la sécurité, interventions sur le serveur comprises | Le moment qui convient à votre activité |
| La supervision | Serveur suivi 24 h/24 et 7 j/7, avec intervention sans attendre votre appel | Vos propres sondes, alertes et pages de statut dans Checkmate |
| Checkmate | Suivi proactif : erreurs, lenteurs, base de données et espace disque repérés, correction recommandée | Son installation, ses mises à jour et ses réglages, que vous appliquez, vous ou votre assistant IA |
| Les utilisateurs et les alertes | Le serveur qui les porte, surveillé et sauvegardé | Les comptes, les rôles, les invitations et les canaux de notification |
| Les sauvegardes | Chaque nuit, chiffrées et gardées hors de la machine ; restauration comprise | Les exports de base propres à Checkmate, et la demande de restauration, quand vous en avez besoin |
| La migration | Votre serveur actuel migré, offert | Le moment de la bascule |
Si vous préférez que nos équipes interviennent dans l'application elle-même, cette prestation se facture à l'heure ou au forfait, avec un chiffrage communiqué avant l'intervention.
Avec un VPS infogéré Simafri, nos équipes tiennent à jour le serveur de votre instance Checkmate, le surveillent jour et nuit et interviennent sans attendre votre appel ; elles suivent aussi votre instance de manière proactive et vous recommandent les corrections utiles, que vous appliquez, vous ou votre assistant IA. Les sauvegardes sont chiffrées chaque nuit et gardées hors de la machine, leur restauration est comprise, et la migration de votre serveur actuel est offerte.
Oui. Checkmate est sous licence AGPL-3.0 : vous pouvez le faire tourner pour vous, votre équipe ou vos clients, sans licence à acheter. Si vous le modifiez et le laissez utiliser à d'autres par le réseau, vous partagez vos modifications. Reste le coût du serveur qui le fait tourner.
Reprenez le compose.yaml de référence : l'image ghcr.io/bluewave-labs/checkmate et MongoDB 8.0. Placez JWT_SECRET et ENCRYPTION_KEY dans un fichier .env, réglez CLIENT_HOST sur votre adresse en https et NODE_ENV sur production, publiez le port 52345 sur 127.0.0.1, lancez docker compose up -d, et placez un proxy inverse en HTTPS devant.
Il n'y en a pas. La première personne qui s'inscrit sur une nouvelle instance devient Superadmin. Créez votre compte juste après le premier démarrage, par un tunnel SSH ; ensuite, les visiteurs sont renvoyés vers la page de connexion et les nouveaux utilisateurs rejoignent l'instance sur invitation.
La documentation demande un VPS Linux doté d'au moins 1 Go de mémoire vive. Sur notre VPS de test, une installation neuve occupait environ 300 Mo pour Checkmate et 280 Mo pour MongoDB. Le disque grandit avec le nombre de sondes, leur intervalle et l'historique que vous gardez, 90 jours par défaut.
Réglez la connexion SMTP dans Settings, onglet Email : serveur, port 587 ou 465, utilisateur, mot de passe et expéditeur, puis Save et Test. Créez une notification par e-mail avec les adresses à alerter et rattachez-la à vos sondes. Les invitations utilisent les mêmes réglages.
Exportez la base MongoDB avec docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, et gardez une copie de votre fichier .env, dont la variable ENCRYPTION_KEY sert à lire les secrets enregistrés. Restaurez avec mongorestore --archive --gzip --drop, l'application arrêtée.
Lisez les notes de version et faites une sauvegarde, changez l'étiquette de l'image dans compose.yaml, puis lancez docker compose pull et docker compose up -d. Les migrations de la base se lancent seules au démarrage.
Un VPS infogéré couvre le serveur : système, sécurité, supervision et sauvegardes. Nos équipes suivent aussi votre instance de manière proactive et vous recommandent les corrections utiles, que vous appliquez. Une intervention dans l'application se facture à l'heure ou au forfait.
Simafri
Parlons de votre projet
Dites-nous en deux mots ce qu'il vous faut : on revient vers vous rapidement.
Merci ! Votre demande a bien été envoyée. Nous vous répondrons rapidement.
Vous préférez l'email ? Écrivez-nous à support@simafri.com.