Checkmate

<p align=center> <a href="https://trendshift.io/repositories/12443" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12443" alt="bluewave-labs%2Fcheckmate | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a></p> <p align="center"> 🇺🇸 <a href="README.md">English</a> | 🇸🇦 <a href="docs/translations/README.ar.md">العربية</a> | 🇪🇸 <a href="docs/translations/README.ca.md">Català</a> | 🇨🇿 <a href="docs/translations/README.cs.md">Čeština</a> | 🇩🇪 <a href="docs/translations/README.de.md">Deutsch</a> | 🇪🇸 <a href="docs/translations/README.es.md">Español</a> | 🇫🇮 <a href="docs/translations/README.fi.md">Suomi</a> | 🇫🇷 <a href="docs/translations/README.fr.md">Français</a> | 🇮🇹 <a href="docs/translations/README.it.md">Italiano</a> | 🇯🇵 <a href="docs/translations/README.ja.md">日本語</a> | 🇧🇷 <a href="docs/translations/README.pt-BR.md">Português (Brasil)</a> | 🇷🇺 <a href="docs/translations/README.ru.md">Русский</a> | 🇹🇭 <a href="docs/translations/README.th.md">ไทย</a> | 🇹🇷 <a href="docs/translations/README.tr.md">Türkçe</a> | 🇺🇦 <a href="docs/translations/README.uk.md">Українська</a> | 🇻🇳 <a href="docs/translations/README.vi.md">Tiếng Việt</a> | 🇨🇳 <a href="docs/translations/README.zh-CN.md">简体中文</a> | 🇹🇼 <a href="docs/translations/README.zh-TW.md">繁體中文</a> </p>

<h1 align="center"><a href="https://bluewavelabs.ca" target="_blank">Checkmate</a></h1> <p align="center"><strong>An open source uptime and infrastructure monitoring application</strong></p>

<img width="1703" height="1041" alt="image" src="https://github.com/user-attachments/assets/0f4dcf38-9b42-4b84-8633-ff34778df1a8" /> <br>

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.

Checkmate has been stress-tested with 1000+ active monitors without any particular issues or performance bottlenecks.

📚 Table of contents

• 📦 Demo
• 🔗 User's guide
• 🛠️ Installation
• 🚀 Performance
• 💚 Questions & Ideas
• 🧩 Features
• 🏗️ Screenshots
• 🏗️ Tech stack
• 🔗 A few links
• 🤝 Contributing

<a id="demo"></a>

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

<a id="users-guide"></a>

User's guide

Usage instructions can be found here.

Prerequisites

• Docker installed
• Git installed

<a id="installation"></a>

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.

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 | | LOG_LEVEL | No | Server log level: error, warn, info, or debug (default debug) |

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, you can also use Coolify, Elestio, K8s, Sive Host (South Africa), Cloudzy or Pikapods to quickly spin off a Checkmate instance. If you would like to monitor your server infrastructure, you'll need Capture agent. Capture repository also contains the installation instructions.

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.

For more documentation, see the docs directory.

<a id="performance"></a>

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:

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

<a id="questions--ideas"></a>

Questions & Ideas

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

• Discord channel (preferred)
• GitHub Discussions (we check here from time to time)

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

<a id="features"></a>

Features

• Completely open source, deployable on your servers or home devices (e.g Raspberry Pi 4 or 5)
• Several monitoring options: Uptime, Docker, Ping, SSL, Port, Game server
• 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
• Status pages with 4 beautiful themes
• E-mail, Webhooks, Discord, Slack, PagerDuty, Matrix, Rocket.Chat, Microsoft Teams, Telegram, Pushover, Twilio (SMS) notifications
• Scheduled maintenance
• JSON query monitoring
• Multi-language support for Arabic, Chinese (Simplified), Chinese (Traditional, Taiwan), Czech, English, Finnish, French, German, Japanese, Portuguese (Brazil), Russian, Spanish, Thai,