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 (Windows)

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 server/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.

---

Quickstart for developers (Linux and MacOS)

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:

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: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
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	Deprecated		API Key for PageSpeed requests	This API key can be set up in Settings.
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 here.

---

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.