Checkmate mit Docker installieren: Self-hosted Uptime-Monitor mit SSL-Tracking und Statusseiten

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. Im Test belegten Checkmate rund 152 MB und MongoDB rund 98 MB RAM bei zwei Monitoren. 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

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

Verifizieren: 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 tragen Sie in Schritt 3 mongo:7.0 ein. Der zweite Befehl gibt avx aus.

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.

Verifizieren: 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.12.0
    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
    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.

Verifizieren: 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. Im Log stehen am Ende Connected to MongoDB, Health server listening on 52346 und Server started on port:52345.

Verifizieren: 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"}.

Verifizieren: 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.

Verifizieren: 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: http://127.0.0.1:28493, also die konfigurierte Adresse. Stimmt CLIENT_HOST nicht, zeigen Links in Benachrichtigungen und E-Mails auf die falsche Adresse.

Verifizieren: 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.

Verifizieren: 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.
• {"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. Die Migration selbst wurde für diese Anleitung nicht getestet.

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.

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
• Checkmate Release v3.12.0
• Checkmate README: Installation, Konfiguration, Docker-Monitore
• Checkmate Referenz-Compose
• MongoDB SERVER-121912: Kernel 6.19 und TCMalloc
• MongoDB Software Lifecycle Schedules