Checkmate: Your Open-Source Infrastructure Monitoring Solution
Discover how Checkmate brings uptime checks, server metrics, Docker monitoring, notifications, incident history, and public status pages into a self-hosted monitoring platform.
Know when your infrastructure needs attention
Checkmate is a self-hosted, open-source monitoring platform for website and API availability, network endpoints, DNS, TLS certificates, Docker, hardware metrics, and incident notifications. It helps operators see service health from a single dashboard while keeping operational data under their control.
Featured image concept: monitoring dashboard with green uptime indicators, server metrics, container status, and an alert bell. The graphic below is an in-article visual; upload a separate 16:9 image to WordPress for the post thumbnail.
Broad monitoring
Track HTTP/HTTPS, ping, TCP, DNS, TLS certificates, gRPC, WebSockets, PageSpeed, Docker, and hardware metrics.
Self-hosted control
Run the application and database on infrastructure you manage, subject to your own backup and security practices.
Actionable alerts
Send notifications to supported channels and review incident history rather than relying on a dashboard alone.
1. What Is Checkmate?
Checkmate is an open-source, self-hosted uptime and infrastructure monitoring platform maintained by BlueWave Labs. It brings several monitoring workflows into a web dashboard, including endpoint availability, response times, DNS and TLS checks, PageSpeed insights, Docker monitoring, server hardware metrics, notifications, incident records, and status pages.
It is useful for system administrators, DevOps teams, small businesses, agencies, homelab operators, and maintainers who want a monitoring service they can deploy on their own Linux or container host. Checkmate is distinct from Checkmk; this article covers the BlueWave Labs project at Checkmate.so.
Checkmate’s published project materials describe an AGPL-3.0 open-source license and Docker Compose, Kubernetes/Helm, and developer installation paths. Review the current license and deployment documentation before using it in a commercial or modified network-service deployment.
2. Key Features
Uptime and endpoint checks
Use HTTP/HTTPS checks to test website or API availability, ping to test reachability, and TCP checks to verify that a service port accepts connections. Depending on the monitor type, checks can also evaluate response behavior rather than simply whether a host answers.
DNS and TLS/SSL monitoring
Check DNS record resolution and keep an eye on TLS certificate validity and expiry. These checks help identify misconfigured records and certificates before users experience a service failure.
Server hardware metrics
The Checkmate Capture agent can report system-level information such as CPU, memory, disk, and network usage. Use trends to identify capacity pressure; thresholds should reflect the role and normal behavior of each system.
Docker container monitoring
Monitor a Docker host and inspect container state, health, resource usage, restarts, and available recent logs. A Docker-host monitor being reachable does not necessarily mean every container is healthy, so review per-container state and alerts too.
PageSpeed, incidents, and status pages
PageSpeed monitoring can track Lighthouse scores and Core Web Vitals. Incident history helps document outages and recovery, while public status pages can communicate service health to customers or internal teams.
Notification integrations
Checkmate supports multiple notification channels, including email, Slack, Discord, Microsoft Teams, Telegram, PagerDuty, and webhooks, with availability depending on the current release and configuration. Test each configured route before relying on it for production incidents.
3. How Checkmate Works
The standard Docker deployment runs the Checkmate application alongside MongoDB. The web interface is served by the application container, while MongoDB stores application and monitoring data. Hardware monitoring requires the Capture agent on monitored systems; Docker monitoring requires an appropriate connection to the Docker daemon.
| Component | Purpose | Notes |
|---|---|---|
| Checkmate application | Dashboard, APIs, monitor scheduling, and notifications | Published container image: ghcr.io/bluewave-labs/checkmate |
| MongoDB | Stores Checkmate’s persistent application data | Keep persistent storage and tested backups |
| Capture agent | Reports host hardware and system metrics | Install/configure on systems whose hardware metrics you need |
| Docker daemon connection | Allows Checkmate to inspect containers | Socket access is sensitive and should be enabled deliberately |
4. Prerequisites
- A Linux server, virtual machine, or other supported Docker host.
- Docker Engine and the Docker Compose plugin installed and working.
- Outbound internet access to download the Compose file and container images.
- A few gigabytes of free storage to start, with more capacity planned for your retention and deployment needs.
- A secure way to access the dashboard; for remote access, use a trusted LAN or a reverse proxy with HTTPS.
- A DNS name if you plan to provide access through a domain and configure a reverse proxy.
Check the installed versions:
docker --version
docker compose version
openssl versionIf a command is missing, install Docker using the official instructions for your distribution before continuing.
5. Install Checkmate with Docker Compose
Create a working directory
Use a dedicated directory so that the Compose file and future operational notes are easy to locate.
mkdir -p ~/checkmate
cd ~/checkmateDownload the official Compose file
Download the reference Compose file from the project’s official repository. Inspect it before deploying, particularly if you are adapting it for a production environment.
curl -fLO https://raw.githubusercontent.com/bluewave-labs/checkmate/master/docker/docker-compose.yaml
ls -lh docker-compose.yamlGenerate a strong JWT secret
Checkmate uses JWT_SECRET to sign authentication tokens. Generate a random value rather than using a sample secret or a value copied from a tutorial.
openssl rand -hex 32Keep this secret private. For repeatable deployments, store it in a protected environment file or secret manager according to the project’s current configuration guidance. Do not commit secrets to source control.
Start the services
For a local test, generate and pass the secret to Docker Compose as shown below. This environment assignment applies to this command; if you need to restart the stack later, ensure the required variables are provided again through your chosen secure configuration.
JWT_SECRET="$(openssl rand -hex 32)" docker compose -f docker-compose.yaml up -dCheck the service state and logs:
docker compose -f docker-compose.yaml ps
docker compose -f docker-compose.yaml logs --tail=100Open the dashboard
On the same host, open this address in a browser:
http://localhost:52345If you are connecting from another machine, use the server’s LAN address only after reviewing the published port and host configuration. For a domain or LAN IP deployment, configure CLIENT_HOST to the exact URL users will use, as described in the official installation guide. Do not expose the raw application port to the public internet without an appropriate secure access design.
Complete initial account setup
Follow the current first-run flow in the web interface to create or configure an administrator account. Use a unique, strong password and avoid reusing credentials from other systems.
6. Create Your First Monitor
Start with a low-risk HTTP monitor for a website or API you are authorized to check.
- Open the Checkmate dashboard and navigate to Uptime.
- Select Create monitor.
- Choose HTTP/HTTPS.
- Enter a descriptive monitor name, such as
VMoreCloud Website, and the target URL. - Choose an appropriate check interval. For a critical service, the documentation suggests considering a one-to-five-minute interval; tune it for your monitoring needs and target service.
- Save the monitor and open its details page.
- Confirm that the first check completes and inspect status and response-time information.
For infrastructure beyond websites, add ping checks for reachability, TCP checks for critical ports, DNS checks for important records, and TLS checks for public-facing certificates. Use descriptive names and document the owner and expected behavior of each monitor.
7. Configure Notifications
A monitoring dashboard is most useful when failures reach the right person. Configure at least one notification channel and test the delivery path.
- Open Notifications in the dashboard.
- Create a notification destination and choose a supported channel, such as email, Slack, Discord, Teams, Telegram, PagerDuty, or a webhook.
- Enter the channel-specific credentials or destination details required by the current integration.
- Choose the appropriate monitors or alert conditions for the notification rule.
- Use the available test option and confirm that the message reaches its destination.
- Document who receives alerts and how an incident is escalated outside business hours.
Use a dedicated service account or integration token when supported. Restrict permissions, rotate credentials when necessary, and avoid including passwords or sensitive URLs in notification payloads.
8. Monitor Hardware and Docker
Hardware monitoring with Capture
Install and configure the official Capture agent on the Linux host you want to monitor, following the current agent-specific instructions. Then add the corresponding hardware/infrastructure monitor in Checkmate. Validate that CPU, memory, disk, and network values update over time before relying on thresholds.
Docker container monitoring
To monitor a Docker host through a local socket, Checkmate’s application container must be able to reach the Docker socket. The official documentation shows a read-only socket mount such as:
volumes:
- /var/run/docker.sock:/var/run/docker.sock:roAdd this under the appropriate Checkmate service in your Compose file, following the existing YAML structure, and recreate the service. Although read-only is preferable, Docker socket access still exposes powerful host-level information and can carry substantial security risk. Enable it only when needed and protect the monitoring host accordingly.
After configuring access, create a Docker monitor and verify that the host is reachable and that individual container details appear. If you monitor a remote Docker daemon, use TLS and authenticated access; do not expose an unauthenticated Docker API over the network.
9. Security and Production Recommendations
- Use HTTPS remotely: Put a maintained reverse proxy such as Caddy, Traefik, or Nginx in front of the application and configure TLS.
- Restrict network access: Use a firewall or VPN to limit dashboard access to administrators and authorized users.
- Protect secrets: Store JWT secrets, notification tokens, and database credentials outside public repositories and logs.
- Back up MongoDB: Define a backup schedule, retain copies away from the monitoring host, and periodically test restoration.
- Update deliberately: Review release notes, back up persistent data, and follow the project’s migration instructions before changing images.
- Limit Docker privileges: Mount the Docker socket only when needed and understand the security implications.
- Plan retention and capacity: Monitor disk use on the monitoring server itself and decide how long historical data should be retained.
- Test alerts: Simulate a controlled failure in a test monitor and confirm notification delivery and escalation.
- Check telemetry settings: Review current documentation for any anonymous version heartbeat or telemetry option and configure it to match your privacy requirements.
10. Troubleshooting
The dashboard does not load
Confirm that containers are running and inspect recent logs. Check that the expected port is published and not blocked by the host firewall.
docker compose -f docker-compose.yaml ps
docker compose -f docker-compose.yaml logs --tail=150MongoDB or application startup errors
Review logs for database connection failures, missing environment variables, or volume permission issues. Confirm the application and database services are on the same Compose network and that the connection string matches the service name.
Remote access or browser-origin errors
When using a LAN address or domain instead of localhost, verify the documented CLIENT_HOST value, proxy configuration, DNS, and HTTPS setup. Ensure the configured URL matches the URL entered in the browser.
Hardware metrics are missing
Verify the Capture agent is installed and configured on the target, that the monitor points to the correct endpoint, and that network access is allowed. Check the current agent logs and documentation.
Docker containers are not visible
Check whether the Docker socket or TLS-protected remote endpoint is configured correctly. A containerized Checkmate deployment does not automatically have access to the host’s Docker daemon.
Notifications are not delivered
Use the integration’s test function, confirm credentials and recipient details, and check application logs and provider-side spam or delivery policies.
11. Frequently Asked Questions
Is Checkmate free and open source?
The project is published under the AGPL-3.0 license. Review the current license and its obligations—especially if you modify the software and make it available as a network service.
Does Checkmate replace every monitoring platform?
Not necessarily. It offers a broad set of uptime and infrastructure checks, but requirements for deep application tracing, complex metrics pipelines, enterprise integrations, or managed support may call for additional tools.
Can I deploy Checkmate on a Raspberry Pi?
The project documents multi-architecture images for Linux AMD64 and ARM64, including compatible Raspberry Pi systems. Check the current system and storage requirements for your particular device.
Can Checkmate monitor a website outside my network?
Yes, HTTP and other supported checks can target reachable endpoints. Ensure your monitoring server can resolve and reach the target and that the target’s terms and security policies permit the checks.
Does a Docker host monitor guarantee all containers are healthy?
No. The host can be reachable even if one or more containers are stopped or unhealthy. Review container-level status and alerts separately.
Should I expose the dashboard directly to the internet?
Avoid exposing the raw application port without protection. Prefer HTTPS through a reverse proxy, strong authentication, restricted access, and a documented patching and backup plan.
Where can I find installation help?
Start with the official Checkmate documentation and the project’s GitHub repository.
12. Official References
- Checkmate official website — project overview, monitor types, supported integrations, and license information.
- What Is Checkmate? — overview of monitoring capabilities.
- Installing Checkmate — current Docker, Compose, and Kubernetes installation options.
- Quick Start Guide — create an initial monitor and notification.
- Docker Monitors — Docker host connection options and security notes.
- Checkmate on GitHub — source code, releases, issues, and project information.