Installing Checkmate

Overview

Checkmate offers several installation options depending on your needs:

• Docker (recommended) — fastest way to get running
• ARM / Raspberry Pi — dedicated image for ARM devices
• Kubernetes / Helm — for orchestrated deployments
• Developer setup — for contributing or customizing

Option 1: Docker (combined)

The simplest approach serves the React frontend from the API server, with MongoDB in a separate container.

Local deployment

1. Download the Docker Compose file from the repository's docker/dist-mono/ directory
2. Start the services:

docker compose up

3. Access Checkmate at http://localhost:52345

Remote server deployment

When hosting on a remote machine, update three environment variables in the compose file. Replace 143.110.231.94 with your server's IP:

UPTIME_APP_API_BASE_URL=http://143.110.231.94:52345/api/v1
UPTIME_APP_CLIENT_HOST=http://143.110.231.94
CLIENT_HOST=http://143.110.231.94

Option 2: Docker (separate frontend/backend)

This option uses Nginx to serve the React frontend independently from the API server.

Local deployment

1. Download the Docker Compose file from the docker/dist/ directory
2. Start the services:

docker compose up

3. Access Checkmate at http://localhost

Optional: Docker container monitoring

To monitor Docker containers, uncomment this volume mount in the compose file:

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

Remote deployment

1. Download the Docker Compose file
2. Update UPTIME_APP_API_BASE_URL to reference your remote server
3. Run docker compose up
4. Access at http://<your-server-ip>

Option 3: ARM / Raspberry Pi

For ARM devices (Raspberry Pi 4/5, Apple Silicon Macs), use the dedicated ARM compose file from docker/dist-arm/:

docker compose up

The application runs at http://localhost:52345 with the same environment variable configuration as Option 1.

Option 4: 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 5: 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)

Option 6: 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.