Checkmate: Self-Hosted Uptime & Infrastructure Monitoring

CheckMate Project Overview

Checkmate is an open-source, self-hosted monitoring tool designed to track the availability, performance, and health of your websites, services, and infrastructure in real time.

It combines a React/Vite/MUI frontend with a Node.js/Express backend, using MongoDB and Redis for storage and BullMQ for distributed job scheduling.

Why Checkmate can be important for you

Maintain full control of your monitoring data and privacy.
Scale to thousands of monitors with minimal resource usage.
Customize dashboards and alerts to fit your team’s workflow.

CheckMate Features

🔓 AGPL-3.0 license
🚀 Website & HTTP(S) uptime monitoring
⚡️ Page-speed and performance checks
💻 Infrastructure metrics (CPU, memory, disk, temperature via optional Capture agent)
📦 Docker container health checks
📶 Ping & latency tracking
🔒 SSL certificate expiry alerts
🔌 TCP/port availability monitoring
🚨 Incidents dashboard & scheduled maintenance windows
📧 Email notifications with MJML & Handlebars templates
🗓️ Bulk import of monitors via CSV
🌐 Internationalized UI & public status pages

CheckMate Key Concepts & Algorithms

Uptime Calculation: Aggregates check results over time to compute availability percentages.
Distributed Job Scheduling: BullMQ queues checks across workers with retry/backoff logic.
Health Checks:
- HTTP(S) via Axios
- ICMP ping via ping module
- TCP probes via Node’s net module
- Docker container checks via dockerode
- SSL expiration checks via ssl-checker
Email Templating: MJML → HTML conversion with Handlebars for dynamic content.
Internationalization: JSON locale files and dynamic language middleware.

Module Descriptions

client/
- src/Pages, Routes, Components, Features, and Hooks organize the React code by feature.
- Redux Toolkit store with redux-persist for state management.
- i18next integration for translations.
- Vite build configuration, ESLint, and Prettier for code quality.
server/
- controllers/ handle REST endpoints: auth, monitors, checks, maintenance, status pages, notifications, diagnostics.
- routes/ map controllers under /api/v1/....
- service/ implements core services:
  - NetworkService (HTTP, ping, Docker, TCP)
  - JobQueue (BullMQ)
  - EmailService (MJML + Handlebars + MailerSend/Nodemailer)
  - SettingsService, StatusService, NotificationService, RedisService, TranslationService.
- middleware/ for JWT verification, error handling, consistent responses, language selection, and role/ownership checks.
- db/ connects to MongoDB via Mongoose and defines models.
- templates/ contains MJML email templates for alerts and activations.
- openapi.json + Swagger UI for interactive API documentation.

Dependencies

Backend:
Node.js, Express, Mongoose, ioredis, BullMQ, Dockerode, Joi, JSON Web Token, MailerSend/Nodemailer, MJML, Winston, Swagger-UI, compression, helmet, cors.
Frontend:
React 18, Vite, MUI, Redux Toolkit, React Router v6, Recharts, i18next, html2canvas, PapaParse.
Dev Tools:
ESLint, Prettier, Mocha, Chai, Sinon, c8, nodemon.

Configuration & Environment

Server (server.env):

PORT=52345
MONGO_URL=mongodb://localhost:27017/checkmate
REDIS_URL=redis://localhost:6379
JWT_SECRET=your_jwt_secret
MAILERSEND_API_KEY=your_mailersend_key
UPTIME_APP_CLIENT_HOST=http://localhost

Client (env vars or .env.production):

VITE_APP_API_BASE_URL=http://localhost:52345/api/v1
VITE_APP_CLIENT_HOST=http://localhost
VITE_APP_LOG_LEVEL=info

Static Code Analysis

Languages: JavaScript (ESM), JSX
Structure: client/, server/, docker/ folders
Linting & Formatting: ESLint with custom configs, Prettier
Testing: Mocha + Chai + Sinon, coverage via c8
Validation: Joi schemas for all API inputs

Deployment

For easy and quick deployment, lets see how to get CheckMate monitoring up and running with its docker-compose.

Docker Compose for CheckMate

cd docker/dev
docker-compose up -d

This will spin up:

client on port 80
server on port 52345
redis and mongodb with healthchecks and data volumes

Production & One-Click

Use docker/prod/docker-compose.yaml or deploy via Coolify/Elestio for one-click setup.
Ensure server.env and NGINX configs under docker/nginx/ are updated with your domains.

services:
  client:
    image: ghcr.io/bluewave-labs/checkmate:frontend-demo
    restart: always
    environment:
      UPTIME_APP_API_BASE_URL: "https://checkmate-demo.bluewavelabs.ca/api/v1"
      UPTIME_APP_CLIENT_HOST: "https://checkmate-demo.bluewavelabs.ca"
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - server
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d/:ro
      - ./certbot/www:/var/www/certbot/:ro
      - ./certbot/conf/:/etc/nginx/ssl/:ro

  certbot:
    image: certbot/certbot:latest
    restart: always
    volumes:
      - ./certbot/www/:/var/www/certbot/:rw
      - ./certbot/conf/:/etc/letsencrypt/:rw
  server:
    image: ghcr.io/bluewave-labs/checkmate:backend-demo
    restart: always
    ports:
      - "52345:52345"
    env_file:
      - server.env
    depends_on:
      - redis
      - mongodb
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
  redis:
    image: ghcr.io/bluewave-labs/checkmate:redis-demo
    restart: always
    volumes:
      - ./redis/data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 5s
  mongodb:
    image: ghcr.io/bluewave-labs/checkmate:mongo-demo
    restart: always
    command: ["mongod", "--quiet", "--replSet", "rs0", "--bind_ip_all"]
    volumes:
      - ./mongo/data:/data/db
      - ./mongo/init/init.js:/docker-entrypoint-initdb.d/init.js
    env_file:
      - mongo.env
    healthcheck:
      test: echo "try { rs.status() } catch (err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'mongodb:27017'}]}) }" | mongosh --port 27017 --quiet
      interval: 5s
      timeout: 30s
      start_period: 0s
      retries: 30

YOu will need a mongo.env:

# MongoDB environment variables for Checkmate (production)
# Uncomment and set values if authentication or a custom database is required
# MONGO_INITDB_ROOT_USERNAME=admin
# MONGO_INITDB_ROOT_PASSWORD=change_me_to_secure_string
# MONGO_INITDB_DATABASE=checkmate

And a server.env

# Server environment variables for Checkmate (production)
PORT=52345
CLIENT_HOST=https://your.domain.com
DB_CONNECTION_STRING=mongodb://mongodb:27017/checkmate
REDIS_URL=redis://redis:6379
JWT_SECRET=change_me_to_secure_random_string
SYSTEM_EMAIL_HOST=smtp.example.com
SYSTEM_EMAIL_PORT=587
SYSTEM_EMAIL_USER=username
[email protected]
TOKEN_TTL=1h
CALLBACK_URL=https://your.domain.com/callback
PAGESPEED_API_KEY=your_pagespeed_api_key
UPROCK_API_KEY=your_uprock_api_key
LOG_LEVEL=info

Manual Setup

Install Node.js (≥18), MongoDB, Redis.
Clone the repo and install dependencies:

cd server && npm install
cd ../client && npm install

Configure environment variables as above.
Build and start both services:

cd client && npm run build
cd ../server && npm run dev

Wrapping Up

#docker system prune -a #or clean its unused container space

Latest Releases

The Checkmate project seems to be actively under development and just got the 2.1 version released.

In case that you read this very into the future - at the time of writing, I got it working with the following commit:

git log -1 --pretty=format:'%h %s (%ci)'
#f7beb4db Merge pull request #2287 from bluewave-labs/hotfix/uptime-perentage (2025-05-15 14:21:30 -0700)

v2.1 (2025-05-13)

Removed version from settings API
Documentation updates and hotfix merges

v2.0.2 (2025-01-23)

UI/UX fixes (maintenance colors, incident filters)
Dependency upgrades and performance patches

v2.0.1 (2024-12-23)

Email template improvements, memory leak patches

v2.0 (2024-12-04)

Major UI overhaul with MUI
i18n support & customizable status pages
Refactored job queue and registry

v1.1.0 (2024-10-11)

Bulk import monitors & scheduled maintenance
Initial email notifications & announcements

v1.0 (2024-09-23)

First public release: core uptime, ping, port, SSL checks, dashboard & alerts

CheckMate Project Overview#

CheckMate Features#

CheckMate Key Concepts & Algorithms#

Module Descriptions#

Dependencies#

Configuration & Environment#

Static Code Analysis#

Deployment#

Docker Compose for CheckMate#

Production & One-Click#

Manual Setup#

Wrapping Up#

Latest Releases#