Checkmate mit Docker installieren: Self-hosted Uptime-Monitor mit SSL-Tracking und Statusseiten
Checkmate 3.13 mit dem All-in-one-Image und MongoDB per Docker Compose betreiben: Pflichtvariablen, Port nur lokal, erstes Superadmin-Konto, Kernel-Falle bei MongoDB 8, Backup mit mongodump und Restore, praktisch getestet.
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

Checkmate ist ein quelloffener Uptime-Monitor (AGPL-3.0) von Bluewave Labs. Er prüft Websites, Ports, Ping, DNS, Docker-Container und weitere Ziele, meldet Ausfälle und zeigt Statusseiten. Mit Version 3.12.0 hat das Projekt die Bereitstellung vereinfacht: Statt getrennter Images für Client, Backend und Datenbank gibt es ein einziges Anwendungs-Image, dazu einen normalen MongoDB-Container. Diese Anleitung richtet genau diesen Aufbau mit Docker Compose ein, sichert ihn ab und zeigt Backup und Wiederherstellung der Datenbank.
Voraussetzungen
- Linux-Server oder VPS mit x86_64 oder ARM64, 2 CPU-Kerne, 4 GB RAM. In zwei Testläufen mit je zwei Monitoren belegte Checkmate 150 bis 290 MB und MongoDB 100 bis 430 MB RAM. Mit vielen Monitoren und langer Aufbewahrung wächst vor allem MongoDB.
- Etwa 2 GB freier Speicher für Images (Checkmate rund 316 MB, MongoDB rund 300 MB) und Messdaten, SSD empfohlen.
- x86_64-CPU mit AVX, weil MongoDB ab 5.0 AVX voraussetzt. Prüfen mit
grep -o -m1 -w avx /proc/cpuinfo. - Docker Engine mit Compose-Plugin (Docker-Installation).
- Für den Zugriff von außen eine Domain und ein Reverse Proxy mit TLS (Caddy als Reverse Proxy einrichten).
Eckdaten
| Punkt | Wert |
|---|---|
| Anwendungs-Image | ghcr.io/bluewave-labs/checkmate:3.13.1 (amd64 und arm64) |
| Version | v3.13.1, aktuelles Release am 23.10.2026 |
| Datenbank | mongo:8.0 laut Referenz-Compose, auf Kernel ab 6.19 mongo:7.0 |
| Ports | 52345 (Weboberfläche und API), 52346 (Health, nur intern) |
| Volume | MongoDB unter /data/db |
| Pflicht-Variablen | JWT_SECRET, CLIENT_HOST, DB_CONNECTION_STRING |
| Optional | ENCRYPTION_KEY, NODE_ENV, LOG_LEVEL, TOKEN_TTL |
| Benutzer im Container | node (UID 1000), nicht root |
Schritt 1: Kernel und MongoDB-Version prüfen
Das Referenz-Compose von Checkmate nutzt mongo:8.0. Im Test auf einem Host mit Kernel 7.0 startete mongo:8.0 (8.0.32) und ebenso mongo:8.3 nicht, sondern beendete sich sofort mit:
MongoDB cannot start: Linux kernel versions 6.19 and newer has a known incompatibility with this version of MongoDB. See https://jira.mongodb.org/browse/SERVER-121912 for more information.Laut MongoDB-Ticket SERVER-121912 liegt die Ursache in der Speicherverwaltung TCMalloc. Die Kompatibilitätstabelle im Folgeticket SERVER-125742 nennt die Grenzen: Unter Kernel 6.19 laufen alle Versionen, von 6.19 bis 7.0.13 beendet sich MongoDB 8.x beim Start, ab Kernel 7.0.14 beziehungsweise 7.1 startet MongoDB ab 8.0.30 wieder. Ubuntu-Kernel wie 7.0.0-38-generic erkennt die Startprüfung bis einschließlich 8.0.34 nicht als korrigiert (SERVER-136848), die Ausnahme ist laut SERVER-131779 erst für 8.0.35 vorgesehen. mongo:7.0 (7.0.43) startete auf demselben Host ohne Fehler, Checkmate lief damit vollständig. MongoDB 7.0 wird laut Lebenszyklus-Seite von MongoDB bis 31. August 2027 unterstützt. Legen Sie die Datenbankversion vor dem ersten Start fest, ein späterer Wechsel der Hauptversion erfordert einen Export und Import.
$ uname -r
$ grep -o -m1 -w avx /proc/cpuinfoLiegt die Kernel-Version unter 6.19 (etwa 6.8 bei Ubuntu 24.04 oder 6.12 bei Debian 13), verwenden Sie mongo:8.0. Ab 6.19, auch bei Ubuntu-Kerneln der Reihe 7.0, tragen Sie in Schritt 3 mongo:7.0 ein. Nur mit einem Upstream-Kernel ab 7.0.14 oder 7.1 bleibt mongo:8.0 möglich. Der zweite Befehl gibt avx aus.
MongoDB 9.0: Seit Oktober 2026 gibt es mongo:9.0 (9.0.4). Das Referenz-Compose von Checkmate bleibt bei mongo:8.0, diese Anleitung folgt ihm. Auf einem Host mit Kernel 6.8 lief Checkmate 3.12.0 im Test auch mit mongo:9.0.4: Erstes Konto, Anmeldung, Ablehnung eines falschen Passworts mit 401 sowie mongodump und mongorestore funktionierten. Ein bestehender Stack mit mongo:8.0 startete nach dem Tagwechsel auf 9.0.4 wieder mit beiden Containern healthy. Laut Upgrade-Anleitung von MongoDB setzt 9.0 eine Installation der Reihe 8.0 oder 8.3 mit passender featureCompatibilityVersion voraus; von mongo:7.0 führt der Weg erst über 8.0. Prüfen Sie den Wert vorher mit db.adminCommand({getParameter:1, featureCompatibilityVersion:1}) und sichern Sie die Datenbank nach Schritt 8. Laut SERVER-125742 beendet sich auch MongoDB 9.0 auf Kerneln von 6.19 bis 7.0.13 beim Start.
Schritt 2: Projektordner und Geheimnisse
Legen Sie einen Projektordner an und erzeugen Sie die Geheimnisse in einer .env. JWT_SECRET signiert die Anmelde-Token. ENCRYPTION_KEY ist laut README nur für gespeicherte TLS-Client-Schlüssel entfernter Docker-Hosts nötig, schadet aber nicht und erspart später einen Neustart.
mkdir -p /opt/checkmate && cd /opt/checkmate
cat > .env <<EOF
JWT_SECRET=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -base64 32)
CLIENT_HOST=https://status.example.de
EOF
chmod 600 .envCLIENT_HOST ist die Adresse, unter der Benutzer Checkmate aufrufen. Checkmate nutzt sie für CORS und für Links in Benachrichtigungen. Ohne Domain setzen Sie vorerst http://127.0.0.1:52345. Sichern Sie ENCRYPTION_KEY zusätzlich im Passwortmanager: Geht der Schlüssel verloren, schlagen Docker-Monitore mit TLS laut README mit einem Entschlüsselungsfehler fehl.
cat .env zeigt drei Zeilen, JWT_SECRET ist 64 Zeichen lang, und ls -l .env zeigt -rw-------.
Schritt 3: Compose-Datei
Die Datei folgt dem Referenz-Compose aus dem Repository (docker/docker-compose.yaml) mit drei Änderungen: fester Versions-Tag statt latest, Port nur an 127.0.0.1 und NODE_ENV=production. Nur im Produktionsmodus greift laut Quellcode das allgemeine API-Limit von 600 Anfragen pro Minute. Für Anmeldung und Registrierung gilt unabhängig davon ein Limit von 15 Anfragen pro Minute.
services:
checkmate:
image: ghcr.io/bluewave-labs/checkmate:3.13.1
restart: unless-stopped
ports:
- "127.0.0.1:52345:52345"
environment:
DB_CONNECTION_STRING: mongodb://mongodb:27017/uptime_db
CLIENT_HOST: ${CLIENT_HOST}
JWT_SECRET: ${JWT_SECRET:?JWT_SECRET fehlt}
ENCRYPTION_KEY: ${ENCRYPTION_KEY}
NODE_ENV: production
LOG_LEVEL: info
TELEMETRY_ENABLED: "false"
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
retries: 3
depends_on:
mongodb:
condition: service_healthy
mongodb:
image: mongo:8.0 # ab Kernel 6.19: mongo:7.0 (Schritt 1)
restart: unless-stopped
command: ["mongod", "--quiet", "--bind_ip_all"]
volumes:
- mongo-data:/data/db
healthcheck:
test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"]
interval: 5s
timeout: 30s
retries: 30
volumes:
mongo-data:MongoDB veröffentlicht keinen Port und ist nur im internen Compose-Netz erreichbar. Deshalb ist eine Anmeldung an der Datenbank hier nicht zwingend. Veröffentlichen Sie Port 27017 niemals nach außen. Der Healthcheck nutzt node, das im Image vorhanden ist, statt curl.
Seit Version 3.13.0 sendet Checkmate laut Release Notes standardmäßig einmal täglich einen anonymen Telemetrie-Heartbeat. Er enthält laut Quellcode eine zufällige Instanz-ID, die Checkmate-Version, die Bereitstellungsart, den Queue-Modus sowie Node-Version, Betriebssystem und Architektur. TELEMETRY_ENABLED: "false" schaltet ihn ab. Im Test meldete der Container danach TELEMETRY_ENABLED=false in seiner Umgebung.
docker compose config läuft ohne Fehler durch. Fehlt JWT_SECRET, bricht Compose ab mit required variable JWT_SECRET is missing a value: JWT_SECRET fehlt.
Schritt 4: Stack starten
$ docker compose up -d
$ docker compose ps
$ docker compose logs checkmate | tail -n 8Checkmate wartet, bis MongoDB gesund ist, führt dann die Datenbank-Migrationen aus und startet. Im Test war der Container etwa 20 Sekunden nach MongoDB healthy. Seit 3.13.0 schreibt Checkmate das Log als JSON-Zeilen auf die Standardausgabe, eine Datei app.log gibt es nicht mehr. Im Log stehen am Ende Meldungen mit Connected to MongoDB, Health server listening und Server started.
docker compose ps zeigt beide Dienste als healthy. curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:52345/ liefert 200.
Schritt 5: Erstes Konto anlegen
Das erste registrierte Konto wird Superadmin. Legen Sie es direkt nach dem Start an, bevor die Instanz über den Proxy erreichbar ist. Rufen Sie dazu die Oberfläche per SSH-Tunnel auf:
$ ssh -L 52345:127.0.0.1:52345 benutzer@serverÖffnen Sie danach im lokalen Browser http://127.0.0.1:52345 und registrieren Sie sich. Das Passwort braucht mindestens 8 Zeichen mit Klein- und Großbuchstaben, Ziffer und Sonderzeichen. Ob bereits ein Superadmin existiert, zeigt die API:
$ curl -s http://127.0.0.1:52345/api/v1/auth/users/superadminIm Test lieferte der Aufruf vor der Registrierung "data":false, danach "data":true. Weitere Konten entstehen nur über Einladungen: Eine Registrierung ohne Einladung beantwortete Checkmate im Test mit {"status":404,"msg":"Invite not found"}.
Wer das Konto per Skript anlegt, muss die Felder wie die Oberfläche in ein Objekt user verpacken. Einen flachen JSON-Body lehnt Checkmate mit Invalid input: expected object, received undefined ab. Version 3.12.0 antwortete dabei mit HTTP 500, laut Release Notes liefert 3.13.0 bei Validierungsfehlern 400:
curl -s -H 'Content-Type: application/json' \
-d '{"user":{"firstName":"Max","lastName":"Admin","email":"admin@example.de","password":"IhrSicheres-Passwort1!"}}' \
http://127.0.0.1:52345/api/v1/auth/registerIm Test lieferte dieser Aufruf "msg":"User registered successfully" mit der Rolle superadmin.
Der Superadmin-Aufruf liefert "data":true, und die Anmeldung in der Oberfläche führt zur leeren Monitorliste.
Schritt 6: Monitore anlegen
Legen Sie in der Oberfläche unter „Uptime“ einen HTTP-Monitor für eine Ihrer Websites an. Checkmate unterstützt laut README unter anderem HTTP mit Prüfung des Zertifikatsablaufs, Ping, Port, DNS, Docker, gRPC und WebSocket. Richten Sie danach unter „Notifications“ mindestens einen Benachrichtigungskanal ein und ordnen Sie ihn den Monitoren zu.

Docker-Monitore für den lokalen Host brauchen Zugriff auf den Docker-Socket. Das Referenz-Compose bindet ihn bewusst nicht ein. Wer ihn ergänzt, gibt dem Container faktisch Root-Rechte auf dem Host, denn über den Socket lassen sich beliebige Container starten. Nutzen Sie diese Option nur, wenn Sie das Risiko bewusst tragen, und laut README mit :ro sowie group_add und der Gruppen-ID aus stat -c %g /var/run/docker.sock. Alternativ liefert der Capture-Agent von Bluewave Labs Containerdaten ohne Socket-Zugriff des Checkmate-Containers.
Im Test wechselte ein Monitor auf https://example.com nach rund einer Minute von initializing auf up, ein Monitor auf einen geschlossenen Port auf down. Beide Zustände müssen in der Übersicht erscheinen.

Schritt 7: Reverse Proxy
Laut README gehört für TLS ein beliebiger Reverse Proxy vor Port 52345. Mit Caddy genügt:
status.example.de {
reverse_proxy 127.0.0.1:52345
}Tragen Sie danach die öffentliche Adresse in CLIENT_HOST ein und übernehmen Sie sie mit docker compose up -d. Checkmate beantwortet CORS-Anfragen mit dem Wert aus CLIENT_HOST: Im Test lieferte auch eine Anfrage mit fremdem Origin den Header Access-Control-Allow-Origin mit der konfigurierten Adresse. Stimmt CLIENT_HOST nicht, zeigen Links in Benachrichtigungen und E-Mails auf die falsche Adresse.
curl -sI https://status.example.de liefert HTTP/2 200, die Anmeldung über die Domain funktioniert, und Links in Test-Benachrichtigungen zeigen auf die Domain.
Schritt 8: Backup und Wiederherstellung
Alle Einstellungen, Konten, Monitore und Messwerte liegen in MongoDB. Sichern Sie die Datenbank mit mongodump aus dem laufenden Container, dazu die .env:
$ cd /opt/checkmate
$ docker compose exec -T mongodb mongodump --db uptime_db --archive --gzip > checkmate-$(date +%F).archive.gz
$ cp .env checkmate-env-$(date +%F).bakDie Wiederherstellung ersetzt die vorhandenen Sammlungen:
$ docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-09-30.archive.gzIm Test wurden nach dem Dump alle Monitore gelöscht und anschließend zurückgespielt. mongorestore meldete 29 document(s) restored successfully. 0 document(s) failed to restore., beide Monitore waren wieder da. Nach docker compose down und erneutem up -d funktionierte die Anmeldung weiter, die Daten lagen also korrekt im Volume.
docker compose exec -T mongodb mongosh uptime_db --quiet --eval 'db.monitors.countDocuments()' liefert nach dem Restore dieselbe Zahl wie vor dem Backup.
Typische Fehler
- MongoDB startet nicht,
dependency failed to start: container … is unhealthy Im Log steht
MongoDB cannot start: Linux kernel versions 6.19 and newer …. Aufmongo:7.0wechseln oder einen Kernel unter 6.19 nutzen (Schritt 1).- MongoDB beendet sich mit Exit-Code 132
Der CPU fehlt AVX, häufig bei alten oder emulierten CPUs. Anderen Host oder CPU-Typ der VM wählen.
Too many requests, please try again later.mit HTTP 429Mehr als 15 Anmelde- oder Registrierungsversuche pro Minute. Eine Minute warten.
{"status":401,"msg":"Incorrect password"}Falsches Passwort beim Login, im Test so reproduziert.
- HTTP 500 mit
expected object, received undefinedbei/api/v1/auth/register Die Felder stehen nicht im Objekt
user. Body wie in Schritt 5 aufbauen.{"status":404,"msg":"Invite not found"}Registrierung ohne gültige Einladung. Der Superadmin lädt weitere Benutzer ein.
- Links in Benachrichtigungen zeigen auf localhost
CLIENT_HOSTsteht noch auf dem Startwert. Öffentliche Adresse eintragen und Container mitdocker compose up -dneu erstellen.- Alte Variablen ohne Wirkung
UPTIME_APP_API_BASE_URL,UPTIME_APP_CLIENT_HOSTundORIGINliest 3.12 nicht mehr. Bei abweichender Herkunft laut READMECLIENT_CONFIG_*nutzen.
Häufige Fragen
Wie migriere ich von den alten getrennten Images?
Laut README stellen Sie auf ghcr.io/bluewave-labs/checkmate um und behalten den bestehenden MongoDB-Dienst samt Datenvolume. Erstellen Sie vorher ein Backup nach Schritt 8.
Kann ich eine externe MongoDB verwenden?
Ja. Setzen Sie DB_CONNECTION_STRING auf die externe Instanz und entfernen Sie den Dienst mongodb aus der Compose-Datei.
Was unterscheidet Checkmate von Uptime Kuma?
Beide überwachen Erreichbarkeit und bieten Statusseiten. Checkmate nutzt MongoDB und bietet mit dem Capture-Agent zusätzlich Hardware-Messwerte. Uptime Kuma kommt mit SQLite in einem Container aus.
Wie aktualisiere ich Checkmate?
Backup nach Schritt 8, Tag in der Compose-Datei ändern, docker compose pull und docker compose up -d. Migrationen laufen beim Start automatisch und erscheinen im Log.
Im Test lief das Update von 3.12.0 auf 3.13.0 mit mongo:8.0 genau so: Der Container war nach wenigen Sekunden healthy, das Image meldete Version 3.13.0 auf Node 24. Das Superadmin-Konto und ein vorher angelegter Monitor blieben erhalten, die Anmeldung gelang, ein falsches Passwort wurde mit 401 abgewiesen, und die Monitor-API antwortete ohne Token mit 401. Ein vor dem Update erstellter mongodump ließ sich danach mit mongorestore --drop einspielen und brachte den zuvor gelöschten Monitor zurück. Laut Release Notes braucht 3.13.0 keine neuen Pflichtvariablen und keine Migration. Neu sind der Telemetrie-Heartbeat (siehe Schritt 3), das JSON-Log auf der Standardausgabe und info als Standard für LOG_LEVEL.
Version 3.13.1 vom 22.10.2026 ist laut Release Notes ein kleiner Nachtrag: Der anonyme Telemetrie-Heartbeat enthält zusätzlich die Anzahl der Monitore je Typ, abschaltbar wie bisher mit TELEMETRY_ENABLED=false. Neue Pflichtvariablen oder Migrationen gibt es nicht, und das Referenz-Compose bleibt bei mongo:8.0. Im Test lief das Update von 3.13.0 auf 3.13.1 mit mongo:8.0: Der Container war nach wenigen Sekunden healthy, das Image meldete 3.13.1 auf Node 24.22.1, Superadmin-Konto und Marker-Monitor blieben erhalten, die Anmeldung gelang, ein falsches Passwort und die Monitor-API ohne Token wurden mit 401 abgewiesen, und der mongodump von vor dem Update brachte einen gelöschten Monitor per mongorestore --drop zurück.
Fazit
Mit dem All-in-one-Image ist Checkmate deutlich einfacher zu betreiben als mit den früheren Varianten. Entscheidend sind die richtige MongoDB-Version für Ihren Kernel, ein Port nur an 127.0.0.1, das sofort angelegte Superadmin-Konto und ein regelmäßiger mongodump. Den Docker-Socket binden Sie nur ein, wenn Sie die damit verbundenen Root-Rechte bewusst akzeptieren.
Weiterführende Anleitungen und Quellen
- Caddy als Reverse Proxy einrichten
- Uptime Kuma installieren
- Beszel Server Monitoring mit Docker
- Docker Compose absichern: Secrets, Healthchecks und Non-Root
- Checkmate Release v3.13.1
- Checkmate README: Installation, Konfiguration, Docker-Monitore
- Checkmate Referenz-Compose
- MongoDB SERVER-121912: Kernel 6.19 und TCMalloc
- MongoDB SERVER-125742: Kompatibilität nach Kernel-Version
- MongoDB Software Lifecycle Schedules


