Checkmate logo

Checkmate

bluewave-labs/Checkmate

Checkmate is an open-source, self-hosted tool designed to track and monitor server hardware, uptime, response times, and incidents in real-time with beautiful visualizations. Don't be shy, join here: https://discord.com/invite/NAb6H3UTjK :)

11,062stars TypeScript AGPL-3.0 last commit 2 hours ago
README.md

bluewave-labs%2Fcheckmate | Trendshift

🇺🇸 English | 🇸🇦 العربية | 🇪🇸 Català | 🇨🇿 Čeština | 🇩🇪 Deutsch | 🇪🇸 Español | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇧🇷 Português (Brasil) | 🇷🇺 Русский | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇻🇳 Tiếng Việt | 🇨🇳 简体中文 | 🇹🇼 繁體中文

Checkmate

An open source uptime and infrastructure monitoring application

Run on PikaPods

image


This repository contains both the frontend and the backend of Checkmate, an open-source, self-hosted monitoring tool for tracking server hardware, uptime, response times, and incidents in real-time with beautiful visualizations. Checkmate regularly checks whether a server/website is accessible and performs optimally, providing real-time alerts and reports on the monitored services' availability, downtime, and response time.

Checkmate also has an agent, called Capture, to retrieve data from remote servers. While Capture is not required to run Checkmate, it provides additional insights about your servers' CPU, RAM, disk, and temperature status. Capture can run on Linux, Windows, Mac, Raspberry Pi, or any device that can run Go.

🚀 Proven at scale

Checkmate is used in production to monitor 1,600+ servers on a single deployment.

✅ No reported performance bottlenecks
✅ No significant operational issues

Checkmate also scales horizontally for more than 5000 servers: you can run dedicated worker nodes that share the check load through MongoDB.

📚 Table of contents

Demo

You can see the latest build of Checkmate in action.

The username is demouser@demo.com and the password is Demouser1! (just a note that we update the demo server from time to time, so if it doesn't work for you, please ping us on the Discussions channel).

User's guide

Usage instructions can be found here.

Prerequisites

  • Docker with Docker Compose installed
  • Git only if you want to build the image yourself

Installation

The quickest way to run Checkmate is the reference Docker Compose file. It starts two services: the all-in-one Checkmate application image (ghcr.io/bluewave-labs/checkmate) and a separate MongoDB service.

What “all-in-one” means: the Checkmate application is packaged in a single image; MongoDB is not embedded in that image and remains required. The reference Compose file starts MongoDB for you. For custom deployments, configure DB_CONNECTION_STRING to use an external MongoDB instance.

curl -O https://raw.githubusercontent.com/bluewave-labs/checkmate/master/docker/docker-compose.yaml
JWT_SECRET="$(openssl rand -hex 32)" docker compose up -d

Then open http://localhost:52345. If the app is reached at another origin (domain or LAN IP), set CLIENT_HOST accordingly. To build the image yourself, run docker build -f docker/Dockerfile -t checkmate . from a checkout. For TLS, put any reverse proxy (Caddy, Traefik, nginx) in front of port 52345.

Install with one click

You can also run Checkmate on any of these platforms:

RepoCloud
RepoCloud
PikaPods
PikaPods
Coolify
Coolify
Elestio
Elestio
Easypanel
Easypanel
Kubernetes
Kubernetes
Railyard
Railyard
Sive Host
Sive Host
Cloudzy
Cloudzy
Pethost
Pethost
xCloud
xCloud
Ryvord
Ryvord

Note that the Helm chart has not yet been migrated to the all-in-one image: it still deploys the legacy checkmate-client, checkmate-backend and checkmate-mongo images, pinned at v3.8.1.

Configuration

The image is configured entirely through environment variables on the server container:

Variable Required Description
DB_CONNECTION_STRING Yes MongoDB connection string, e.g. mongodb://mongodb:27017/uptime_db
JWT_SECRET Yes Secret used to sign auth tokens; generate one with openssl rand -hex 32
CLIENT_HOST Yes The URL users reach the app at, e.g. https://checkmate.example.com; used for CORS and for links in notifications and emails
ENCRYPTION_KEY No Encrypts stored secrets at rest: Docker TLS client keys and the Checkmate Connect credential. Required to use TLS Docker monitors or to enroll with Checkmate Connect. Generate one with openssl rand -base64 32. Comma-separated list: the first key encrypts, every key decrypts. Must be identical on the API and every worker. To rotate without downtime, deploy OLD_KEY,NEW_KEY everywhere, then NEW_KEY,OLD_KEY everywhere, wait for the worker to re-encrypt every row, then drop OLD_KEY.
PORT No Port the API and web client are served on (default 52345)
HEALTH_PORT No Port for the /livez, /readyz and /metrics endpoints, served by any process that runs the job worker (default 52346)
NODE_ENV No development, production or test (default development). development disables the general API rate limiter; set production on real deployments
LOG_LEVEL No Server log level: error, warn, info, or debug (default info)
TOKEN_TTL No Lifetime of issued auth tokens, e.g. 12h or 7d (default 99d)
QUEUE_MODE No primary (default) runs the API, the web client and the job scheduler; worker runs a job-processing worker only, with no API
QUEUE_PRIMARY_PROCESSES No true (default) or false. Whether a primary node also processes monitoring jobs itself; set false when dedicated worker nodes handle all checks. Ignored in worker mode
STATUS_PAGE_THEMES_ENABLED No true (default) or false. When false, status pages ignore theme settings and always render the default theme
TELEMETRY_ENABLED No true (default) or false. Set false to stop sending the daily anonymous usage heartbeat; see Telemetry
TELEMETRY_URL No Where the heartbeat is sent. Only needed to point it at your own collector
CONNECT_ALLOWED_HOSTS No Comma-separated hostnames this server may enroll with Checkmate Connect against; an entry starting with . matches its subdomains (.example.com matches connect.example.com). Defaults to the official Checkmate Connect hosts; only needed if you run your own Connect service
CONNECT_API_URL No Overrides the Checkmate Connect API base URL used for cloud backups. When set, Checkmate also accepts any http(s) storage URL the Connect API returns. Only needed if you run your own Connect service
CONNECT_MONGODUMP_BIN No Path to mongodump, used for Checkmate Connect cloud backups. Defaults to mongodump on PATH; the Docker image includes it
CONNECT_MONGORESTORE_BIN No Path to mongorestore, used for Checkmate Connect cloud backups. Defaults to mongorestore on PATH; the Docker image includes it

The web client needs no configuration by default: it calls the API on the same origin it was served from (/api/v1). For setups where the defaults don't apply — for example, the API is reached through a different origin than the page — the server renders overrides into the client at runtime via these optional variables:

Variable Description
CLIENT_CONFIG_API_BASE_URL Full base URL the client calls the API at, e.g. https://api.example.com/api/v1; defaults to same-origin /api/v1
CLIENT_CONFIG_CLIENT_HOST Origin used when the client builds absolute links (invites, status pages); defaults to the browser's current origin
CLIENT_CONFIG_LOG_LEVEL Browser console log level: error, warn, info, or debug (default error)

Upgrading from an older image? The UPTIME_APP_* variables (UPTIME_APP_API_BASE_URL, UPTIME_APP_CLIENT_HOST, UPTIME_APP_LOG_LEVEL) are no longer read. In most setups no replacement is needed — the same-origin defaults cover them; if you pointed the client at a different origin, use the CLIENT_CONFIG_* equivalents above. The checkmate-client, checkmate-backend, checkmate-mongo, and checkmate-backend-mono-multiarch images are no longer updated — switch to ghcr.io/bluewave-labs/checkmate, keeping your existing MongoDB service and data volume.

See full installation instructions in the Checkmate documentation portal.

Alternatively, any of the 1-click installation options listed above can spin up a Checkmate instance quickly. If you would like to monitor your server infrastructure, you'll need Capture agent. Capture repository also contains the installation instructions.

Telemetry

Checkmate sends one anonymous heartbeat per installation every 24 hours so we can see how many instances are running. It contains only:

Field Example What it is
instanceId 3f0c7a52-… A random UUID generated once and stored in your database. It is not derived from your hardware, hostname or network
version 3.12.0 Checkmate version
deployment docker docker for the official image, source otherwise
queueMode primary The QUEUE_MODE setting
nodeVersion 24.4.0 Node.js version
os linux Operating system
arch x64 CPU architecture

No URLs, hostnames, IP addresses, emails, names, monitor details or any other data you've entered are sent.

To opt out, set TELEMETRY_ENABLED=false on every server container and restart. The scheduled heartbeat is removed on the next start.

Using a Custom CA

If you need to monitor internal HTTPS endpoints with certificates from private Certificate Authorities (like Smallstep), see our Custom CA Trust Guide for Docker configuration options.

Docker monitors

A Docker monitor reports on every container running on a host. It can connect to the Docker daemon directly or read container metrics from a Capture agent. Direct monitors use the daemon's ping response for availability and record container state, health, CPU and memory usage, restart count, published ports and mounts. Enabling Collect container logs additionally stores the latest 200 log lines per container on every direct check; logs are kept for 7 days.

The Docker host field accepts three forms:

Host Example Notes
Local socket unix:///var/run/docker.sock Also accepts a bare absolute path such as /var/run/docker.sock. Use this for the daemon on the same machine Checkmate runs on.
Remote daemon tcp://docker.example.com:2376 Always uses mutual TLS; the port defaults to 2376. Unencrypted daemons on 2375 are not supported.
Capture agent https://capture.example.com/api/v1/metrics/docker Enter the full endpoint ending in /metrics/docker and its authorization secret. Checkmate requests all=true so stopped containers are included.

Capture-backed monitors normalize Capture's container state, health, CPU, memory, start time and exposed ports into the same Docker pages. Capture does not currently provide restart counts, mounts, published host-port bindings or container logs, so those values are shown as unavailable. Capture also reports a container whose health check is still starting as healthy, so the starting health state only appears on direct monitors, and stopped containers carry no CPU or memory metrics.

Monitoring the local socket. The reference Compose file does not mount the socket, so add it and grant the container the host's docker group. The image runs as an unprivileged user and cannot read the socket otherwise. Find the group id with stat -c %g /var/run/docker.sock, then:

services:
  checkmate:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    group_add:
      - "989"   # the gid printed by stat

Monitoring a remote daemon. Set the host to tcp://host:port and fill in the TLS credentials section of the monitor form with the same PEM files you would pass to docker --tlsverify:

  • CA certificate: the CA that signed the daemon's server certificate. Required unless Ignore TLS/SSL errors is on, which skips verifying the daemon's identity.
  • Client certificate: the certificate the daemon uses to authenticate Checkmate.
  • Client key: the matching private key, unencrypted (no passphrase). Checkmate checks that it matches the certificate, encrypts it with ENCRYPTION_KEY, and never shows it again. Leave the field blank when editing to keep the stored key.

TLS Docker monitors require ENCRYPTION_KEY to be set on the server (see Configuration). Saving one without it fails with an error telling you so. If the key is ever removed or rotated incorrectly, affected checks fail with a decryption error until it is restored.

If the daemon's certificate is signed by a private CA that you also want the rest of Checkmate to trust, see the Custom CA Trust Guide; for Docker monitors alone, the CA certificate field is enough.

Securing the Docker daemon with TLS

The Docker daemon does not enable TLS by default. Follow these steps on the Docker host to generate a CA, a server certificate, and a client certificate for Checkmate. This is the procedure from Docker's own guide, condensed. Replace docker.example.com and 203.0.113.10 with your daemon's DNS name and IP.

1. Create a CA. The CA key gets a passphrase; keep it offline once the certificates are issued.

openssl genrsa -aes256 -out ca-key.pem 4096
openssl req -new -x509 -days 365 -key ca-key.pem -sha256 -subj "/CN=docker-ca" -out ca.pem

2. Create the server certificate. The subject alternative names must cover every name or address Checkmate will use to reach the daemon.

openssl genrsa -out server-key.pem 4096
openssl req -subj "/CN=docker.example.com" -sha256 -new -key server-key.pem -out server.csr
cat > server-ext.cnf <<EOF
subjectAltName = DNS:docker.example.com,IP:203.0.113.10
extendedKeyUsage = serverAuth
EOF
openssl x509 -req -days 365 -sha256 -in server.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out server-cert.pem -extfile server-ext.cnf

3. Create the client certificate for Checkmate. Do not add a passphrase to this key; Checkmate cannot use encrypted private keys.

openssl genrsa -out key.pem 4096
openssl req -subj "/CN=checkmate" -new -key key.pem -out client.csr
echo "extendedKeyUsage = clientAuth" > client-ext.cnf
openssl x509 -req -days 365 -sha256 -in client.csr -CA ca.pem -CAkey ca-key.pem -CAcreateserial \
  -out cert.pem -extfile client-ext.cnf
rm client.csr server.csr server-ext.cnf client-ext.cnf
chmod 0400 ca-key.pem key.pem server-key.pem
chmod 0444 ca.pem server-cert.pem cert.pem

4. Point the daemon at the certificates. Move ca.pem, server-cert.pem and server-key.pem to /etc/docker/certs/ and configure /etc/docker/daemon.json:

{
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],
  "tls": true,
  "tlsverify": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem"
}

On distributions where the systemd unit already passes -H fd:// (Debian, Ubuntu and derivatives), the daemon refuses to start with hosts set in both places. Remove the flag from the unit with an override, then restart:

sudo systemctl edit docker.service
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd
sudo systemctl daemon-reload && sudo systemctl restart docker

Open port 2376 on the host firewall only to the machine running Checkmate.

5. Verify from the Checkmate host, then paste ca.pem, cert.pem and key.pem into the monitor form:

docker --tlsverify --tlscacert=ca.pem --tlscert=cert.pem --tlskey=key.pem \
  -H=docker.example.com:2376 version

Heartbeat monitors

A heartbeat monitor is passive: your job pings Checkmate when it runs, and the monitor goes down if no ping arrives within its alert window. Use it for cron jobs, backups and scheduled tasks.

Each ping URL combines the team's ping key with the monitor's slug:

https://<checkmate-host>/api/v1/heartbeat/<pingKey>/<slug>
  • Ping key: one per team. Generate or rotate it in Settings → Monitoring. It is shown once, so copy it when it appears; rotating replaces it and the old key stops working.
  • Slug: set when you create the monitor, for example nightly-backup. Lowercase letters, numbers and single hyphens.
Route Records
GET or POST /<pingKey>/<slug> an up check
GET or POST /<pingKey>/<slug>/fail a down check
GET or POST /<pingKey>/<slug>/<exitCode> up for 0, down for anything else

Optional query parameters, on any route:

Parameter Effect
duration=<ms> How long the run took, stored as the check's response time
msg=<text> A message stored on the check
create=true Creates the monitor if the slug doesn't exist yet (see below)
interval=<ms> Alert window for a monitor created by create=true (default 1 day)
# Report the exit code and how long the job took
START=$(date +%s); /path/to/job.sh; CODE=$?
curl -fsS -m 10 --retry 3 "https://<checkmate-host>/api/v1/heartbeat/<pingKey>/nightly-backup/$CODE?duration=$((($(date +%s) - START) * 1000))"

Creating monitors from a job. Add create=true and a ping to an unknown slug creates the heartbeat monitor, then records the ping. Later pings reuse it. The new monitor is named after the slug, owned by the admin who generated the ping key, and has no notifications until you add them in the UI. Requests with create=true are limited to 20 per hour per ping key, including pings to monitors that already exist, so remove the flag after the first run for jobs that ping more often than every 3 minutes. Without create=true, an unknown slug returns 404, so a typo never creates a monitor silently.

curl -fsS "https://<checkmate-host>/api/v1/heartbeat/<pingKey>/nightly-backup?create=true&interval=3600000"

Checkmate Connect

Checkmate Connect is an optional cloud service for self-hosted Checkmate, available from v4.0.0. It adds remote access to your installation without opening inbound ports, encrypted cloud backups with restore, and a watchdog that emails you when your server stops reporting. Checkmate runs fully without it. Connect is free during its beta.

To enroll a server:

  1. Set ENCRYPTION_KEY on the server and every worker (see Configuration). Enrolling requires it.
  2. Create a Connect account and add your server in the Connect dashboard. Copy the credential block it shows; it is shown only once.
  3. As a superadmin, open Settings → Checkmate Connect in Checkmate and paste the block under Enroll installation.

Full guide: checkmate.so/docs/connect. The sections below cover the server-side details.

Checkmate Connect remote access

Remote access keeps an outbound tunnel open from this server to Checkmate Connect, so you can reach the installation from its Connect address without opening inbound ports. A superadmin turns it on in Settings → Checkmate Connect after enrolling.

The tunnel forwards every request to this server's own PORT. The web UI loads over the Connect address only when this server serves it, which the default Docker image does. If you serve the client separately, for example from its own nginx or origin, only the API is reachable through Connect.

Development. npm run dev serves the client from Vite, so the API server has no UI to return and the Connect address answers 404. To test remote access with the UI, have the server serve a production build of the client. From the repository root:

ln -s ../client/dist server/public
cd client && npx vite build --watch

vite build --watch rebuilds client/dist on every save; reload the Connect address to pick up changes. Both server/public and client/dist are gitignored.

To go back to the normal dev setup, stop vite build --watch and remove the link from the repository root:

rm server/public

This deletes only the link, not client/dist. Leave off the trailing slash: rm server/public/ would target the linked directory instead of the link.

Checkmate Connect backups

Cloud backups copy this installation's database to Checkmate Connect. Each backup is encrypted on this server before upload, so Connect only stores ciphertext.

  • Recovery key. A superadmin generates it once in Settings → Checkmate Connect. It is shown only once and stored on this server encrypted with ENCRYPTION_KEY. No backup can be restored without it, so keep a copy somewhere other than this server.
  • What's backed up. Only data you created: monitors and their check history, incidents, status pages, notifications, maintenance windows, users, teams and settings, plus the record of applied data migrations. Queue and worker state is never backed up; after a restore, the job queue is rebuilt from the restored monitors. A configuration backup also leaves out check history (checks, monitorstats, geochecks, dockerlogs).
  • Runs on the job queue. "Back up now" queues the backup and whichever process runs jobs picks it up. With QUEUE_PRIMARY_PROCESSES=false and no worker running, it waits until a worker starts.
  • Scheduled backups. A superadmin can turn them on in Settings → Checkmate Connect under Scheduled backups and choose how often (every 1, 3 or 7 days) and whether each backup is full or configuration only. The first scheduled backup starts as soon as they're turned on. Each one is queued like "Back up now", so exactly one process runs it; one that comes due while another backup, restore or key check is in progress is skipped until the next interval. Restarting Checkmate doesn't trigger an extra backup. Scheduled backups count towards your plan's backup versions like manual ones.
  • Tools. Backups need mongodump and mongorestore from the MongoDB Database Tools on the processes that run jobs. The Docker image includes them. On a source install, install them and, if they aren't on PATH, set CONNECT_MONGODUMP_BIN and CONNECT_MONGORESTORE_BIN. The settings page shows the install steps until at least one job-processing process finds them.
  • Restore. A superadmin picks a backup under Restore a backup in Settings → Checkmate Connect and confirms it. Checkmate downloads it, checks its size and checksum, decrypts it with the recovery key and replaces the current data with it, on whichever process runs jobs. User accounts are replaced too, so log in with an account from the backup afterwards. A backup can be restored into a database with a different name. Restoring a backup made by an older version of Checkmate brings back that version's migration record; restart Checkmate afterwards so the newer migrations run on the restored data.
  • Moving to a new server. Enroll the new server with Checkmate Connect, then choose I already have a recovery key under Recovery key and enter the key from the original server. Checkmate decrypts one of your cloud backups to check the key before saving it, then lists the backups you can restore.

For more documentation, see the Checkmate documentation portal.

Performance

Thanks to extensive optimizations, Checkmate operates with an exceptionally small memory footprint, requiring minimal memory and CPU resources. Here’s the memory usage of a Node.js instance running on a server that monitors 323 servers every minute:

image

You can see the memory footprint of MongoDB on the same server (398Mb) for the same amount of servers:

image

Questions & Ideas

If you have any questions, suggestions or comments, you have several options:

Feel free to ask questions or share your ideas - we'd love to hear from you!

Features

  • Completely open source, deployable on your servers or home devices (e.g Raspberry Pi 5)
  • Several monitoring options: HTTP (with SSL certificate expiry), Ping, Port, DNS, Docker, gRPC, WebSocket, Game server
  • Heartbeat monitors for cron jobs, backups and other scheduled tasks
  • Page speed monitoring
  • Infrastructure monitoring (memory, disk usage, CPU performance, network etc) - requires Capture agent
    • Selective disk monitoring with mountpoint selection
  • Incidents at a glance
  • Dashboard with monitor status, uptime, currently down monitors, job queue and server health cards that you can rearrange and hide
  • Status pages with 5 beautiful themes
  • E-mail, Webhooks, Discord, Slack, PagerDuty, Matrix, Rocket.Chat, Microsoft Teams, Telegram, Pushover, ntfy, SignalGrid, Twilio (SMS) notifications
  • Scheduled maintenance
  • JSON query monitoring
  • Checkmate Connect (optional): remote access without opening inbound ports, encrypted cloud backups with scheduled runs and restore, and a watchdog that emails you when your server stops reporting
  • Multi-language support for Arabic, Catalan, Chinese (Simplified), Chinese (Traditional, Taiwan), Czech, English, Finnish, French, German, Italian, Japanese, Polish, Portuguese (Brazil), Russian, Spanish, Thai, Turkish, Ukrainian, and Vietnamese

Monitor Lifecycle

  1. A monitor executes a check (HTTP / ping / port / hardware via Capture agent)
  2. The result is stored (success/failure + response time)
  3. Recent check results are evaluated against the monitor's configured status change threshold
  4. If the monitor's status change threshold is met and the current status is not equal to the previous status, the monitor's state changes (e.g. up, down, breached). New monitors start as initializing; monitors inside a maintenance window are set to maintenance and are not checked
  5. Upon a state change: an incident is either created or resolved, depending on the monitor's current status
  6. Notifications are triggered based on configuration

Screenshots

image

image

image

image

Tech stack

A few links

  • If you would like to support us, please consider giving it a ⭐ and click on "watch".
  • Have a question or suggestion for the roadmap/featureset? Check our Discord channel or Discussions forum.
  • Need a ping when there's a new release? Use Newreleases, a free service to track releases.
  • Watch a Checkmate installation and usage video

Contributing

We are Alex (team lead), Gorkem, Aryaman, Malena and Mert helping individuals and businesses monitor their infra and servers.

We pride ourselves on building strong connections with contributors at every level. Despite being a young project, Checkmate has already earned more than 11K stars and attracted 150+ contributors from around the globe.

Our repo is starred by employees from Google, Microsoft, Intel, Cisco, Tencent, Electronic Arts, ByteDance, JP Morgan Chase, Deloitte, Accenture, Foxconn, Broadcom, China Telecom, Barclays, Capgemini, Wipro, Cloudflare, Dassault Systèmes and NEC, so don’t hold back — jump in, contribute and learn with us!

Here's how you can contribute:

  1. Star this repo :)
  2. Check Contributor's guideline. First timers are encouraged to check good-first-issue tag.
  3. Read a detailed structure of Checkmate if you would like to deep dive into the architecture.
  4. Open an issue if you believe you've encountered a bug.
  5. Check for good-first-issue's if you are a newcomer.
  6. Make a pull request to add new features/make quality-of-life improvements/fix bugs.
  7. Check out this interactive walkthrough of the Checkmate codebase on CodeCanvas here. To refine existing dataflow simulation or create new ones, follow the quick tutorial here.

Star History Chart