Installing Checkmate

Overview

Checkmate offers several installation options depending on your needs:

• Docker (recommended) — fastest way to get running
• Kubernetes / Helm — for orchestrated deployments
• Developer setup — for contributing or customizing

Option 1: Docker

Checkmate ships as a single all-in-one application image, ghcr.io/bluewave-labs/checkmate. It serves the React frontend from the API server, so only two services are needed: the application and MongoDB.

The image is multi-arch (linux/amd64 and linux/arm64), so the same tag works on x86 servers, Apple Silicon, and ARM devices such as a Raspberry Pi 4/5.

Local deployment

Download the reference Compose file and start it:

curl -O https://raw.githubusercontent.com/bluewave-labs/checkmate/master/docker/docker-compose.yaml
JWT_SECRET="$(openssl rand -hex 32)" docker compose up -d

Then open http://localhost:52345.

Remote server deployment

When the app is reached at another origin — a domain or a LAN IP rather than localhost — set CLIENT_HOST to that URL:

CLIENT_HOST=https://checkmate.example.com \
JWT_SECRET="$(openssl rand -hex 32)" \
docker compose up -d

For TLS, put a reverse proxy (Caddy, Traefik, nginx) in front of port 52345.

Configuration

The application is configured entirely through environment variables:

The web client needs no configuration by default — it calls the API on the same origin it was served from. For setups where that does not apply, the server renders overrides into the client at runtime:

Monitoring Docker containers

To monitor containers on the host, mount the Docker socket into the Checkmate service:

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

Socket access is root-equivalent on that host, so enable it deliberately.

Building the image yourself

docker build -f docker/Dockerfile -t checkmate .

Option 2: Third-party hosting

You can also deploy Checkmate using these hosting providers:

• Elestio — managed open-source hosting
• PikaPods — one-click container hosting
• Sive Host — hosting provider (South Africa)
• RepoCloud
• Coolify
• Cloudzy

Option 3: Kubernetes with Helm

Prerequisites

• A running Kubernetes cluster
• Helm CLI installed and configured
• kubectl configured to access your cluster

Deploy

git clone https://github.com/bluewave-labs/checkmate.git
cd checkmate/charts/helm/checkmate

Edit values.yaml to configure:

• client.ingress.host and server.ingress.host with your domain names
• server.protocol (http or https)
• Secrets under the secrets section (JWT_SECRET, email credentials, API keys)

Then deploy:

helm install checkmate ./charts/helm/checkmate

Verify the deployment:

kubectl get pods
kubectl get svc

Enabling TLS with cert-manager

If you have cert-manager installed, enable automatic TLS:

client:
  protocol: https
  ingress:
    enabled: true
    host: checkmate.example.com
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    tls:
      enabled: true
      secretName: checkmate-client-tls

server:
  protocol: https
  ingress:
    enabled: true
    host: checkmate.example.com
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
    tls:
      enabled: true
      secretName: checkmate-server-tls

Verify certificates:

kubectl get certificates
kubectl describe certificate checkmate-client-tls

Option 4: Developer installation

For contributing or customizing Checkmate with hot-reload support.

Clone and start MongoDB

You don't need to build any Docker images for development. The only container required is MongoDB:

git clone https://github.com/bluewave-labs/checkmate
cd checkmate
docker run -d -p 27017:27017 \
  -v uptime_mongo_data:/data/db \
  --name uptime_database_mongo mongo:8.0

Start the server

cd checkmate/server
npm install

Create a .env file in the server directory (see environment variables below), then:

npm run dev

Server runs on localhost:52345 by default.

Start the client

cd checkmate/client
npm install

Create a .env file in the client directory (see environment variables below), then:

npm run dev

Frontend runs on localhost:5173 by default.

Environment variables

Client variables

Create .env in the client directory:

VITE_APP_API_BASE_URL="http://localhost:52345/api/v1"
VITE_APP_LOG_LEVEL="debug"

Server variables

Create .env in the server directory:

CLIENT_HOST="http://localhost:5173"
JWT_SECRET="my_secret"
DB_CONNECTION_STRING="mongodb://localhost:27017/uptime_db"
TOKEN_TTL="99d"
ORIGIN="localhost"

Using a custom CA

If you need to monitor internal HTTPS endpoints with certificates from private Certificate Authorities (like Smallstep), see the Custom CA Trust Guide for Docker configuration options.