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.
By Simon Vasconcelos Lee
Published on 17 November 202612 minute read
ghcr.io/bluewave-labs/checkmate and MongoDB 8.0, with the port published on 127.0.0.1 behind an HTTPS reverse proxy.JWT_SECRET, ENCRYPTION_KEY and your public address in CLIENT_HOST, and add NODE_ENV=production, which the reference file leaves out.mongodump and keep your .env file, then update by changing the image tag: migrations run on their own at startup.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.
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 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.
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:
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:
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
127.0.0.1: the reference file publishes it without an address, and Docker then opens it on every address of the server. Published locally, it is reachable only through the reverse proxy.CLIENT_HOST is the address your users type, with https://. Checkmate uses it for cross-origin checks and for the links in its alerts and emails.NODE_ENV=production: the README asks for it on real deployments. Without it the application runs in development mode, which turns off the API rate limiter.ENCRYPTION_KEY is optional in the reference file. It encrypts the secrets Checkmate stores, and v4.0.0 requires it for TLS Docker monitors and for Checkmate Connect. Set it from the start: it is easier than adding it later.latest and pulls it at every start. A full version, here v4.0.0, lets you choose when each update happens.mongo-data holds all your data: monitors, checks, users and settings.The first start runs the database migrations; on our test VPS, the application reported healthy in under ten seconds. To check that it responds:
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.
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.
ssh -L 52345:127.0.0.1:52345 root@status.example.com
http://localhost:52345: Checkmate shows its registration page.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.
| Role | What it can do |
|---|---|
| User | See every monitor, the dashboard, checks, incidents, status pages and settings, without changing anything |
| Admin | Everything a User can, plus monitors, notification channels, incidents, maintenance windows, status pages, invitations and global settings, SMTP included |
| Superadmin | Everything 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.
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.
status.example.com {
reverse_proxy 127.0.0.1:52345
}
sudo systemctl reload caddy
CLIENT_HOST must hold the same https:// address as the proxy. After you change it, run docker compose up -d to recreate the container.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.
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:
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.
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.
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:
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.
On the same or a new installation, with the same .env, stop the application, load the archive, then start it again:
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.
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:
docker compose pull
docker compose up -d
docker compose logs checkmate | grep -i migration
mongodump and mongorestore. No new environment variable is required.checkmate-client, checkmate-backend and checkmate-mongo images, which are no longer updated. Switch to ghcr.io/bluewave-labs/checkmate and keep your MongoDB service and its volume; the UPTIME_APP_* variables are no longer read.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.
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.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Your own monitors, alerts and status pages in Checkmate |
| Checkmate | Proactive monitoring: errors, slowdowns, database and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Users and alerts | The server that carries them, monitored and backed up | Accounts, roles, invitations and notification channels |
| Backups | Every night, encrypted and kept off the machine; restores included | Checkmate’s own database exports, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.