Checkmate: Open-Source Server Monitoring with Uptime Alerts

Checkmate is an open-source monitoring tool designed for self-hosting. It allows you to monitor servers and websites by tracking uptime, response times, and hardware health. The system triggers alerts immediately when a service fails, providing details on what is down, the duration of the outage, and any performance regressions.

What Checkmate Tracks

• Fully open-source codebase for deployment on your own infrastructure.
• Comprehensive website monitoring.
• Hardware health checks, including memory, disk, CPU, and temperature.
• Connectivity testing via Ping monitoring.
• Oversight for Docker containers.
• Detailed page speed statistics.
• Historical event logs.
• Publicly accessible status pages.
• Notifications delivered via email, Telegram, Slack, Discord, and webhooks.
• Support for scheduled maintenance windows.

For example, a typical monitor like "BU BlueWave Uptime" might track a site every minute. If it has been active for five days with a last check performed 23 seconds ago, the dashboard would display a response time of 1,826 ms. Over a 24-hour period consisting of 921 checks, you can observe whether the average response time remains steady and confirm if uptime reached the target of 99.7%, with specific event logs available for any disruptions.

Installing Checkmate

Setting up Checkmate on Linux is a straightforward process with several available methods depending on your requirements.

Installation Options

For standard Linux servers, the combined Frontend/Backend (FE/BE) Docker option is the most efficient choice. This method bundles the frontend and backend into a single Docker container, while Redis and MongoDB run in two auxiliary containers.

If you prefer to keep these components isolated, you can choose the split FE/BE option, though it requires more manual configuration.

A third route is available for developers, which is the best choice for those looking to test the application or extend its functionality.

Installation Steps

Option 1: Combined FE/BE Docker Install (The Simplest Method)

In this configuration, the API server serves the React frontend directly. You do not need a separate client image, though the React Single Page Application (SPA) still executes within the user's browser.

The browser communicates with the API server. If the browser and the server are on different machines, you must ensure the API URL is configured correctly.

1. Download the Docker Compose file.
2. Execute docker compose up.
3. Access the application at http://localhost:52345.

The configuration follows standard server setups, but two specific frontend environment variables are critical:

• UPTIME_APP_API_BASE_URL: http://localhost:52345/api/v1
• UPTIME_APP_CLIENT_HOST: http://localhost

If you are hosting Checkmate on a remote server rather than localhost, update these variables accordingly. For instance, if your server IP is 143.110.231.94, use:

• UPTIME_APP_API_BASE_URL=http://143.110.231.94:52345/api/v1
• UPTIME_APP_CLIENT_HOST=http://143.110.231.94
• CLIENT_HOST=http://143.110.231.94

UPTIME_APP_API_BASE_URL directs the client to the server, UPTIME_APP_CLIENT_HOST generates return links to the client, and CLIENT_HOST informs the API which origins are permitted.

When upgrading from a previous deployment, simply mount the same volume to the MongoDB image to keep your data intact. It is recommended to back up your data directory before proceeding with an update.

Option 2: Split FE/BE Docker Install

In this setup, the React frontend runs within an Nginx Docker image labeled client, separate from the API server.

To customize the Nginx configuration, mount a volume over the default settings:

client:
  image: ghcr.io/bluewave-1abs/checkmate:frontend-dist
  restart: always
  ports:
    - "80:80"
    - "443:443"
  depends_on:
    - server
  volumes:
    - ./nginx/conf.d:/etc/nginx/conf.d/:ro

2.1 Running on Your Local Machine

1. Download the Docker Compose file.
2. Execute docker compose up.
3. Access the application at http://localhost.

Optional: To monitor Docker containers, uncomment the following lines in your docker-compose.yaml file:

# volumes:
#  - /var/run/docker.sock:/var/run/docker.sock:ro

This provides the application access to the Docker daemon via a Unix socket. Note the security implications of granting this access.

2.2 Running on a Remote Server

1. Download the Docker Compose file.
2. Edit the UPTIME_APP_API_BASE_URL in the compose file to point to your remote server's IP.
3. Execute docker compose up.
4. Access the application at http://<remote_server_ip>.

The optional configuration for Docker monitoring remains the same as the local setup.

Deploying on Windows

The Windows deployment mirrors Option 2 but is tailored for a local environment.

1. Fork and clone the repository.

   • Fork the Checkmate GitHub repository to your own account.
   • Open a terminal and execute:

     git clone https://github.com/your-username/checkmate.git
     cd checkmate
     

2. Configure the backend (server).

   • Navigate to the server folder: cd server
   • Install dependencies: npm install
   • Create a .env file within the server folder to store your environment variables.

3. Build and launch the MongoDB and Redis Docker images.

   • Return to the main directory: cd ..
   • Build the images:

     docker build -f ./docker/dev/mongoDB.Dockerfile -t uptime_database_mongo .
     docker build -f ./docker/dev/redis.Dockerfile -t uptime_redis .
     

   • Navigate to the dev directory: cd docker/dev
   • Launch the containers:

     docker run -d -p 6379:6379 -v $PWD/redis/data:/data --name uptime_redis uptime_redis
     docker run -d -p 27017:27017 -v $PWD/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo
     

4. Start the backend server.

   • cd server
   • Execute npm run dev.

5. Configure the frontend (client).

   • Navigate to the client folder: cd client
   • Install dependencies: npm install
   • Create a .env file in the client folder for frontend secrets.
   • Execute npm run dev.

Deploying on ARM Machines

If you are using a Raspberry Pi 4, Pi 5, or an Apple Silicon Mac, download the ARM-specific Docker Compose file from the provided link and run docker compose up.

The application will be available at http://localhost:52345. The environment variables follow the same logic as those in Option 1.

Developer Install (Linux and macOS)

To avoid rebuilding Docker images after every minor code change, you can run the client and server directly on your host machine. This enables hot reloading for instant feedback. In this scenario, Redis and MongoDB still run as Docker containers to keep them isolated from your host environment.

Ensure you are in the correct directory, as command paths are relative.

1. Clone and Initial Setup Clone the repository containing both the frontend (client) and backend (server). If you intend to monitor infrastructure, you will also need the Capture agent.

2. Configure Docker Images You will need MongoDB and Redis. You can use the provided Docker images or your own instances. From the checkmate folder, navigate to server/docker/dev. Run build_images.sh, then execute:

   docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis
   docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo
   

   The default Redis image does not include authentication. You should add this manually if you expose the server to a public IP.

3. Server Setup From the checkmate root, enter the server directory. Run npm install. Create a .env file in server with the necessary variables. Start the server with npm run dev.

4. Client Setup From the checkmate root, enter the client directory. Run npm install. Create a .env file in client. Start the client with npm run dev.

5. Access the Application The client typically runs at localhost:5173 and the server at localhost:52345 unless ports were modified.

API Documentation

Checkmate’s API documentation follows the OpenAPI specification. You can find these documents at http://localhost:{port}/api-docs on your local development server. A demo server also hosts a version of the documentation for reference.