Zum Hauptinhalt springen
S-EDV news
← Alle Anleitungen
📘 Anleitung Monitoring 05.07.2026 · 11 min Lesezeit Wird überarbeitet

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

Titelbild: Checkmate mit Docker, Uptime überwachen mit Zertifikaten und Statusseite

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

PunktWert
Anwendungs-Imageghcr.io/bluewave-labs/checkmate:3.13.1 (amd64 und arm64)
Versionv3.13.1, aktuelles Release am 23.10.2026
Datenbankmongo:8.0 laut Referenz-Compose, auf Kernel ab 6.19 mongo:7.0
Ports52345 (Weboberfläche und API), 52346 (Health, nur intern)
VolumeMongoDB unter /data/db
Pflicht-VariablenJWT_SECRET, CLIENT_HOST, DB_CONNECTION_STRING
OptionalENCRYPTION_KEY, NODE_ENV, LOG_LEVEL, TOKEN_TTL
Benutzer im Containernode (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/cpuinfo

Liegt 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 .env

CLIENT_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 8

Checkmate 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/superadmin

Im 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/register

Im 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.

Checkmate-Formular zum Anlegen eines Uptime-Monitors mit Auswahl des Prüftyps HTTP(S) und Feldern für Anzeigename und URL
Uptime, Create: Prüftyp wählen, danach Anzeigename und URL eintragen.

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.

Checkmate-Übersicht der Uptime-Monitore mit einem Monitor im Status Up und einem im Status Down
Übersicht unter „Uptime“: ein erreichbares Ziel (Up) und ein geschlossener Port (Down).

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).bak

Die Wiederherstellung ersetzt die vorhandenen Sammlungen:

$ docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-09-30.archive.gz

Im 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 …. Auf mongo:7.0 wechseln 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 429

Mehr 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 undefined bei /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_HOST steht noch auf dem Startwert. Öffentliche Adresse eintragen und Container mit docker compose up -d neu erstellen.

Alte Variablen ohne Wirkung

UPTIME_APP_API_BASE_URL, UPTIME_APP_CLIENT_HOST und ORIGIN liest 3.12 nicht mehr. Bei abweichender Herkunft laut README CLIENT_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