Skip to main content

Setup Guide

Install Checkmate with a single command using our interactive installer:

curl -fsSL https://raw.githubusercontent.com/ds-horizon/checkmate/master/bootstrap.sh | bash

Or using wget:

wget -qO- https://raw.githubusercontent.com/ds-horizon/checkmate/master/bootstrap.sh | bash

The installer will:

  • ✅ Automatically check and install all prerequisites
  • ✅ Guide you through Google OAuth setup step-by-step
  • ✅ Configure everything for you
  • ✅ Get Checkmate running in minutes

That's it! Skip to Verify Installation after running the installer.

Manual Installation​

If you prefer manual installation or need more control, follow these steps.

Prerequisites​

Before starting, ensure you have the following installed:

RequirementVersionPurpose
Docker DesktopLatestContainer runtime
Node.js18.x+JavaScript runtime
Yarn1.xPackage manager
GitAnyVersion control
tip

New to Docker? Download it from docker.com and make sure it's running before proceeding.

Google OAuth Setup​

Checkmate uses Google OAuth for authentication. You'll need to create a Google Cloud OAuth application.

  1. Go to Google Cloud Console

    Visit Google Cloud Console and create or select a project.

  2. Enable Google+ API

    Navigate to APIs & Services → Library and enable the Google+ API.

  3. Create OAuth Credentials

    Go to APIs & Services → Credentials and click Create Credentials → OAuth 2.0 Client ID.

  4. Configure OAuth Consent Screen

    • Application name: Checkmate (or your preferred name)
    • User support email: Your email
    • Developer contact: Your email
    • Add test users if needed

  5. Configure OAuth Client

    • Application type: Web application
    • Name: Checkmate Local (or your preferred name)
    • Authorized JavaScript origins: 
      http://localhost:3000
    • Authorized redirect URIs: 
      http://localhost:3000/callback

  6. Save Credentials

    Copy the Client ID and Client Secret — you'll need these for the .env file.

caution

For production deployments, replace localhost:3000 with your actual domain (e.g., https://yourdomain.com and https://yourdomain.com/callback).

Installation​

Choose your preferred setup method:

Local Development Setup​

Run Checkmate locally with hot reload for development.

  1. Clone the repository

    git clone git@github.com:dream-sports-labs/checkmate.git
    cd checkmate

  2. Install dependencies

    yarn install

  3. Configure environment variables

    Copy .env.example to .env:

    cp .env.example .env

    Update the following required values:

    # Database
    DATABASE_URL=mysql://root:password@localhost:3306/checkmate

    # Google OAuth (from previous step)
    GOOGLE_CLIENT_ID=your_google_client_id_here
    GOOGLE_CLIENT_SECRET=your_google_client_secret_here

    # Session Secret (generate a random string)
    SESSION_SECRET=your_random_session_secret_here

  4. Start the database

    yarn docker:db:setup

    This creates a MySQL container and seeds initial data.

  5. Start the application

    yarn dev

    The app will be available at http://localhost:3000

tip

The dev server supports hot reload — changes to your code will automatically refresh the app.

Verify Installation​

After starting Checkmate, verify everything is working:

  1. Open the application

    Navigate to http://localhost:3000

  2. Sign in with Google

    Click "Sign in with Google" and authenticate with your Google account.

  3. Check the dashboard

    You should see the Projects page with seed data (sample projects, tests, and runs).

tip

First-time users are created automatically with the user role. To make yourself an admin, update the users table in the database.

Database Management​

Database Scripts​

CommandPurpose
yarn docker:db:setupCreate MySQL container and seed from seedData.sql
yarn dev:db:setupApply schema changes and seed from app/db/seed/
yarn db:initInsert seed data from app/db/seed/ folder
yarn db:studioOpen Drizzle Studio to explore the database
yarn db:generateGenerate SQL files from Drizzle schema

Drizzle Studio​

Explore and manage your database with a visual interface:

yarn db:studio

Opens at http://localhost:4983

Features:

  • Browse all tables and data
  • Edit records directly
  • Execute custom queries
  • View table relationships

Schema Migrations​

When modifying the database schema:

  1. Update schema files

    Edit files in app/db/schema/

  2. Generate migration

    yarn db:generate

  3. Apply migration

    yarn dev:db:setup

MCP Server Setup (Optional)​

Checkmate includes an MCP (Model Context Protocol) server that allows AI assistants like Claude to interact with your Checkmate instance programmatically.

Quick Setup​

  1. Create MCP Server Environment File

    Copy the example file:

    cd mcp-server
    cp .env.example .env

  2. Get Your API Token

    • Start Checkmate: yarn docker:setup
    • Login at http://localhost:3000
    • Navigate to User Settings → API Tokens
    • Click Generate Token
    • Copy the token

  3. Configure MCP Server

    Edit mcp-server/.env:

    CHECKMATE_API_BASE=http://localhost:3000
    CHECKMATE_API_TOKEN=your-api-token-here

  4. Start MCP Server

    The MCP server starts automatically with Docker:

    docker-compose up -d

    Or run locally:

    cd mcp-server
    npm install
    npm run build
    node build/index.js

Docker Deployment​

When using Docker, the MCP server is included in docker-compose.yml:

  • Service name: checkmate-mcp
  • Container name: checkmate-mcp
  • Auto-starts: Yes, with docker-compose up -d
  • Configuration: Uses mcp-server/.env

Verify MCP Server​

Check if the MCP server is running:

# Check Docker container
docker-compose ps checkmate-mcp

# View logs
docker-compose logs -f checkmate-mcp

Connect to AI Assistants​

See the MCP Server README for detailed instructions on connecting to:

  • Claude Desktop
  • Cursor IDE
  • Other MCP-compatible clients
tip

For Docker deployments, use http://checkmate-app:3000 as CHECKMATE_API_BASE in mcp-server/.env (internal Docker network).

Troubleshooting​

Cannot connect to database​

Problem: Application can't connect to MySQL.

Solution:

  • Verify Docker is running
  • Check container status: docker ps
  • Restart database: yarn docker:db:setup
  • Verify DATABASE_URL in .env matches your setup

Google OAuth errors​

Problem: OAuth login fails or redirects incorrectly.

Solution:

  • Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct
  • Check authorized origins and redirect URIs in GCP
  • Ensure you're using http://localhost:3000 (not https)
  • Clear browser cookies and try again

Port 3000 already in use​

Problem: Cannot start application — port is taken.

Solution:

# Find process using port 3000
lsof -ti:3000

# Kill the process
kill -9 $(lsof -ti:3000)

# Or change the port in vite.config.ts

Database seed fails​

Problem: Seed data not loading correctly.

Solution:

  • Drop and recreate database: yarn docker:db:setup
  • Check seedData.sql file exists
  • Verify MySQL container is healthy: docker logs checkmate-db

Permission denied errors​

Problem: Cannot access database or files.

Solution:

  • Check Docker has necessary permissions
  • On Linux, run: sudo usermod -aG docker $USER (then log out and back in)
  • Verify file permissions: ls -la

Environment Variables Reference​

Required Variables​

# Database Connection
DATABASE_URL=mysql://root:password@localhost:3306/checkmate

# Google OAuth Credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret

# Session Management
SESSION_SECRET=random_secret_string_min_32_chars

Optional Variables​

# Server Configuration
PORT=3000
NODE_ENV=development

# Logging
LOG_LEVEL=info
tip

Generate secure secrets: Use openssl rand -base64 32 to generate a strong SESSION_SECRET.

Next Steps​

User Guide

Learn how to use Checkmate

Get Started →

System Architecture

Understand how Checkmate works

Read Docs →

API Documentation

Integrate with Checkmate APIs

View APIs →

Contributing

Contribute to the project

View Guidelines →

Additional Resources​