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

Wer seine Server, Webdienste und Docker-Container im Blick behalten möchte, ohne auf einen kostenpflichtigen Cloud-Dienst angewiesen zu sein, findet in Checkmate eine ernstzunehmende Alternative. Das Projekt von Bluewave Labs vereint HTTP/HTTPS-Uptime, SSL-Zertifikatsüberwachung, Port-Checks, DNS-Monitoring, Docker-Container-Status und Infrastruktur-Metriken in einer einzigen Oberfläche. Mit über 10.000 GitHub-Stars, 9.000+ Commits und der aktuellen Version v3.8.1 (Juni 2026) ist es kein Hobby-Projekt, sondern ein aktiv gewartetes Werkzeug für DevOps-Teams, Systemadministratoren und Agenturen. Besonders praktisch: anpassbare öffentliche Statusseiten in vier Themes, über 16 Benachrichtigungskanäle (Slack, Discord, Telegram, PagerDuty, Teams und viele mehr) sowie konfigurierbare Wartungsfenster, die falsche Alarme bei geplanten Downtimes verhindern.

Voraussetzungen

1. Docker Engine v24.0+ und das Docker Compose Plugin v2.x (docker compose ohne Bindestrich) auf dem Host installiert – falls nicht vorhanden, hilft die Anleitung Docker und Docker Compose auf Linux installieren.
2. Linux-Host, VM oder NAS mit Docker-Unterstützung (Ubuntu 22.04+, Debian 12+ empfohlen); alternativ Windows mit WSL2 oder macOS.
3. Mindestens 1 GB RAM (empfohlen 2 GB+), mindestens 5 GB freier Speicherplatz für Images und MongoDB-Daten.
4. Internetzugang für den Image-Pull von ghcr.io.
5. Offene Ports in der Host-Firewall: 52345 (dist-mono) oder 80 (dist-Variante mit getrennten Containern).
6. openssl auf dem Host für die sichere JWT-Secret-Generierung.
7. Optional: Reverse Proxy (Nginx, Traefik, Caddy) für HTTPS-Terminierung.

Varianten im Überblick

Checkmate bietet drei offizielle Deployment-Varianten. Die Wahl hängt von deiner Hardware und dem Einsatzzweck ab:

Diese Anleitung zeigt die dist-mono-Variante als Hauptweg (ein kombinierter Container, am einfachsten zu betreiben) und erklärt danach die Unterschiede der dist-Variante mit getrennten Containern.

Eckdaten der Docker-Images

Wichtig: Alle Images befinden sich ausschließlich auf der GitHub Container Registry (ghcr.io/bluewave-labs/). Ein docker pull checkmate auf Docker Hub schlägt fehl. Das :latest-Tag ist bequem, für Produktionsumgebungen empfiehlt sich jedoch ein konkreter Versions-Tag (z. B. :3.8.1), um Breaking Changes durch ungewollte Updates zu vermeiden.

Schritt 1: Projektordner anlegen

Leg einen dedizierten Ordner für den Checkmate-Stack an. Alle folgenden Dateien kommen dort rein:

mkdir -p /opt/checkmate
cd /opt/checkmate

Du kannst auch ~/checkmate verwenden, wenn du keinen Root-Zugriff hast.

Verifizieren: ls -la /opt/checkmate – der leere Ordner sollte existieren und dir gehören.

Schritt 2: Umgebungsvariablen in der .env-Datei konfigurieren

Bevor du die compose.yaml schreibst, erzeugst du einen kryptografisch sicheren JWT-Secret. Dieser Schlüssel schützt die gesamte Authentifizierung von Checkmate – der Default-Wert my_secret aus den offiziellen Beispieldateien darf in einer produktiven Umgebung niemals übernommen werden:

openssl rand -hex 32

Die Ausgabe (64 zufällige Hex-Zeichen) kopierst du in die .env-Datei. Erstelle die Datei im Projektordner:

# /opt/checkmate/.env

# JWT-Secret: PFLICHT – niemals "my_secret" verwenden!
JWT_SECRET=hier-deinen-generierten-32-byte-hex-wert-eintragen

# Server-IP oder Domain: "localhost" nur für lokale Tests
# Für Remote-Server: tatsächliche IP oder Hostname eintragen
SERVER_IP=localhost

Läuft Checkmate auf einem Remote-Server, musst du SERVER_IP auf die tatsächliche IP-Adresse oder den Hostnamen setzen – z. B. SERVER_IP=192.168.1.100. Die compose.yaml referenziert diese Variable an drei Stellen. Stimmt die IP nicht, kann das Frontend die API nicht erreichen, und du siehst CORS-Fehler im Browser.

Verifizieren: cat /opt/checkmate/.env – der JWT_SECRET-Wert muss 64 Hex-Zeichen lang sein, nicht der Platzhalter.

Schritt 3: compose.yaml erstellen (dist-mono, empfohlen)

Erstelle die compose.yaml im Projektordner. Diese Konfiguration startet den kombinierten Backend-Frontend-Container zusammen mit MongoDB:

services:
  checkmate:
    image: ghcr.io/bluewave-labs/checkmate-backend-mono:latest
    restart: always
    ports:
      - "52345:52345"
    depends_on:
      mongodb:
        condition: service_healthy
    environment:
      DB_CONNECTION_STRING: "mongodb://mongodb:27017/uptime_db"
      CLIENT_HOST: "http://${SERVER_IP:-localhost}"
      JWT_SECRET: "${JWT_SECRET}"
      ORIGIN: "http://${SERVER_IP:-localhost}"
      LOG_LEVEL: "info"
      TOKEN_TTL: "99d"
    # Docker-Container-Monitoring: folgende zwei Zeilen einkommentieren
    # volumes:
    #   - /var/run/docker.sock:/var/run/docker.sock:ro

  mongodb:
    image: ghcr.io/bluewave-labs/checkmate-mongo:latest
    restart: always
    volumes:
      - checkmate_mongo_data:/data/db
    command: ["mongod", "--quiet", "--bind_ip_all"]
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')", "--quiet"]
      interval: 5s
      timeout: 30s
      start_period: 0s
      start_interval: 1s
      retries: 30

volumes:
  checkmate_mongo_data:
    driver: local

Der checkmate-Service startet erst, wenn MongoDB den Healthcheck (condition: service_healthy) bestanden hat – ohne diese Bedingung bekommst du beim ersten Start häufig MongoNetworkError: connect ECONNREFUSED. Das Named Volume checkmate_mongo_data stellt sicher, dass deine Monitoring-Daten auch nach einem Neustart erhalten bleiben.

Variante: dist (getrennte Container, für Produktion)

Wenn du Checkmate hinter einem Reverse Proxy mit HTTPS betreiben möchtest, eignet sich die dist-Variante. Tausche den checkmate-Service gegen diese beiden Services aus:

  client:
    image: ghcr.io/bluewave-labs/checkmate-client:latest
    restart: always
    environment:
      UPTIME_APP_API_BASE_URL: "http://${SERVER_IP:-localhost}:52345/api/v1"
      UPTIME_APP_CLIENT_HOST: "http://${SERVER_IP:-localhost}"
    ports:
      - "80:80"
    depends_on:
      - server

  server:
    image: ghcr.io/bluewave-labs/checkmate-backend:latest
    restart: always
    ports:
      - "52345:52345"
    depends_on:
      mongodb:
        condition: service_healthy
    environment:
      DB_CONNECTION_STRING: "mongodb://mongodb:27017/uptime_db"
      CLIENT_HOST: "http://${SERVER_IP:-localhost}"
      JWT_SECRET: "${JWT_SECRET}"
      ORIGIN: "http://${SERVER_IP:-localhost}"
      LOG_LEVEL: "info"
    # volumes:
    #   - /var/run/docker.sock:/var/run/docker.sock:ro

Port 443 ist ohne zusätzliche TLS-Zertifikate nicht funktional. Für HTTPS empfiehlt sich ein vorgelagerter Reverse Proxy – etwa wie in der Anleitung Traefik als Docker-Reverse-Proxy mit automatischem HTTPS beschrieben. Läuft bereits ein Webserver auf Port 80, schlägt der Start mit „Bind: address already in use" fehl – passe dann den Host-Port an.

Variante: dist-arm (Raspberry Pi und Apple Silicon)

Für ARM-Hardware ersetzt du Image und MongoDB-Quelle:

  checkmate:
    image: ghcr.io/bluewave-labs/checkmate-backend-mono-multiarch:latest
    # ... Rest identisch zu dist-mono

  mongodb:
    image: mongo:6.0
    # ... Rest identisch zu dist-mono

Das Standard-Image checkmate-backend-mono:latest ist ausschließlich für x86_64 gebaut. Auf ARM-Systemen startet es entweder gar nicht oder wirft „Illegal instruction"-Fehler. Das Multiarch-Image löst das zuverlässig.

Verifizieren: Mit docker compose config im Projektordner die aufgelöste Konfiguration inklusive substituierter Umgebungsvariablen prüfen. Stimmen IP und JWT-Secret, kann es losgehen.

Schritt 4: Stack starten

Starte den Stack aus dem Projektordner heraus:

cd /opt/checkmate
docker compose up -d

Beim ersten Start werden die Images von ghcr.io gezogen – je nach Internetverbindung dauert das einige Minuten. Danach startet MongoDB, durchläuft den Healthcheck (bis zu 30 Wiederholungen à 1 Sekunde), und der Checkmate-Container startet erst, wenn MongoDB als healthy gilt.

Verifizieren: Status aller Container prüfen:

docker compose ps

Erwartete Ausgabe:

NAME                    IMAGE                                                    STATUS
checkmate-checkmate-1   ghcr.io/bluewave-labs/checkmate-backend-mono:latest     Up X minutes
checkmate-mongodb-1     ghcr.io/bluewave-labs/checkmate-mongo:latest            Up X minutes (healthy)

MongoDB muss den Status (healthy) zeigen. Falls Checkmate sofort abstürzt, prüfe die Logs:

docker compose logs checkmate
docker compose logs mongodb

Ein häufiges Problem ist ein fehlerhafter JWT_SECRET (leer oder noch der Platzhalter). Prüfe auch, ob die .env-Datei im selben Verzeichnis wie die compose.yaml liegt.

Schritt 5: Ersteinrichtung im Browser

Öffne die Checkmate-Oberfläche im Browser:

1. dist-mono: http://localhost:52345 (oder http://<SERVER-IP>:52345)
2. dist: http://localhost (Port 80)

Beim ersten Aufruf wirst du zur Registrierung des ersten Admin-Accounts aufgefordert. Nach dem Login gelangst du zum Dashboard, das zunächst noch leer ist. Lege jetzt deinen ersten Monitor an: Klicke auf „Add Monitor", wähle den Typ (z. B. HTTP), trage URL, Prüfintervall und Benachrichtigungsziel ein.

Statusseiten einrichten: Unter „Status Pages" kannst du eine öffentliche Übersichtsseite in einem der vier Themes erstellen und per eigenem Link teilen – ideal für die transparente Kommunikation mit Kunden oder Endnutzern während Störungen.

Benachrichtigungen konfigurieren: Unter den Einstellungen findest du alle 16+ Kanäle. Für Slack, Discord und Telegram reicht ein Webhook-URL, für PagerDuty und Teams gibt es native Integrationen.

Verifizieren: Überprüfe per curl, ob die API antwortet:

curl -I http://localhost:52345

Erwartete Antwort: HTTP/1.1 200 OK oder HTTP/1.1 302 Found. Außerdem sollte das Dashboard im Browser ohne CORS-Fehler laden (kein roter Netzwerkfehler in den Browser-Dev-Tools).

Schritt 6 (optional): Docker-Container-Monitoring aktivieren

Um Docker-Container direkt in Checkmate zu überwachen, muss der Docker-Socket in den Container eingebunden werden. Öffne die compose.yaml und kommentiere die auskommentierten Zeilen ein:

    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

Starte den Stack danach neu:

docker compose up -d

Das :ro-Flag sorgt dafür, dass Checkmate den Socket nur lesen, nicht schreiben kann. Beachte, dass der Zugriff auf den Docker-Socket grundsätzlich erhöhte Berechtigungen bedeutet – in sicherheitskritischen Umgebungen solltest du abwägen, ob du stattdessen den optionalen Capture-Agent nutzt.

Verifizieren: In der Checkmate-Weboberfläche → „Add Monitor" → Typ „Docker Container" auswählen. Du solltest jetzt eine Liste der laufenden Container auf dem Host sehen.

Schritt 7 (optional): Capture-Agent für Infrastruktur-Monitoring

Für tiefes Infrastruktur-Monitoring (CPU, RAM, Disk, Netzwerk) auf Remote-Servern steht der separate Capture-Agent (ghcr.io/bluewave-labs/capture:latest) bereit. Du installierst ihn auf dem zu überwachenden Server (Installationsanleitung im Repository github.com/bluewave-labs/capture) und legst in der Checkmate-Weboberfläche einen Monitor vom Typ „Infrastructure" an, der den Capture-Endpunkt abfragt. Dieser Weg vermeidet den direkten Docker-Socket-Zugriff und ist besonders für verteilte Infrastrukturen geeignet.

Verifizieren: In Checkmate → „Add Monitor" → Typ „Infrastructure" → Capture-Server-URL eintragen. Der Monitor sollte nach dem ersten Poll Metriken anzeigen.

Updates und Backup

Bevor du ein Update einspielst, sichere das MongoDB-Volume. Checkmate enthält keine automatische Datenmigration – prüfe bei jedem Release die GitHub Release-Notes auf Breaking Changes:

# MongoDB-Backup erstellen
docker exec checkmate-mongodb-1 mongodump --out /data/backup
docker cp checkmate-mongodb-1:/data/backup ./mongo-backup-$(date +%Y%m%d)

# Neue Images ziehen und Stack neu starten
cd /opt/checkmate
docker compose pull
docker compose up -d

Die Daten im Named Volume checkmate_mongo_data bleiben beim Neustart erhalten. Niemals docker compose down -v beim Update verwenden – das -v-Flag löscht die Volumes. Für automatische Container-Update-Strategien findest du Alternativen in der Anleitung Docker-Container automatisch aktualisieren nach dem Watchtower-Aus.

Verifizieren: Nach dem Update: docker compose ps – alle Container müssen wieder im Status Up sein. Im Browser: Checkmate-Version in den Einstellungen prüfen.

Troubleshooting / Typische Fehler

1. „MongoNetworkError: connect ECONNREFUSED": Der Checkmate-Container startet, bevor MongoDB bereit ist. Ursache: depends_on ohne condition: service_healthy. Fix: Healthcheck-Block und condition: service_healthy in der compose.yaml sicherstellen, dann docker compose down && docker compose up -d.
2. CORS-Fehler im Browser („blocked by CORS policy"): ORIGIN, CLIENT_HOST und UPTIME_APP_API_BASE_URL zeigen noch auf localhost, obwohl Checkmate auf einem Remote-Server läuft. Fix: In der .env-Datei SERVER_IP auf die tatsächliche Server-IP setzen, dann docker compose up -d.
3. „Bind: address already in use" auf Port 80: Ein anderer Prozess belegt Port 80. Fix: Host-Port in der compose.yaml ändern (z. B. "8080:80") oder einen Reverse Proxy vorschalten.
4. Docker-Container erscheinen nicht in der Übersicht: Der Docker-Socket ist nicht eingebunden. Fix: Die auskommentierten Volume-Zeilen einkommentieren und docker compose up -d ausführen.
5. „Illegal instruction" oder Container startet nicht auf ARM: Das checkmate-backend-mono:latest-Image ist nur für x86_64. Fix: checkmate-backend-mono-multiarch:latest verwenden und MongoDB auf mongo:6.0 wechseln.
6. Images nicht gefunden (Docker Hub): Alle Images liegen ausschließlich auf ghcr.io/bluewave-labs/. Fix: Den vollständigen Image-Pfad verwenden.
7. Monitoring-Daten nach Neustart weg: Kein Named Volume für MongoDB konfiguriert. Fix: Das Volume checkmate_mongo_data:/data/db in der compose.yaml sicherstellen.
8. JWT-Fehler / Login schlägt fehl: JWT_SECRET ist leer oder enthält den Platzhalter. Fix: openssl rand -hex 32 ausführen, Wert in .env eintragen, docker compose up -d.

Häufige Fragen

Welche Variante soll ich nehmen – dist-mono, dist oder dist-arm?

Für lokale Tests und den schnellsten Einstieg ist dist-mono die richtige Wahl: ein Container, ein Port (52345), minimaler Konfigurationsaufwand. Für Produktionsumgebungen mit Reverse Proxy und HTTPS eignet sich dist besser. Auf Raspberry Pi, anderen ARM-Boards oder Apple-Silicon-Macs ist dist-arm mit dem Multiarch-Image Pflicht.

Wie generiere ich einen sicheren JWT_SECRET?

Mit OpenSSL auf jedem Linux-/macOS-System: openssl rand -hex 32. Das ergibt einen 64 Zeichen langen Hex-String. Den Wert schreibst du in die .env-Datei als JWT_SECRET=<ausgabe>. Gib den Secret niemals in Logs aus oder committe die .env-Datei in ein öffentliches Repository.

Wie überwache ich Docker-Container mit Checkmate?

Im checkmate-Service die auskommentierten Volume-Zeilen einkommentieren: - /var/run/docker.sock:/var/run/docker.sock:ro. Dann docker compose up -d und in der Weboberfläche einen Monitor vom Typ „Docker Container" anlegen.

Wie erreiche ich Checkmate von einem anderen Gerät im Netzwerk?

In der .env-Datei SERVER_IP auf die tatsächliche IP-Adresse setzen, z. B. SERVER_IP=192.168.1.100. Danach docker compose up -d ausführen, damit die Umgebungsvariablen neu eingelesen werden.

Wie richte ich Wartungsfenster ein?

In der Checkmate-Weboberfläche unter „Maintenance Windows" kannst du einmalige oder wiederkehrende Wartungsfenster konfigurieren. Während eines aktiven Wartungsfensters werden keine Alarme für die zugehörigen Monitore ausgelöst – praktisch für geplante Updates oder Reboots.

Wie spiele ich Updates sicher ein?

Immer zuerst ein MongoDB-Backup erstellen, dann die Release-Notes auf Breaking Changes prüfen, danach docker compose pull && docker compose up -d. Niemals docker compose down -v verwenden – das löscht die Volumes.

Fazit

Checkmate ist eine ausgereifte, vollständig selbst gehostete Alternative zu kommerziellen Uptime-Diensten. Der Einstieg per dist-mono ist in unter 15 Minuten erledigt, und der Funktionsumfang – von SSL-Tracking über Docker-Container-Monitoring bis zu anpassbaren öffentlichen Statusseiten – deckt die Anforderungen von KMU-Admins und Agenturen vollständig ab. Die wichtigsten Stolpersteine sind der JWT-Secret (niemals den Default übernehmen), die korrekte SERVER_IP-Konfiguration für Remote-Zugriff und der Docker-Socket-Mount für Container-Monitoring. Wer Checkmate zusammen mit einem sicheren Reverse Proxy betreiben möchte, findet in der Anleitung Caddy als Reverse Proxy mit automatischem HTTPS einen bewährten Einstiegspunkt. Für ein umfassendes Monitoring-Ökosystem lässt sich Checkmate gut mit Metriken-Tools kombinieren – etwa mit Beszel für leichtgewichtiges Server-Monitoring als ergänzende Lösung.

Weiterführende Anleitungen und Quellen

1. Docker und Docker Compose auf Linux installieren – die Self-Hosting-Grundlage
2. Traefik als Docker-Reverse-Proxy mit automatischem HTTPS einrichten
3. Caddy als Reverse Proxy mit automatischem HTTPS
4. Beszel Server Monitoring mit Docker einrichten
5. Docker-Container automatisch aktualisieren nach dem Watchtower-Aus
6. Gatus mit Docker installieren: Entwicklerorientiertes Status-Dashboard

Offizielle Quellen: Checkmate GitHub Repository und Dokumentation unter github.com/bluewave-labs/Checkmate sowie checkmate.so/docs.

Passende Anleitungen auf S-EDV

1. Automatische Sicherheitsupdates unter Debian/Ubuntu mit unattended-upgrades rich
2. Google schließt Android-Zero-Day CVE-2025-48595 in Juni-Sicherheitsupdates – 124
3. Linux-Fileserver im Active Directory: Samba als Domain Member mit NTFS-ähnlichen