Checkmate on Ubuntu 24.04 on Azure User Guide

Overview

Checkmate (by BlueWave Labs) is an open source uptime, infrastructure and incident monitoring platform. It continuously checks the availability and response time of your websites, HTTP APIs, TCP ports, ping targets, DNS records and more, and presents their status, uptime percentage and response time history in a clean React dashboard backed by a REST API. You add a monitor for each endpoint you care about, set the check interval, and Checkmate records every result so you can see current status at a glance and be alerted the moment something goes down.

The cloudimg image installs Checkmate 3.9.2 from the pinned upstream release under /opt/checkmate, builds the React client and the Node.js server, runs the server as the dedicated checkmate system user bound to loopback 127.0.0.1:52345, stores all monitoring data in a local MongoDB 8.0, and fronts the dashboard with nginx on port 80. Checkmate's check queue is MongoDB backed, so there is no separate Redis to run.

Secure by default: the image ships with no default credential. On the first boot of every VM a unique JWT signing secret and a unique MongoDB password are generated at random, MongoDB is bound to loopback with authorization enabled, and a single administrator account is registered for you with a random per instance password written to a root only file. Self registration closes after that first account, so the dashboard is never left open.

What is included:

• Checkmate 3.9.2 (AGPL-3.0) under /opt/checkmate (React client + Node.js server, built from source)
• Local MongoDB 8.0 Community, bound to 127.0.0.1, authorization enabled, WiredTiger cache capped for the VM size
• checkmate.service running as checkmate, bound to 127.0.0.1:52345
• nginx reverse proxy on port 80, serving the static React client and proxying /api to the server, WebSocket aware, ready for TLS
• checkmate-firstboot.service that rotates the per VM secrets and registers your administrator on first boot
• Node.js 22 runtime
• Ubuntu 24.04 LTS base, fully patched, unattended security upgrades enabled
• 24/7 cloudimg support, 24h response SLA

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet with a subnet. Recommended VM size: Standard_B2s (4 GB RAM is comfortable for the dashboard, the server and a local MongoDB).

Step 1: Deploy from the Azure Portal

Search the Marketplace for Checkmate on Ubuntu 24.04, choose your VM size, and attach an NSG that allows TCP 22 (SSH) from your management network and TCP 80 / 443 (the dashboard) from the networks that need it. Front port 80 with TLS in production (see the HTTPS section below). Only nginx listens externally; the Node server and MongoDB are bound to loopback.

Step 2: Deploy from the Azure CLI

RG="checkmate-prod"; LOCATION="eastus"; VM_NAME="checkmate-01"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/checkmate-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az network vnet create -g "$RG" --name checkmate-vnet --address-prefix 10.90.0.0/16 --subnet-name checkmate-subnet --subnet-prefix 10.90.1.0/24
az network nsg create -g "$RG" --name checkmate-nsg
az network nsg rule create -g "$RG" --nsg-name checkmate-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp
az network nsg rule create -g "$RG" --nsg-name checkmate-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 443 --access Allow --protocol Tcp
az vm create -g "$RG" --name "$VM_NAME" --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name checkmate-vnet --subnet checkmate-subnet --nsg checkmate-nsg --public-ip-sku Standard

Step 3: Connect via SSH

ssh azureuser@<vm-ip>

Step 4: Verify the services are running

MongoDB and the Checkmate Node server listen on loopback; nginx fronts the dashboard on port 80 and proxies the API.

sudo systemctl is-active mongod checkmate nginx
sudo ss -tln | grep -E ':80 |127.0.0.1:52345 |127.0.0.1:27017 '
curl -s -o /dev/null -w 'GET /api/v1/health -> HTTP %{http_code}\n' http://127.0.0.1/api/v1/health

All three services report active, MongoDB is bound to 127.0.0.1:27017, the Node server to 127.0.0.1:52345, nginx to :80, and the health endpoint returns HTTP 200 through nginx.

Step 5: Retrieve your administrator credentials

The image ships with no default credential. On first boot Checkmate generated a per VM JWT signing secret and MongoDB password, and registered a single administrator with a random password stored in a root only file. Read it over SSH:

sudo grep -E 'bindIp|authorization' /etc/mongod.conf
sudo stat -c '%n perms=%a owner=%U:%G' /root/checkmate-credentials.txt
curl -s http://127.0.0.1/api/v1/auth/users/superadmin; echo
sudo cat /root/checkmate-credentials.txt

MongoDB is bound to loopback with authorization enabled, the credentials file is 600 root:root, exactly one superadmin exists (so self registration is closed), and the file gives you the URL, admin email and admin password for this VM:

CHECKMATE_URL=http://<vm-ip>/
CHECKMATE_ADMIN_EMAIL=admin@checkmate.local
CHECKMATE_ADMIN_PASSWORD=<unique-per-vm-password>

Step 6: Sign in

Open http://<vm-ip>/ in your browser. Enter the email and password from /root/checkmate-credentials.txt and click Login.

Step 7: The uptime dashboard

After signing in you land on the Uptime dashboard. It summarises how many monitors are up, down, paused or initializing, and lists each monitor with its live status, response time and uptime percentage.

Step 8: Add your first monitor

Click Create. Choose the monitor Type (HTTP(S), Ping, Docker, Port, Game, gRPC, WebSocket or DNS), enter the URL or address to watch, give it a display name, set the check interval, and save.

Step 9: Watch it live

Checkmate starts checking immediately. Open a monitor to see how long it has been active, its last check and last response time, the certificate expiry for HTTPS targets, and charts of uptime and response time over your chosen window.

Step 10: The runtime stack

node -v
nginx -v
mongod --version | head -1
node -p "require('/opt/checkmate/client/package.json').version"

Node.js 22 runs the server, nginx fronts it, MongoDB 8.0 stores the data, and the pinned Checkmate release is 3.9.2.

Step 11: Data and persistence

All monitoring data lives in the local MongoDB under /var/lib/mongodb, captured into the image and carried onto every instance.

sudo du -sh /var/lib/mongodb
systemctl is-enabled checkmate-firstboot.service checkmate.service
apt-mark showhold

The database directory is present, the services are enabled for the next boot, and there are no held packages, so the OS security baseline is intact.

Step 12: Enable HTTPS

nginx already fronts Checkmate on port 80 and is ready for TLS. Point a DNS record at your VM, then obtain a certificate with certbot:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> --agree-tos -m <your-email> --redirect

certbot installs the certificate, rewrites the nginx server block for TLS and sets up automatic renewal. When you serve the dashboard on a custom domain, set CLIENT_HOST in /etc/checkmate/checkmate.env to your https:// URL and run sudo systemctl restart checkmate so the server accepts requests from that origin.

Managing the service

sudo systemctl status checkmate
sudo systemctl restart checkmate
sudo journalctl -u checkmate -f

The Node server logs to the journal; nginx logs are under /var/log/nginx/. Add more users from Settings in the dashboard once you are signed in as the administrator. Back up the instance by snapshotting the OS disk, or with mongodump against the local database while the service is stopped.

Support

cloudimg provides 24/7 support for this image via email and live chat: deployment, nginx TLS termination, upgrades, notification integrations and performance tuning. Email support@cloudimg.co.uk.

This is a repackaged open source software product with additional charges for cloudimg support services. Checkmate is licensed under the GNU AGPL-3.0 and is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.