Checkmate auf einem Managed VPS zu hosten heißt, die Überwachung Ihrer Websites und Server auf einer Maschine zu behalten, die Ihnen gehört und die unsere Teams aktuell halten und Tag und Nacht beaufsichtigen. Checkmate ist eine freie, quelloffene Überwachungsanwendung unter der AGPL-3.0-Lizenz: Verfügbarkeit, Antwortzeiten, Vorfälle, Alarme und Statusseiten. Dieser Leitfaden folgt dem offiziellen Docker-Image in Version v4.0.0, und wir haben jeden Befehl vor dem Schreiben auf einem VPS von Simafri ausgeführt: die Installation mit Docker Compose, HTTPS, das erste Konto, Monitore und Alarme, Backups und Updates.
Von Simon Vasconcelos Lee
Veröffentlicht am 17. November 2026Lesezeit: 12 Minuten
ghcr.io/bluewave-labs/checkmate und MongoDB 8.0, mit dem Port auf 127.0.0.1 veröffentlicht, hinter einem Reverse Proxy mit HTTPS.JWT_SECRET, ENCRYPTION_KEY und Ihre öffentliche Adresse in CLIENT_HOST, und ergänzen Sie NODE_ENV=production, das in der Referenzdatei fehlt.mongodump und bewahren Sie Ihre Datei .env auf; aktualisieren Sie dann, indem Sie das Image-Tag ändern: Die Migrationen laufen beim Start von selbst.Checkmate prüft Ihre Dienste in regelmäßigen Abständen, zeichnet jede Antwort und ihre Antwortzeit auf und alarmiert Sie, wenn etwas nicht mehr antwortet. Sein Entwickler, BlueWave Labs, beschreibt es als selbst gehostetes Werkzeug, um Server-Hardware, Verfügbarkeit, Antwortzeiten und Vorfälle in Echtzeit zu verfolgen.
Checkmate wird unter der GNU Affero General Public License, Version 3 (AGPL-3.0) veröffentlicht. Sie können es kostenlos nutzen, für sich, Ihr Unternehmen oder Ihre Kunden, es kopieren und ändern.
Ihre besondere Klausel betrifft die Nutzung über das Netzwerk: Wenn Sie Checkmate ändern und anderen Personen Ihre geänderte Fassung über das Netzwerk zur Nutzung bereitstellen, müssen Sie ihnen deren Quellcode anbieten. Wer das offizielle Image unverändert betreibt, wie in diesem Leitfaden, hat keine solche Pflicht. Die Software wird ohne Gewährleistung bereitgestellt.
Die Dokumentation setzt eine bescheidene Untergrenze: jeder Linux-VPS mit 1 GB Arbeitsspeicher oder mehr. Sie fügt hinzu, dass MongoDB etwa 400 MB belegt, auf einer Instanz, die mehr als 300 Server jede Minute prüft.
Die Größe des Servers hängt also von der Zahl der Monitore, ihrem Intervall und dem Verlauf ab, den Sie aufbewahren. Auf einem Managed VPS beschreiben Sie uns Ihre Nutzung, und wir empfehlen Ihnen die passende Größe.
Seit Version 3.10 wird Checkmate als ein einziges Image ausgeliefert, ghcr.io/bluewave-labs/checkmate, das sowohl die Oberfläche als auch die API bereitstellt. MongoDB läuft daneben, in einem eigenen Container. Legen Sie auf einem Server mit Docker Engine und seinem Compose-Plugin, installiert aus dem Docker-Repository für Ubuntu, einen Ordner wie /opt/checkmate an und speichern Sie darin diese compose.yaml, die auf der Referenzdatei des Projekts aufbaut:
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:
Die beiden Geheimnisse kommen in eine Datei .env daneben, die Docker Compose von selbst liest. Legen Sie sie so an, dass nur root sie lesen kann, und starten Sie dann den Stack:
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 veröffentlicht: Die Referenzdatei veröffentlicht ihn ohne Adresse, und Docker öffnet ihn dann auf allen Adressen des Servers. Lokal veröffentlicht, ist er nur über den Reverse Proxy erreichbar.CLIENT_HOST ist die Adresse, die Ihre Nutzer eingeben, mit https://. Checkmate verwendet sie für die Cross-Origin-Prüfungen und für die Links in seinen Alarmen und E-Mails.NODE_ENV=production: Das README verlangt es für echte Bereitstellungen. Ohne diese Variable läuft die Anwendung im Entwicklungsmodus, der die Ratenbegrenzung der API abschaltet.ENCRYPTION_KEY ist in der Referenzdatei optional. Er verschlüsselt die Geheimnisse, die Checkmate speichert, und v4.0.0 verlangt ihn für die Docker-Monitore über TLS und für Checkmate Connect. Setzen Sie ihn von Anfang an: Das ist einfacher, als ihn später nachzutragen.latest und lädt es bei jedem Start. Mit einer vollständigen Versionsnummer, hier v4.0.0, bestimmen Sie selbst, wann jedes Update kommt.mongo-data enthält alle Ihre Daten: Monitore, Prüfungen, Nutzer und Einstellungen.Der erste Start führt die Migrationen der Datenbank aus; auf unserem Test-VPS meldete sich die Anwendung in weniger als zehn Sekunden als betriebsbereit. Um zu prüfen, ob sie antwortet:
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
Der erste Befehl antwortet 200. Der zweite antwortet "data":false, solange kein Konto existiert, und true, sobald der Superadmin angelegt ist.
Checkmate hat kein Standardkonto. Die erste Person, die sich registriert, wird Superadmin; legen Sie Ihr Konto also gleich nach dem ersten Start an, bevor Sie die Adresse öffentlich zugänglich machen. Ein SSH-Tunnel holt den Port 52345 des Servers auf Ihren Computer, unter http://localhost:52345; ergänzen Sie -p und den SSH-Port, der in Ihrem Kundenbereich angegeben ist.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: Checkmate zeigt seine Registrierungsseite.Ab dann ist die öffentliche Registrierung geschlossen: Auf unserem Test-VPS wurde jeder neue Besucher zur Anmeldeseite geleitet, und auch die Registrierungsadresse führte dorthin. Andere Personen kommen per Einladung dazu, aus dem Bereich Team der Kontoeinstellungen, mit der Rolle User oder Admin. Die Einladung geht per E-Mail hinaus, braucht also die SMTP-Einstellungen weiter unten, und ihr Link läuft nach einer Stunde ab.
| Rolle | Was sie darf |
|---|---|
| User | Alle Monitore, das Dashboard, die Prüfungen, die Vorfälle, die Statusseiten und die Einstellungen sehen, ohne etwas zu ändern |
| Admin | Alles, was ein User darf, dazu die Monitore, die Benachrichtigungskanäle, die Vorfälle, die Wartungsfenster, die Statusseiten, die Einladungen und die globalen Einstellungen, SMTP inbegriffen |
| Superadmin | Alles, was ein Admin darf, dazu Konten direkt anlegen, einen anderen Nutzer bearbeiten, eine Rolle oder ein Passwort ändern |
Seit v4.0.0 sind Tags, Statusseiten und Proxys Aktionen für Admins: Ein User, der sie vorher verwalten konnte, verliert diesen Zugriff nach dem Update.
Der Container liefert Checkmate über HTTP aus, auf Port 52345. HTTPS übernimmt ein vorgeschalteter Reverse Proxy: Die Dokumentation nennt Caddy, Traefik und nginx. Wir haben Caddy getestet, installiert aus seinem offiziellen Repository für Debian und Ubuntu: Es bezieht das Zertifikat von Let’s Encrypt selbst, erneuert es und leitet standardmäßig den Header Host und die Header X-Forwarded-* weiter.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST muss dieselbe Adresse mit https:// enthalten wie der Proxy. Führen Sie nach einer Änderung docker compose up -d aus, um den Container neu zu erstellen.Alarme per E-Mail und Einladungen laufen über eine SMTP-Verbindung für den ganzen Server, eingestellt unter „Settings“, Reiter „Email“: Host, Port, Benutzer, Passwort und Absenderadresse, dann „Save“ und „Test“. Verwenden Sie auf einem VPS von Simafri einen authentifizierten SMTP-Server auf Port 587 oder 465: den E-Mail-Dienst Ihrer Domain oder einen Versanddienst. Legen Sie danach eine E-Mail-Benachrichtigung mit den zu alarmierenden Adressen an und verknüpfen Sie sie mit Ihren Monitoren.
Slack, Discord, Teams, Telegram und die anderen Kanäle legen Sie genauso an, unter „Notifications“, jeweils mit ihrer Webhook-Adresse oder ihrem Token und jeweils mit einer Schaltfläche „Test“.
Ein Heartbeat-Monitor überwacht eine Aufgabe, die von selbst läuft, etwa ein nächtliches Backup. Erzeugen Sie den Ping-Schlüssel des Teams unter „Settings“, Reiter „Monitoring“ (er wird nur einmal angezeigt), legen Sie einen Heartbeat-Monitor mit einem Slug und einem Alarmfenster an und rufen Sie dann am Ende der Aufgabe seine Ping-URL auf:
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"
Wenn Sie /fail oder den Exit-Code der Aufgabe an die URL anhängen, wird der Monitor sofort als ausgefallen markiert, ohne das Ende des Fensters abzuwarten.
Unter „Status pages“ veröffentlicht ein Admin eine Seite, die ausgewählte Monitore und ihre Verfügbarkeit auflistet, für Ihre Kunden oder Ihr Team. Seit v4.0.0 hat jede Statusseite eine Zeitzone, standardmäßig UTC.
Alles liegt an zwei Stellen: in der MongoDB-Datenbank, im Volume mongo-data, und in Ihrer Datei .env. Bewahren Sie Letztere sicher auf: ENCRYPTION_KEY wird gebraucht, um die in der Datenbank gespeicherten Geheimnisse zu lesen, und JWT_SECRET hält Ihre Nutzer angemeldet. Das MongoDB-Image enthält mongodump:
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak
Planen Sie diese Kopie regelmäßig ein und senden Sie sie außerhalb des Servers; ein Heartbeat-Monitor kann Ihnen melden, wenn sie einmal nicht mehr läuft. Auf der Festplatte abgelegt, gehen die Archive außerdem in die nächtlichen Backups des Servers ein.
Halten Sie auf derselben oder einer neuen Installation, mit derselben .env, die Anwendung an, spielen Sie das Archiv ein und starten Sie sie dann wieder:
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate
Wir haben den ganzen Ablauf auf unserem VPS getestet: Backup, die Datenbank tatsächlich gelöscht, Wiederherstellung. Der Monitor und das Konto waren wieder da, und die Anmeldung funktionierte sofort wieder.
Checkmate v4.0.0 bietet außerdem verschlüsselte Cloud-Backups über Checkmate Connect an, einen optionalen Dienst, kostenlos während seiner Beta, der ENCRYPTION_KEY und einen Superadmin braucht, um die Installation anzumelden. Die Kopien oben funktionieren ohne ihn.
Lesen Sie die Release Notes, erstellen Sie ein Backup, ändern Sie das Image-Tag in der compose.yaml, laden Sie dann das neue Image und erstellen Sie den Container neu. Die Migrationen der Datenbank laufen beim Start von selbst:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump und mongorestore mit. Keine neue Umgebungsvariable ist nötig.checkmate-client, checkmate-backend und checkmate-mongo, die nicht mehr aktualisiert werden. Wechseln Sie zu ghcr.io/bluewave-labs/checkmate und behalten Sie Ihren MongoDB-Dienst und sein Volume; die Variablen UPTIME_APP_* werden nicht mehr gelesen.Checkmate sendet einen anonymen Bericht pro Tag: eine Installationskennung, die Version, die Art der Installation und die Zahl der Monitore jedes Typs, niemals Ihre URLs oder Ergebnisse. Es weist beim Start in seinem Protokoll darauf hin. Um sie abzuschalten, ergänzen Sie TELEMETRY_ENABLED=false in der Umgebung des Dienstes checkmate und führen Sie dann docker compose up -d aus.
Beim Selbsthosting müssen Sie neben der Anwendung auch den Server betreuen. Auf einem Managed VPS übernehmen unsere Teams den Server und betreuen Ihre Instanz proaktiv; Checkmate bleibt Ihre Software, mit seinen Monitoren und Ihren Einstellungen.
| Thema | Unsere Teams | Sie |
|---|---|---|
| Der Server | System- und Sicherheitsupdates, Eingriffe am Server inbegriffen | Der Zeitpunkt, der zu Ihrem Betrieb passt |
| Die Überwachung | Server rund um die Uhr im Blick, mit Eingriff, ohne auf Ihren Anruf zu warten | Ihre eigenen Monitore, Alarme und Statusseiten in Checkmate |
| Checkmate | Proaktive Betreuung: Fehler, lange Antwortzeiten, Datenbank und Speicherplatz erkannt, Korrektur empfohlen | Installation, Updates und Einstellungen, die Sie umsetzen, selbst oder mit Ihrem KI-Assistenten |
| Die Nutzer und Alarme | Der Server, der sie trägt, überwacht und gesichert | Die Konten, die Rollen, die Einladungen und die Benachrichtigungskanäle |
| Die Backups | Jede Nacht, verschlüsselt und außerhalb der Maschine aufbewahrt; Wiederherstellung inbegriffen | Die eigenen Datenbankexporte von Checkmate und die Wiederherstellungsanfrage, wenn Sie sie brauchen |
| Die Migration | Ihr aktueller Server wird kostenlos migriert | Der Zeitpunkt der Umstellung |
Wenn unsere Teams lieber in der Anwendung selbst eingreifen sollen, wird diese Leistung nach Stunden oder pauschal abgerechnet, mit einem Kostenvoranschlag vor dem Eingriff.
Mit einem Managed VPS von Simafri halten unsere Teams den Server Ihrer Checkmate-Instanz aktuell, überwachen ihn Tag und Nacht und greifen ein, ohne auf Ihren Anruf zu warten; sie betreuen auch Ihre Instanz proaktiv und empfehlen Ihnen die sinnvollen Korrekturen, die Sie umsetzen, selbst oder mit Ihrem KI-Assistenten. Die Backups werden jede Nacht verschlüsselt und außerhalb der Maschine aufbewahrt, ihre Wiederherstellung ist inbegriffen, und die Migration Ihres aktuellen Servers ist kostenlos.
Ja. Checkmate steht unter der AGPL-3.0-Lizenz: Sie können es für sich, Ihr Team oder Ihre Kunden betreiben, ohne eine Lizenz zu kaufen. Wenn Sie es ändern und anderen über das Netzwerk zur Nutzung bereitstellen, teilen Sie Ihre Änderungen. Bleiben die Kosten für den Server, auf dem es läuft.
Verwenden Sie die Referenz-compose.yaml: das Image ghcr.io/bluewave-labs/checkmate und MongoDB 8.0. Legen Sie JWT_SECRET und ENCRYPTION_KEY in einer Datei .env ab, setzen Sie CLIENT_HOST auf Ihre https-Adresse und NODE_ENV auf production, veröffentlichen Sie den Port 52345 auf 127.0.0.1, starten Sie docker compose up -d und schalten Sie einen Reverse Proxy mit HTTPS davor.
Es gibt keine. Die erste Person, die sich auf einer neuen Instanz registriert, wird Superadmin. Legen Sie Ihr Konto gleich nach dem ersten Start an, über einen SSH-Tunnel; danach werden Besucher zur Anmeldeseite geleitet, und neue Nutzer kommen per Einladung dazu.
Die Dokumentation verlangt einen Linux-VPS mit 1 GB Arbeitsspeicher oder mehr. Auf unserem Test-VPS belegte eine frische Installation etwa 300 MB für Checkmate und 280 MB für MongoDB. Die Festplatte wächst mit der Zahl der Monitore, ihrem Intervall und dem aufbewahrten Verlauf, standardmäßig 90 Tage.
Richten Sie die SMTP-Verbindung unter Settings, Reiter Email, ein: Host, Port 587 oder 465, Benutzer, Passwort und Absender, dann Save und Test. Legen Sie eine E-Mail-Benachrichtigung mit den zu alarmierenden Adressen an und verknüpfen Sie sie mit Ihren Monitoren. Die Einladungen verwenden dieselben Einstellungen.
Exportieren Sie die MongoDB-Datenbank mit docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, und bewahren Sie eine Kopie Ihrer Datei .env auf, deren ENCRYPTION_KEY gebraucht wird, um die gespeicherten Geheimnisse zu lesen. Stellen Sie mit mongorestore --archive --gzip --drop wieder her, bei angehaltener Anwendung.
Lesen Sie die Release Notes und erstellen Sie ein Backup, ändern Sie das Image-Tag in der compose.yaml und führen Sie dann docker compose pull und docker compose up -d aus. Die Migrationen der Datenbank laufen beim Start von selbst.
Ein Managed VPS deckt den Server ab: System, Sicherheit, Überwachung und Backups. Unsere Teams betreuen auch Ihre Instanz proaktiv und empfehlen Ihnen die sinnvollen Korrekturen, die Sie umsetzen. Ein Eingriff in der Anwendung wird nach Stunden oder pauschal abgerechnet.
Simafri
Sprechen wir über Ihr Vorhaben
Sagen Sie uns in wenigen Worten, was Sie brauchen: Wir melden uns schnell bei Ihnen.
Vielen Dank! Ihre Anfrage wurde gesendet. Wir melden uns in Kürze bei Ihnen.
Sie schreiben lieber eine E-Mail? Schreiben Sie uns an support@simafri.com.