Self-host Checkmate on a managed VPS: uptime monitoring on your own server

To self-host Checkmate on a managed VPS is to keep the watch on your websites and servers on a machine of your own, which our teams keep up to date and monitor day and night. Checkmate is a free, open source monitoring application under the AGPL-3.0 license: uptime, response times, incidents, alerts and status pages. This guide follows its official Docker image at version v4.0.0, and we ran every command on a Simafri VPS before writing it: installation with Docker Compose, HTTPS, the first account, monitors and alerts, backups and updates.

Simon Vasconcelos Lee By Published on 17 November 202612 minute read

All guides

In short

  1. The AGPL-3.0 license lets you run Checkmate for yourself, your team or your clients with no license to buy; if you modify it and let others use it over the network, you share your changes.
  2. Install it with Docker Compose: the all-in-one image ghcr.io/bluewave-labs/checkmate and MongoDB 8.0, with the port published on 127.0.0.1 behind an HTTPS reverse proxy.
  3. Set JWT_SECRET, ENCRYPTION_KEY and your public address in CLIENT_HOST, and add NODE_ENV=production, which the reference file leaves out.
  4. The first person to register becomes the Superadmin: create your account right after the first start, then everyone else joins by invitation.
  5. Back up the MongoDB database with mongodump and keep your .env file, then update by changing the image tag: migrations run on their own at startup.

What Checkmate does

Checkmate checks your services at regular intervals, records each answer and its response time, and alerts you when something stops responding. Its developer, BlueWave Labs, describes it as a self-hosted tool to track server hardware, uptime, response times and incidents in real time.

What the AGPL-3.0 license allows

Checkmate is published under the GNU Affero General Public License, version 3 (AGPL-3.0). You can use it free of charge, for yourself, your company or your clients, copy it and modify it.

Its particular clause concerns network use: if you modify Checkmate and let other people use your modified version over the network, you must offer them its source code. Running the official image unmodified, as in this guide, creates no such obligation. The software is provided without warranty.

The resources to plan for

The documentation sets a modest floor: any Linux VPS with 1 GB of RAM or more. It adds that MongoDB uses about 400 MB on an instance that checks more than 300 servers every minute.

Server size therefore depends on the number of monitors, their interval and the history you keep. On a managed VPS, tell us about your usage and we will recommend the right size.

Installing with Docker Compose

Since version 3.10, Checkmate ships as a single image, ghcr.io/bluewave-labs/checkmate, which serves both the interface and the API. MongoDB runs beside it, in its own container. On a server with Docker Engine and its Compose plugin, installed from Docker’s repository for Ubuntu, create a folder such as /opt/checkmate and put this compose.yaml in it, based on the project’s reference file:

compose.yaml
services:
  checkmate:
    image: ghcr.io/bluewave-labs/checkmate:v4.0.0
    restart: always
    ports:
      - "127.0.0.1:52345:52345"
    environment:
      - DB_CONNECTION_STRING=mongodb://mongodb:27017/uptime_db
      - CLIENT_HOST=https://status.example.com
      - JWT_SECRET=${JWT_SECRET:?set JWT_SECRET in .env}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY:?set ENCRYPTION_KEY in .env}
      - NODE_ENV=production
    stop_grace_period: 60s
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:52346/livez',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))"]
      interval: 15s
      timeout: 3s
      start_period: 60s
      start_interval: 2s
      retries: 3
    depends_on:
      mongodb:
        condition: service_healthy

  mongodb:
    image: mongo:8.0
    restart: always
    command: ["mongod", "--quiet", "--bind_ip_all"]
    volumes:
      - mongo-data:/data/db
    healthcheck:
      test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/27017"]
      interval: 5s
      timeout: 30s
      start_period: 0s
      start_interval: 1s
      retries: 30

volumes:
  mongo-data:

The two secrets go in a .env file next to it, which Docker Compose reads on its own. Create it readable by root only, then start the stack:

Terminal, in /opt/checkmate
umask 077
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -base64 32)" > .env
umask 022
docker compose up -d
docker compose ps

The first start runs the database migrations; on our test VPS, the application reported healthy in under ten seconds. To check that it responds:

Terminal
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:52345/
curl -s http://127.0.0.1:52345/api/v1/auth/users/superadmin

The first command answers 200. The second answers "data":false as long as no account exists, and true once the Superadmin is created.

The first account, roles and invitations

Checkmate has no default account. The first person to register becomes the Superadmin, so create yours right after the first start, before you open the address to the public. An SSH tunnel brings the server’s port 52345 to your computer, at http://localhost:52345; add -p and the SSH port shown in your client area.

Terminal, on your computer
ssh -L 52345:127.0.0.1:52345 root@status.example.com
  1. Open http://localhost:52345: Checkmate shows its registration page.
  2. Enter your first name, last name, email address and a password of at least 8 characters, with an uppercase letter, a lowercase letter, a number and a special character.
  3. Register: you land on the dashboard, signed in as Superadmin.

From then on, public registration is closed: on our test VPS, every new visitor was sent to the login page, and the registration address led there too. Other people join by invitation, from the Team section of the account settings, with the User or Admin role. The invitation goes out by email, so it needs the SMTP settings below, and its link expires after one hour.

RoleWhat it can do
UserSee every monitor, the dashboard, checks, incidents, status pages and settings, without changing anything
AdminEverything a User can, plus monitors, notification channels, incidents, maintenance windows, status pages, invitations and global settings, SMTP included
SuperadminEverything an Admin can, plus creating accounts directly, editing another user, changing a role or a password

Since v4.0.0, tags, status pages and proxies are Admin actions: a User who could manage them before loses that access after the update.

HTTPS: the reverse proxy

The container serves Checkmate over HTTP, on port 52345. HTTPS is handled by a reverse proxy in front of it: the documentation names Caddy, Traefik and nginx. We tested Caddy, installed from its official Debian and Ubuntu repository: it obtains the Let’s Encrypt certificate itself, renews it, and forwards the Host header and the X-Forwarded-* headers by default.

/etc/caddy/Caddyfile
status.example.com {
	reverse_proxy 127.0.0.1:52345
}
Terminal
sudo systemctl reload caddy

Your first monitor and its alerts

  1. In “Uptime”, click “Create monitor” and choose HTTP/HTTPS.
  2. Enter the address to check, a name you will recognize in an alert, and an interval: the documentation recommends one to five minutes for a critical service.
  3. Save: Checkmate runs the first check at once. On our test VPS, the monitor was up a minute later.

Email: the SMTP settings

Email alerts and invitations go through a server-wide SMTP connection, set under “Settings”, “Email” tab: host, port, user, password and sender address, then “Save” and “Test”. On a Simafri VPS, use an authenticated SMTP server on port 587 or 465: your domain’s mail service, or a sending service. Then create an email notification with the addresses to alert, and attach it to your monitors.

Slack, Discord, Teams, Telegram and the other channels are created the same way, under “Notifications”, each with its webhook address or token, and each with a “Test” button.

Heartbeat monitors for your scheduled jobs

A heartbeat monitor watches a job that runs on its own, such as a nightly backup. Generate the team’s ping key under “Settings”, “Monitoring” tab (it is shown only once), create a Heartbeat monitor with a slug and an alert window, then call its ping URL at the end of the job:

crontab
0 3 * * * /usr/local/bin/backup.sh && curl -fsS -m 10 --retry 3 "https://status.example.com/api/v1/heartbeat/<ping-key>/nightly-backup"

Adding /fail, or the job’s exit code, to the URL marks the monitor down at once, without waiting for the window to pass.

Status pages

Under “Status pages”, an Admin publishes a page that lists chosen monitors and their uptime, for your clients or your team. Since v4.0.0, every status page has a time zone, UTC by default.

Backups

Everything lives in two places: the MongoDB database, in the mongo-data volume, and your .env file. Keep the latter safe: ENCRYPTION_KEY is needed to read the secrets stored in the database, and JWT_SECRET keeps your users signed in. The MongoDB image includes mongodump:

Terminal, in /opt/checkmate
docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db > checkmate-$(date +%F).archive.gz
cp .env env-$(date +%F).bak

Schedule this copy and send it off the server; a heartbeat monitor can tell you if it ever stops running. Stored on the disk, the archives are also included in the server’s nightly backups.

Restoring

On the same or a new installation, with the same .env, stop the application, load the archive, then start it again:

Terminal, in /opt/checkmate
docker compose stop checkmate
docker compose exec -T mongodb mongorestore --archive --gzip --drop < checkmate-2026-11-17.archive.gz
docker compose start checkmate

We tested the whole cycle on our VPS: backup, the database actually deleted, restore. The monitor and the account came back, and signing in worked again at once.

Checkmate v4.0.0 also offers encrypted cloud backups through Checkmate Connect, an optional service, free during its beta, which needs ENCRYPTION_KEY and a Superadmin to enroll the installation. The copies above work without it.

Updates

Read the release notes, take a backup, change the image tag in the compose.yaml, then pull the new image and recreate the container. The database migrations run on their own at startup:

Terminal, in /opt/checkmate
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration

Telemetry

Checkmate sends one anonymous report a day: an installation ID, the version, how it was installed and the number of monitors of each type, never your URLs or results. It says so in its log at startup. To turn it off, add TELEMETRY_ENABLED=false to the environment of the checkmate service, then run docker compose up -d.

Who does what on a managed VPS

Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; Checkmate remains your software, with its monitors and your settings.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callYour own monitors, alerts and status pages in Checkmate
CheckmateProactive monitoring: errors, slowdowns, database and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Users and alertsThe server that carries them, monitored and backed upAccounts, roles, invitations and notification channels
BackupsEvery night, encrypted and kept off the machine; restores includedCheckmate’s own database exports, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe timing of the switch

If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.

Checkmate, on a server run for you

With a Simafri Managed VPS, our teams keep your Checkmate instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.

Explore Managed VPS

Frequently asked questions

Is Checkmate free?

Yes. Checkmate is under the AGPL-3.0 license: you can run it for yourself, your team or your clients with no license to buy. If you modify it and let others use it over the network, you share your changes. What remains is the cost of the server that runs it.

How do I install Checkmate with Docker Compose?

Use the reference compose.yaml: the ghcr.io/bluewave-labs/checkmate image and MongoDB 8.0. Put JWT_SECRET and ENCRYPTION_KEY in a .env file, set CLIENT_HOST to your https address and NODE_ENV to production, publish port 52345 on 127.0.0.1, run docker compose up -d, and put an HTTPS reverse proxy in front.

What is the default Checkmate login?

There is none. The first person to register on a new instance becomes the Superadmin. Create your account right after the first start, through an SSH tunnel; after that, visitors are sent to the login page and new users join by invitation.

How much memory does Checkmate need?

The documentation asks for a Linux VPS with 1 GB of RAM or more. On our test VPS, a fresh installation used about 300 MB for Checkmate and 280 MB for MongoDB. Disk grows with the number of monitors, their interval and the history you keep, 90 days by default.

How do I send Checkmate alerts by email?

Set the SMTP connection under Settings, Email tab: host, port 587 or 465, user, password and sender, then Save and Test. Create an email notification with the addresses to alert and attach it to your monitors. Invitations use the same settings.

How do I back up Checkmate?

Export the MongoDB database with docker compose exec -T mongodb mongodump --archive --gzip --db uptime_db, and keep a copy of your .env file, whose ENCRYPTION_KEY is needed to read the stored secrets. Restore with mongorestore --archive --gzip --drop, the application stopped.

How do I update Checkmate?

Read the release notes and take a backup, change the image tag in compose.yaml, then run docker compose pull and docker compose up -d. The database migrations run on their own at startup.

Does a managed VPS cover Checkmate?

A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.

Contact us