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.

It uses Capture to get data from remote servers and doesn't need anything other than the Checkmate server itself to monitor uptime and page speed.

Demo

We have a demo where you can test how the Uptime Manager works. We update it from time to time with the latest code. The username is [email protected] , and the password is Demouser1!

Questions & ideas

If you have a question, head over to GitHub's page. We also have a where you can ask questions or provide comments and suggestions.

Features

• Completely open source, deployable on your servers

• Website monitoring

• Memory, disk, CPU and temperature monitoring

• Network monitoring

Tech stack

Sponsor Checkmate

Your support helps keep alive and improving. Sponsorships go toward covering essential infrastructure like servers, domain costs, and email delivery services.

By sponsoring Checkmate, you’re also investing in the ongoing development of a powerful, open-source monitoring tool that gives teams better visibility and control over their systems.

The Logs section shows 3 pieces of information:

1. Server logs, which contain all log information in the Checkmate backend service.

2. Job queue, a list of all the jobs that are used to check monitors.

3. Diagnostics, showing general status of the system's health.

Under the Settings page, you can configure the server's behaviour.

Display timezone: The timezone of the dashboard you publicly display.

Appearance: Here you can select the theme (light or dark), and the dashboard language.

Google PageSpeed API key: You'll need a Google PageSpeed API key if you'd like to use Pagespeed monitor.

Monitor IP/URL on Status Page: Display the IP address or URL of monitor on the public Status page. If it's disabled, only the monitor name will be shown to protect sensitive information.

Monitor history: Define how long you want to keep the data for. You can also remove all past data and clear all stats. Note that clearing data is irreversible.

Global thresholds: Configure global CPU, Memory, Disk, and Temperature thresholds. If a value is provided, it will automatically be enabled for monitoring.

Demo monitors: You can add 3 demo monitors to your platform quickly for testing purposes.

This screen allows you to manage your personal information and account settings within the application.

Profile section

Enter your first name, last name and email here. You can also upload or delete a profile photo. If you want to delete an account, this can also be done here. Note that that this is irreversible and cannot be undone.

Checkmate is an optimized monitoring solution. While it runs on modest hardware, knowing your hardware requirements is important.

Here is an example: When you have 300 monitors, you'll need 3Gb of disk space each month if they are configured to check in 1 sec periods (intervals). This means that you'll need 36Gb of disk for the entire year to monitor 300 servers.

By default, Checkmate has a data retention policy of 90 days. This can be configured under Settings. Hence, if you need Checkmate to keep longer data periods, you can set it up accordingly.

By default, the Checkmate uses the snappy MongoDB compression method, featuring CPU usage with a moderate compression ratio. This is suitable for workloads where speed is more critical than storage savings. If you want, you can always use zlib in MongoDB configuration, which has a higher compression ratio than snappy but with more CPU overhead.

A notification channel keeps everyone in the loop. It alerts teams when downtime or performance issues crop up, pings engineers the moment incidents occur, and tells administrators about any system changes.

If you create a notification, you can add it to a monitor later.

When you create a notification, it'll ask you the following:

• Name: A descriptive name for your notification.

• Type: Select the type of notification channel you want to create (e.g Discord)

Each notification has its own configuration. When you select Type, the corresponding configuration will be shown under this section.

The figure below shows a high level architecture of the Uptime Manager.

Typical auth request overview

The following diagram describes a typical request to the /auth endpoints.

Typical monitor request overview

The following diagram describes a typical request to the /monitors endpoints.

JobQueue

The heart of this application is a JobQueue class that wraps a BullMQ Queue. A Monitor is considered a job, when one is created it is enqueued in the JobQueue. Jobs are handled by a pool of workers in the JobQueue and their tasks are executed in the order in which they are enqueued. Workers are scaled up and down based on the jobs/worker ratio as jobs are enqueued and dequeued.

High level overview of the JobQueue

SSL

SSL is handled by LetsEncrypt and Certbot. This works by Nginx and Certbot sharing the same volume where the certificates are held. The following snippet from the docker-compose.yaml file shows how this works.

Please see for more information on this setup.

The Maintenance mode allows you to manage and schedule maintenance periods for monitored URLs. During a maintenance window, no pings or HTTP requests are sent to the specified URLs, preventing downtime alerts during scheduled maintenance activities.

Creating a new maintenance window

When you click the "Create Maintenance Window" button, you will see a page similar to this:

Here's how to set up a new maintenance window:

General settings:

• Maintenance repeat: Select how often the maintenance window should repeat (e.g., don't repeat, daily, weekly).

• Date: Select the date the maintenance window should start.

• Start time: Set the time of day the window begins.

• Duration: Specify how long the maintenance window should last (in seconds, minutes, or hours).

Monitor related settings:

• Friendly Name: Provide a descriptive name for the maintenance window (e.g., "Maintenance at 10:37 PM for 30 minutes").

• Add Monitors: Select the specific monitors (URLs) for which this maintenance window will apply by typing and selecting from the list.

Once all fields are filled, click Create maintenance to save the new window.

Editing a maintenance window

• To edit an existing window, click the gear icon under Actions in the table view.

• Update the required fields and save your changes.

We generally follow the gitflow workflow model. If you’re not familiar with it, the general steps are

1. Create a feature branch in your local repository and make your changes.

2. Push your branch to the remote repository on Github.

3. Open a pull request.

4. The rest of the team will review the pull request and either approve or request changes.

5. If changes are requested, make changes and push.

6. Project maintainer will merge the branch, closing the pull request and deleting the remote branch.

Git

If you are inexperienced with Git or need a refresher please visit our to help get up to speed. If you’d like to go further in depth, this is a good resource.\

This page provides a comprehensive overview of all incidents across the servers you monitor. The incidents are displayed in a detailed table format, allowing you to quickly assess the status and details of each incident.

Incidents overview

Incidents page includes a table where Monitor name, Status (down or cannot resolve), date and time of the incident, status code and corresponding message is shown.

By default, the page shows all incidents from all servers. There is also a dropdown button above the table where you can select a server name.

The incidents table includes the following columns:

Here you can configure your public status page. You'll see two tabs here, General settings and Contents.

General settings

Access

The Uptime Manager product uses the MERN stack, which is to say that the project uses:

• React on the frontend via Vite

Infrastructure monitor is used to get information (hardware and network) from a remove Linux, Windows or MacOS machine.

This is the only feature of Checkmate that retrieves data from remote servers using Checkmate's server agent, Capture.

In order to check a remote server's CPU, disk, memory and disk, you need to install Checkmate agent first. Please read to install Capture.

For an available list of platforms and what kind of data Capture retrieves,

General Overview

Checkmate is an open-source server monitoring tool designed to track the uptime, downtime, and performance of servers, websites, or web applications.

It provides real-time alerts, status updates, and detailed response time metrics.

Sidebar menu

The sidebar on the left contains the following sections:

• Uptime: Shows the uptime of your monitors

• Pagespeed: Shows your web page speed and performance

• Infrastructure: Gets RAM, CPU, disk etc data from your servers and shows on a UI.

• Incidents: A section where alerts and incidents regarding the monitored services are logged. This helps users investigate issues and track downtime history.

User info section

At the bottom of the sidebar, you’ll see the current logged-in user alongside with the role. When you click on the hamburger menu, you'll see sections like Profile, Password, Team and Log out.

Dashboard content

The main section of the dashboard displays an overview of the monitored services, including their current status and key performance indicators.

The dashboard offers a summary of your uptime monitors:

• Up: The number of monitored services that are currently operational.

• Down: The number of monitored services that are currently experiencing issues.

• Paused: The number of services that have their monitoring paused.

Monitoring table

This section lists all the services being monitored, showing key details for each service:

• Host: The name and URL of the service being monitored.

• Status: The current status of the service, indicated by color-coded icons:

  • Green: Up (operational)

  • Red: Down (non-operational)

At the top-right corner of the dashboard, there’s a button labeled Create monitor. This allows users to add a new server or website to monitor.

A search bar is available above the list of monitored services, enabling users to quickly locate specific services by name or URL.

Status indicators

• Green: Indicates the service is currently up and operational.

• Red: Indicates the service is down or experiencing problems.

• Yellow: Indicates that monitoring for this service is paused.

Each service has a graph in the Response Time column that displays its performance history over time. This allows you to easily visualize any spikes or drops in performance.

The gear icon next to each monitored service allows for quick access to configuration settings or additional monitoring options.

Table actions

When you click on the gear icon, you'll see a few options that correspond to that host:

1. Open site: Opens the monitored website or server in a new browser tab.

2. Details: Displays historical uptime and performance metrics for the service.

3. Incidents: Shows a log of all incidents related to the service, including downtime and performance issues.

4. Configure: Allows modification of monitoring parameters like check frequency and alert preferences.

Under Dashboard > Pagespeed, you can see an overview of pagespeed monitors for different websites. This dashboard helps you view optimal website performance by providing clear, actionable insights into various aspects of your site's speed and user experience.

When you add a new page speed monitor, it is added here. Click on the "Create new" button to add a new page speed.

Here, both monitors are shown as "Live (Collecting Data)" with a green dot, indicating they are actively monitoring. Each monitor has a small graph, representing recent pagespeed performance over time.

Details of a pagespeed monitor

When you click on a pagespeed card, you'll see an overview of data collected using Google's PageSpeed Monitor API.

Score history graph

Shows performance trends over the past 24 hours. Four colored lines represent different metrics:

• Accessibility (blue)

• Best Practices (orange)

• Performance (green)

• Search Engine Optimization (purple)

You can toggle these metrics on/off using the checkboxes on the right

Performance report

You'll see an overall score of your server's pagespeed.

Performance metrics

• Cumulative Layout Shift: Measures visual stability

• Speed Index: How quickly content is visually displayed

• First Contentful Paint: Time until the first content is rendered

• Largest Contentful Paint: Time until the largest content element is rendered

Creating a new pagespeed

When you are on a pagespeed screen, click on the "Create pagespeed" button. You'll see a screen similar to this:

This page allows you to set up a new pagespeed monitor for your website. Follow these steps to configure your monitor:

General settings

• URL to monitor: Enter the full URL of the website you want to monitor (e.g., ).

• Display name (optional): Enter a custom name for your monitor to easily identify it in your dashboard.

Checks to perform

Here, you can choose between HTTPS (recommended for secure sites) or HTTP protocols.

Incident notifications

• Notify via email (to your email address)

Advanced settings

Check frequency: Choose how often you want the system to check your website's pagespeed. The default is set to 3 minutes.

After configuring all settings, click the "Create monitor" button at the bottom right of the page.

Tips

• Ensure the URL you enter is correct and accessible.

• Choose a descriptive display name if you're monitoring multiple sites.

• Consider the trade-off between check frequency and resource usage. More frequent checks provide more data but may use more resources.

• Remember to enable your preferred notification methods to stay informed about incidents.

After creating the monitor, you'll be able to view its performance data in your dashboard. This will help you track your website's pagespeed and optimize its performance over time.

General troubleshooting steps

If you are having trouble running Checkmate, those are the general steps you can take towards finding the issue.

Verify port availability:

• Ensure the port used by the Checkmate server (e.g., 5000) is not already in use by another application or container.

• Check environment variables: Verify that all required environment variables are set correctly with valid values.

• Check database connections: If using external databases (Redis, MongoDB), verify that the client points to the correct IP address and port for each database.

• Check for port interference: Verify that no other containers or applications create port conflicts.

Check network connectivity:

• Verify your internet connection.

• Check for firewall/antivirus interference.

• Review proxy server settings.

Check Docker server status:

• Access the Docker dashboard to check the server container's status.

• Inspect the server container's logs for error messages.

Check application configuration:

• Review client-side configuration for any misconfigurations.

• Enable debug logging: Enable error or warn log levels in the client application for more detailed troubleshooting information.

Test server endpoint directly:

• Try accessing the server endpoint directly in your browser (e.g., localhost:5000/api/v1).

  • If you see any message other than "Cannot GET /api/v1" error, it indicates that the server might not be binding to the specified port or is not running correctly, regardless of what the server logs show.

Restart Checkmate Docker services:

• Restart the Checkmate server container.

• Restart the Checkmate client container.

• Restart the MongoDB client container.

Clear browser cache and cookies

• Clear your browser's cache and cookies.

General FAQ

Q: I installed Checkmate, but I don't see the registration page to sign up for the first time

A: Normally the application will automatically redirect you to the register page if you have not yet created an account.

If the client cannot reach the server then the server client does not know that you do not have an account yet and won't redirect you.

If you are not redirected to /register and cannot see the sign-up page automatically, this means that the client cannot reach the server. Make sure the Checkmate Docker server is running.

Q: I get "Uncaught (in promise) Error" and monitors added but keep pending

If you get an error similar to "Uncaught (in promise) Error: A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received at v (VM7845 vendor.js:142:18472)", remove your "AdBlocker Ultimate". This adblocker is known to not work with Checkmate.

Q: I enabled local Docker volume and set up two Docker container monitors. The state remains at "pending".

You can use a to expose the socket to Checkmate.

Q: I can't access Checkmate outside the host machine

Problem: I'm running Checkmate on a machine (like with IP 192.168.1.2). I can access it via and it works well. But if I want to access it outside this machine, it doesn't work. I open , and it loads some part of the UI, but fails after.

Solution: You need to specify the IP address of your host machine (192.168.1.2 in our case) in docker-compose.yml, do the client part know, where the server is. You can do it by updating the address in this variable:

Q: Is it possible to increase the login token expiry?

Yes, this is configurable via the env file. TOKEN_TTL is the parameter you would want to set.

Q: How do I add ntfy.sh support?

1. Create a topic on your NTFY server.

2. (Only if you require authentication for your NTFY Server):

   Generate an authentication token via the command below on the NTFY server:

   echo -n "Basic echo -n 'username:password' | base64" | base64 | tr -d '=' (Change username:password in your actual NTFY username and password)

3. Add the link to the webhook in CheckMate.

Q: Checkmate server fails to interact with docker.sock. How do I fix it?

If the Checkmate server fails to interact with docker.sock when mounting the volume, follow those troubleshooting steps:

1. Verify Docker group membership:

• Check the Docker group: Determine the Group ID (GID) of the Docker group.

2. Configure Checkmate server user

Method 1 (Direct docker.sock mount): Ensure the user field in your Checkmate server configuration includes the GID of the Docker group.

• Compose YAML:

  • user: nobody:281

or

• Compose YAML:

  • user: nobody:<Docker Group Name>

Important: The User ID (UID) is typically not critical for this scenario.

• For docker CLI you would add new container variables:

  • PUID: UID

  • PGID: Docker GID

Another method is that, if using a Docker socket proxy, ensure the DOCKER_HOST environment variable is correctly set:

• Compose YAML

  • environment:

  • - DOCKER_HOST=tcp://docker-socket-proxy:2375

1. Check Docker socket permissions

Verify read-only access: If mounting `docker.sock` directly, ensure the read_only: true option is set in your Checkmate server configuration. This prevents accidental modifications to the Docker daemon.

Restart Checkmate server: After making any configuration changes, restart the Checkmate server to apply the updates.

4. Test Docker interaction:

Once the server is restarted, set up a new docker container monitoring with your container ID within your Checkmate server. Monitor the server logs for any error messages related to Docker communication.

Installing Checkmate is a fairly straightforward process on a Linux machine. There are many installation options though, which may be overwhelming. Here is a breakdown of all the options:

1. If you'd like to deploy on a Linux server, we suggest you go with Combined FE/BE Docker option. This keeps backend and frontend on one Docker and MongoDB on the other Docker service.

2. If you want to deploy on a Linux server, but want to keep frontend and backend on two separate Docker images, then go with Separate FE/BE option. Note that this installation method may not be as straightforward as the first oe.

To collect hardware information from your servers, you need Capture, a server monitoring agent for Checkmate. Capture receives requests from Checkmate (server), and sends the necessary infrastructure status data, eg CPU, RAM, disk or network packet information.

When Capture runs on the remote server, it starts collecting hardware information from the host machine and exposes it through a RESTful API. The agent is designed to be lightweight and easy to use.

Capture is available for Linux, Windows, Mac, Raspberry PI or any device that can run Go.

Features

Follow these steps to create a new monitor.

Checks to perform

Select the type of checks you want to configure:

• Website monitoring

  • Uses HTTP(s) protocols to monitor your website or API endpoint.

  • Options: HTTPS or HTTP.

• Ping monitoring

  • Confirms the server's availability using ping responses.

• Docker monitoring: Monitors whether a Docker container is running.

  • Ensure your Docker daemon is exposed.

  • Docker IDs must be the full 64 char Docker ID. You can run docker inpsect <short_id> to get the full container ID.

• Port monitoring

  • Checks whether your port is open or not.

• Game server monitoring

  • Checks whether your game server is up or not (supports hundreds of game server types)

General settings

This section changes depending on the type of the monitor you want use, but in general you'd need to enter URL, display name, or port.

Notifications

This is where you add a notification to a monitor. In order to attach a notification to a monitor, first you need to go to the Monitor section on the left (Sidebar), add a notification there, and its name will popup here.

Ignore TLS/SSL error

If there is a TLS/SSL error when connecting to a service, you can tell Checkmate to continue checking the service's uptime.

Advanced settings

Check frequency

Set the frequency of checks. The default is 1 minute, but you can adjust this based on your requirements.

Response validations

When creating or configuring an uptime monitor in Checkmate, you have access to advanced settings that allow for precise response validation. This guide explains how to use these features effectively.

Match method

The Match method determines how Checkmate compares your expected value with the actual response data.

The Expected Value field defines what you want to check for in the response body content.

JSON path

The JSON Path field allows you to extract and validate specific data from JSON responses using JMESPath syntax.

When to Use JSON Path

• When testing APIs that return JSON responses

• When you need to validate nested data within a complex response

• When you only care about a specific value in a larger JSON object

Example Scenarios

Scenario 1: Checking Website Availability

Scenario 2: Verifying User Data in API Response

Scenario 3: Checking for Error Messages

When monitoring websites, it’s essential to understand how Checkmate evaluates responses. This is how response checking works:

1. Response Body Only: The Expected Value field checks the response body content only, not HTTP metadata like status codes. Checkmate does not provide a direct way to check the HTTP status code through Expected Value.

2. For Website Monitoring

   1. Focus on checking for content that should be present on your website:

Reliable website monitoring examples