Checkmate Deployment and Usage Guide

1. Prerequisites

Before installing Checkmate, ensure you have the following:

Runtime & Databases:

Node.js (v18 or higher) - JavaScript runtime for the TypeScript application
MongoDB (v5.0+) - Primary database for storing monitors, checks, and incidents
Redis (v6.0+) - Used for caching and queue management
Docker (optional) - For containerized deployment

Optional Components:

Capture Agent - For hardware monitoring (CPU, RAM, disk, temperature)
- Available for Linux, Windows, Mac, Raspberry Pi
- Go runtime required on target servers

Tools:

Git - For cloning the repository
npm or yarn - Package manager for Node.js
Docker Compose (for Docker deployment)

Accounts (Optional):

Discord/Slack webhook URLs for notifications
Email SMTP credentials for email alerts
Custom CA certificates for internal HTTPS monitoring

2. Installation

Clone the Repository

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

Install Dependencies

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install

Quick Deployment Options

For rapid deployment, consider these managed solutions:

Elestio - One-click deployment
K8s Helm Chart - Kubernetes deployment
Pikapods - Simple container hosting
Sive Host - South Africa-based hosting

3. Configuration

Environment Variables

Create a .env file in the server directory:

# Server Configuration
NODE_ENV=production
PORT=3001
HOST=0.0.0.0
BASE_URL=http://localhost:3001
CLIENT_URL=http://localhost:3000

# Database Configuration
MONGODB_URI=mongodb://localhost:27017/checkmate
REDIS_URL=redis://localhost:6379

# Security
JWT_SECRET=your-secure-jwt-secret-here
ENCRYPTION_KEY=your-32-character-encryption-key

# Email (for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=Checkmate <noreply@checkmate.so>

# Optional: External Services
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

Custom CA Trust (for Internal HTTPS)

If monitoring internal HTTPS endpoints with private certificates:

Place your CA certificate in server/certs/ca.pem
Update Docker configuration (see docs/custom-ca-trust.md):

# In docker-compose.yml
services:
  checkmate:
    volumes:
      - ./certs:/app/certs:ro
    environment:
      - NODE_EXTRA_CA_CERTS=/app/certs/ca.pem

Capture Agent Configuration

For hardware monitoring, install and configure Capture:

# On each server to monitor
# Download and install Capture agent
# Configure connection to Checkmate instance
CHECKMATE_URL=http://your-checkmate-instance:3001
AGENT_TOKEN=your-agent-authentication-token

4. Build & Run

Development Mode

# Start MongoDB and Redis (if not running)
# Using Docker:
docker run -d -p 27017:27017 --name checkmate-mongo mongo:latest
docker run -d -p 6379:6379 --name checkmate-redis redis:latest

# Start the development servers
# Terminal 1 - Backend
cd server
npm run dev

# Terminal 2 - Frontend
cd client
npm run dev

Access the application at http://localhost:3000

Production Build

# Build the frontend
cd client
npm run build

# Build and run the backend
cd ../server
npm run build
npm start

Using Docker Compose

# From project root
docker-compose up -d

This starts:

Checkmate application on port 3000
MongoDB on port 27017
Redis on port 6379

5. Deployment

Recommended Platforms

Based on the tech stack (TypeScript, Node.js, MongoDB, Redis):

For Small to Medium Deployments:

DigitalOcean Droplet (2GB RAM minimum)
AWS Lightsail or EC2
Linode or Vultr VPS
Raspberry Pi 4/5 (for home/lab use)

For Large Scale/Enterprise:

Kubernetes (using provided Helm charts)
AWS ECS/EKS
Google Cloud Run with Cloud SQL/Memorystore
Azure Container Instances with Cosmos DB/Cache

Docker Deployment

# Pull the latest image
docker pull ghcr.io/bluewave-labs/checkmate:latest

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  -e MONGODB_URI=mongodb://host.docker.internal:27017/checkmate \
  -e REDIS_URL=redis://host.docker.internal:6379 \
  -e JWT_SECRET=your-secret \
  --name checkmate \
  ghcr.io/bluewave-labs/checkmate:latest

Kubernetes Deployment

# Using Helm
helm repo add checkmate https://bluewave-labs.github.io/checkmate
helm install checkmate checkmate/checkmate \
  --set mongodb.enabled=true \
  --set redis.enabled=true

Performance Considerations

Memory usage: ~50MB for Node.js + 400MB for MongoDB + 15MB for Redis (for 300+ monitors)
Monitor interval: Adjust based on your needs (default is 60 seconds)
Database indexes: Automatically created for optimal query performance

6. Troubleshooting

Common Issues

1. MongoDB Connection Failed

# Check if MongoDB is running
mongosh --eval "db.runCommand({ping:1})"

# Verify connection string
echo $MONGODB_URI
# Should be: mongodb://localhost:27017/checkmate

2. Redis Connection Issues

# Test Redis connection
redis-cli ping
# Should return: PONG

# Check Redis logs
docker logs checkmate-redis

3. High Memory Usage

Checkmate is optimized for low memory usage

If experiencing high memory:

# Monitor memory usage
docker stats checkmate

# Adjust Node.js memory limit
NODE_OPTIONS="--max-old-space-size=512"

4. Monitors Not Updating

# Check the queue service
# View logs for network service errors
docker logs checkmate --tail 100 | grep -i "error\|timeout"

# Verify monitor configuration
# Ensure URLs are accessible from Checkmate's network

5. SSL/TLS Certificate Errors For internal HTTPS monitoring:

# Ensure custom CA is properly mounted
docker exec checkmate ls -la /app/certs/

# Test certificate validation
docker exec checkmate node -e "require('tls').createSecureContext({ca: require('fs').readFileSync('/app/certs/ca.pem')})"

6. Capture Agent Not Connecting

# Check agent logs
journalctl -u capture-agent --no-pager -n 50

# Verify network connectivity
curl -v http://your-checkmate-instance:3001/api/health

# Check firewall rules
sudo ufw status

Getting Help

Discord: Join https://discord.gg/NAb6H3UTjK for real-time support
GitHub Issues: Report bugs at https://github.com/bluewave-labs/checkmate/issues
Documentation: Visit https://docs.checkmate.so for detailed guides

Logs and Debugging

# View application logs
docker logs checkmate -f

# Enable debug logging
DEBUG=checkmate:* npm start

# Check specific service logs
docker logs checkmate 2>&1 | grep -i "NetworkService\|MonitorService"

Note: Checkmate has been stress-tested with 1000+ active monitors. If you encounter performance issues, check your database indexes and network latency between services.

How to Deploy & Use Checkmate