Installing Checkmate

Installing Checkmate is a fairly straightforward process on a Linux machine. There are many installation options though, which may be overwhelming. Here is a breakdown of all the options:

  1. If you'd like to deploy on a Linux server, we suggest you go with Combined FE/BE Docker option. This keeps backend and frontend on one Docker, and Redis and MongoDB on two other Docker services.

  2. If you want to deploy on a Linux server, but want to keep frontend and backend on two separate Docker images, then go with Separate FE/BE option. Note that this installation method may not be as straightforward as the first oe.

  3. (For developers), there is also a 3rd option for developers who want to work on the application, e.g extend and test it.

Option 1: Combined FE/BE Docker installation (easy method)

In this installation, the React front-end is served from the API server. There is no Client image as it is not required. Note that this is still a React SPA and is served to your browser where it runs.

Requests to the API server are made from your browser. If that is on a different machine than your API server, then you must configure the API URL appropriately.

To get started:

Your application will spin up at http://localhost:52345

Configuration remains the same as the regular server, with two additional frontend ENV vars:

  • UPTIME_APP_API_BASE_URL: http://localhost:52345/api/v1

  • UPTIME_APP_CLIENT_HOST: http://localhost

NOTE: If you’d like to host your Checkmate instance somewhere other than the machine your browser is running on, you will need to update these vars. As an example, if you were hosting at 143.110.231.94, use the following variables: 

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

Where,

  • UPTIME_APP_API_BASE_URL points the client to the server

  • UPTIME_APP_CLIENT_HOST is used for building some links that point to the client

  • CLIENT_HOST is the origin that the API server will approve requests from

If you are upgrading from a previous deployment:

  • As long as you mount the same directories to the MongoDB image you'll retain your data.

  • The Mongo part of the application remains unchanged.

  • You can always back up your data directory as well before migration.

Option 2: Separate FE/BE Docker installation

In this installation, the React front-end is served by an Nginx Docker image (named Client) and is independent of the API server.

Note that if you want to configure Nginx, you will have to mount a volume to the Client image to override the default config:

2.1 Running on a local machine

  1. Download our Docker compose file

  2. Run docker compose up to start the application

  3. Now the application is running at http://localhost

Optional config:

  • If you want to monitor Docker containers, uncomment this line in docker-compose.yaml:

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

This gives the app access to your docker daemon via unix socket, please be aware of what you are doing.

2.2 Running on a remote server

  1. Download our Docker compose file

  2. Edit the UPTIME_APP_API_BASE_URL variable in the docker-compose file to point to your remote server.

  3. Run docker compose up to start the application

  4. Now the application is running at http://<remote_server_ip>

Optional config:

  • If you want to monitor Docker containers, uncomment this line in docker-compose.yaml:

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

This gives the app access to your Docker daemon via unix socket, please be aware of what you are doing.

Deploying on Windows

This is like option 2, but for Windows machines.

Step 1: Fork and clone the repository

  1. Fork the repository: Go to the Checkmate GitHub repository and fork it to your account.

  2. Clone the repository: Open your terminal or command prompt and run:

    git clone https://github.com/your-username/checkmate.git
cd checkmate

Step 2: Set up the backend (server)

  1. Navigate to the server directory:

  2. cd server

  3. Install dependencies:

  4. npm install

  5. Create a .env File: Add a .env file in the server directory to hold your server secrets.

Step 3: Build and Run MongoDB and Redis Docker Images

  1. Navigate to the main directory:

  2. cd ..

  3. Build Docker Images:

    docker build -f ./docker/dev/mongoDB.Dockerfile -t uptime_database_mongo .
docker build -f ./docker/dev/redis.Dockerfile -t uptime_redis .

  4. Navigate to the docker/dev directory:

  5. cd docker/dev

  6. Run Docker containers:

    docker run -d -p 6379:6379 -v $PWD/redis/data:/data --name uptime_redis uptime_redis
docker run -d -p 27017:27017 -v $PWD/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo

Step 4: Start the backend server

  1. Navigate to the server directory:

  2. cd into server.

  3. Run the development server:

  4. npm run dev

  5. Your backend should now be up and running.

Step 5: Set up the frontend (client)

  1. Navigate to the client directory:

  2. cd client

  3. Install dependencies:

  4. npm install

  5. Create a .env File: Add a .env file in the client directory to hold your client secrets.

  6. Run the client (a.k.a frontend):

  7. npm run dev

  8. Your frontend should now be up and running.

Deploying on ARM machines

If you would like to install Checkmate on Raspberry PI 4, Raspberry PI 5 or MacOS, use this link to download the Docker compose file. Then run the usual docker compose up command to start instances.

Your application will spin up at http://localhost:52345

Configuration environment variables is the same as what you'd use in Option 1 section above.

Developer installation (Linux and MacOS)

When you’re working on the app locally, it’s painful to rebuild and reload Docker images every time you tweak the client or server. Instead, run those services directly on your host machine—this gives you instant feedback and lets you use hot-reload without waiting for image builds.

At the same time, we still include Redis and MongoDB as Docker containers. Those services rarely change, so keeping them in containers simplifies setup and avoids cluttering your host environment.

Make sure you change the directory to the specified directories, as paths in commands are relative.

Cloning and initial setup

This application consists of a frontend (client) and a backend (server) in a single repository. Start by cloning the repo, as it contains everything you need, except the Capture agent if you plan to use the Infrastructure Monitoring feature.

Setting up Docker images

This application requires a MongoDB instance and a Redis instance. If you want, you can use our Docker images. Otherwise, you can provide your instances as well.

  1. From your checkmate directory you created above, cd into server/docker/dev.

  2. Run build_images.sh

  3. Run docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis

  4. Run docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_database_mongo uptime_database_mongo

The default Checkmate Redis Docker image does not include authentication. If your setup requires authentication (e.g, especially if you expose the server on a public IP), you need to configure it manually.

Server set up

The server requires some configuration to run.

  1. From your checkmate directory, CD into the server directory.

  2. Run npm install.

  3. In the server directory, create a .env file to hold your configuration. This is where you'll add your environment variables.

  4. Add the required environmental variables.

  5. Start the server by running npm run dev.

Client set up

The client also requires some configuration in order to run.

  1. From your checkmate directory, CD into the client directory.

  2. Run npm install.

  3. In the client directory, create a .env file to hold your configuration. This is where you'll add your environment variables.

  4. Add the required environmental variables.

  5. Start the client by running npm run dev

Access the application

  1. The client is running at localhost:5173 (unless you changed the default port).

  2. The server is running at localhost:52345 (unless you changed the default port).

Client env vars

  1. Change directory to the Client directory

  2. Install all dependencies by running npm install

  3. Add a .env file to the Client directory with the following options:

ENV Variable Name
Required/Optional
Type
Description
Accepted Values

VITE_APP_API_BASE_URL

Required

string

Base URL of server

{host}/api/v1

VITE_APP_LOG_LEVEL

Optional

string

Log level

"none"|"error" | "warn" |

VITE_APP_DEMO

Optional

boolean

Demo server or not

true|false |

Sample ENV file:

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

Server env vars

  1. Change the directory to the Server directory

  2. Install all dependencies by running npm install

  3. Add a .env file to the Server directory with the following options:

Environment variables

Configure the server with the following environmental variables. Note that those variables need to be set in .env files if you are running the local development server, or in the Docker compose file if you use docker compose.

ENV Variable Name
Required/Optional
Type
Description
Accepted Values

CLIENT_HOST

Required

string

Frontend host

JWT_SECRET

Required

string

JWT secret

DB_CONNECTION_STRING

Required

string

Specifies URL for MongoDB database

ORIGIN

Required

string

Origin where requests to server originate from, for CORS purposes

localhost

LOG_LEVEL

Optional

string

Debug level

Can be one of debug, info, warn, error

DB_TYPE

Deprecated

string

Specify DB to use

MongoDB | FakeDB

REFRESH_TOKEN_SECRET

Deprecated

string

Refresh JWT secret

PORT

Deprecated

integer

Specifies port for server

LOGIN_PAGE_URL

Deprecated

string

Login URL to be used in emailing service

REDIS_HOST

Deprecated

string

Host address for Redis database

REDIS_PORT

Deprecated

integer

Port for Redis database

TOKEN_TTL

Optional

string

Time for token to live

In vercel/ms format https://github.com/vercel/ms

PAGESPEED_API_KEY

Deprecated

API Key for PageSpeed requests

This API key can be set up in Settings.

SYSTEM_EMAIL_HOST

Deprecated

string

Host to send system emails from

SYSTEM_EMAIL_PORT

Deprecated

number

Port for system email host

SYSTEM_EMAIL_ADDRESS

Deprecated

string

System email address

SYSTEM_EMAIL_PASSWORD

Deprecated

string

System email password

Sample, minimum env file is as follows:

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

Note that for the Pagespeed feature to work, you need a free Google Pagespeed API key from this link.

API documentation

Our API documentation follows the OpenAPI spec. You can see the documentation on your local development server at http://localhost:{port}/api-docs . You can also view the documentation on our demo server here. Just a note that the API documentation is still in the works. Let us know in our Discord channel if you have any questions about the latest status.

Error handling

Errors are returned in a standard format:

{"success": false, "msg": "No token provided"}

Errors are handled by error handling middleware and should be thrown with the following parameters

Name
Type
Default
Notes

status

integer

500

Standard HTTP codes

message

string

"Something went wrong"

An error message

service

string

"Unknown Service"

Name of service that threw the error

Example:

const myRoute = async(req, res, next) => {
  try{
    const result = myRiskyOperationHere();
  }
  catch(error){
    error.status = 404
    error.message = "Resource not found"
    error.service = service name
    next(error)
    return;
  }
}

Errors should not be handled at the controller level and should be left to the middleware to handle.

PreviousWelcome to Checkmate 2.1NextUsing Checkmate

Last updated

Was this helpful?