Installing Checkmate
Quickstart for users (quick method)
Download our Docker compose file
Run
docker compose up
to start the applicationNow 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.
Quickstart for users (remote server)
Download our Docker compose file
Edit the
UPTIME_APP_API_BASE_URL
variable in the docker-compose file to point to your remote server.Run
docker compose up
to start the applicationNow 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.
Quickstart for developers (Windows)
Step 1: Fork and clone the repository
Fork the repository: Go to the Checkmate GitHub repository and fork it to your account.
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)
Navigate to the server directory:
cd server
Install dependencies:
npm install
Create a
.env
File: Add a.env
file in theserver
directory to hold your server secrets.
Step 3: Build and Run MongoDB and Redis Docker Images
Navigate to the main directory:
cd ..
Build Docker Images:
docker build -f ./docker/dev/mongoDB.Dockerfile -t uptime_database_mongo . docker build -f ./docker/dev/redis.Dockerfile -t uptime_redis .
Navigate to the docker/dev directory:
cd server/docker/dev
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
Navigate to the server directory:
cd into server.
Run the development server:
npm run dev
Your backend should now be up and running.
Step 5: Set up the frontend (client)
Navigate to the client directory:
cd client
Install dependencies:
npm install
Create a
.env
File: Add a.env
file in theclient
directory to hold your client secrets.Run the client (a.k.a frontend):
npm run dev
Your frontend should now be up and running.
Quickstart for developers (Linux and MacOS)
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.
From your
checkmate
directory you created above, cd intodocker/dev
.Run
build_images.sh
Run
docker run -d -p 6379:6379 -v $(pwd)/redis/data:/data --name uptime_redis uptime_redis
Run
docker run -d -p 27017:27017 -v $(pwd)/mongo/data:/data/db --name uptime_mongo uptime_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.
From your
checkmate
directory, CD into theserver
directory.Run
npm install
.In the
server
directory, create a.env
file to hold your configuration. This is where you'll add your environment variables.Add the required environmental variables.
Start the
server
by runningnpm run dev
.
Client set up
The client also requires some configuration in order to run.
From your
checkmate
directory, CD into theclient
directory.Run
npm install
.In the
client
directory, create a.env
file to hold your configuration. This is where you'll add your environment variables.Add the required environmental variables.
Start the
client
by runningnpm run dev
Access the application
The
client
is running atlocalhost:5173
(unless you changed the default port).The
server
is running atlocalhost:5000
(unless you changed the default port).
Client env vars
Change directory to the
Client
directoryInstall all dependencies by running
npm install
Add a
.env
file to theClient
directory with the following options:
Environment variables
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:5000/api/v1"
VITE_APP_LOG_LEVEL="debug"
Server env vars
Change the directory to the
Server
directoryInstall all dependencies by running
npm install
Add a
.env
file to theServer
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.
CLIENT_HOST
Required
string
Frontend Host
JWT_SECRET
Required
string
JWT secret
REFRESH_TOKEN_SECRET
Required
string
Refresh JWT secret
DB_TYPE
Optional
string
Specify DB to use
MongoDB | FakeDB
DB_CONNECTION_STRING
Required
string
Specifies URL for MongoDB Database
PORT
Optional
integer
Specifies Port for Server
LOGIN_PAGE_URL
Required
string
Login url to be used in emailing service
REDIS_HOST
Required
string
Host address for Redis database
REDIS_PORT
Required
integer
Port for Redis database
TOKEN_TTL
Optional
string
Time for token to live
In vercel/ms format https://github.com/vercel/ms
REFRESH_TOKEN_TTL
Optional
string
Time for refresh token to live
PAGESPEED_API_KEY
Optional
string
API Key for PageSpeed requests
SYSTEM_EMAIL_HOST
Required
string
Host to send System Emails From
SYSTEM_EMAIL_PORT
Required
number
Port for System Email Host
SYSTEM_EMAIL_ADDRESS
Required
string
System Email Address
SYSTEM_EMAIL_PASSWORD
Required
string
System Email Password
Sample env file
CLIENT_HOST="http://localhost:5173"
JWT_SECRET="my_secret"
DB_TYPE="MongoDB"
DB_CONNECTION_STRING="mongodb://localhost:27017/uptime_db"
REDIS_HOST="127.0.0.1"
REDIS_PORT=6379
TOKEN_TTL="99d"
PAGESPEED_API_KEY=<api_key>
SYSTEM_EMAIL_HOST="smtp.gmail.com"
SYSTEM_EMAIL_PORT=465
SYSTEM_EMAIL_ADDRESS=<email_address>
SYSTEM_EMAIL_PASSWORD=<password>
REFRESH_TOKEN_SECRET="my_refresh"
REFRESH_TOKEN_TTL="99d"
Note that for the Pagespeed feature to work, you need a free Google Pagespeed API key from this link.
API documentation
Our API is documented in accordance with 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 at https://uptime-demo.bluewavelabs.ca/api-docs
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
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.
Last updated
Was this helpful?