Installing Checkmate

Quickstart for users (quick method)

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.

---

Quickstart for users (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.

---

Quickstart for developers

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). We recommend you create a directory, let's call it checkmate, to hold both the Client and the Server in one location.

1. CD into your checkmate directory

2. Clone the Client repository. We'll refer to this directory as client
3. Clone the Server repository. We'll refer to this directory as server

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 own instances.

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

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

3. 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 are exposing the server on a public IP), you'll need to configure it manually.

Server set up

The server requires some configuration in order 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:5000 (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:

Environment variables

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:5000/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
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

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.