Checkmate CLI

[gorkem-bwl]

This issue is a part of the $5000 grant funding program.

A command line interface which can manage Checkmate directly from terminal.

• Programming language: Go
• https://github.com/spf13/cobra Golang Module as a CLI framework
• Required: Search/evaluate CLI authentication mechanisms, eg docker, npm

Features:

• Monitor management
• User management
• Incident management

[mertssmnoglu]

Checkmate CLI Proposals

I want to discuss and verify the work load.
cc: @gorkem-bwl, @ajhollid

I have the demo for two concepts.

Proposal 1: Internal CLI

NodeJS or Shell Scripts

Internal means that the CLI is part of the Checkmate codebase and is not a separate executable.(All commands must be executed at TARGET_PATH)

Usage

./cli [options] [command] [command options]  

./cli monitors [add, remove, list]
./cli users [add, remove, list]
./cli incidents [list]
./cli pagespeed [list]
./cli backup [mongo, redis] | shell: using system binaries / node: using packed db drivers
./cli restore [mongo, redis] | shell: using system binaries / node: using packed db drivers
./cli upgrade |

Technical Details

1. The CLI is implemented using the nodejs or shell script.
2. The CLI is located in the cli or directory on the Checkmate repository.
3. Commands must be used inside the cli directory.
4. Distribution: Already distributed with checkmate codebase

Impact

System administrators will be able to use ./cli upgrade command to easy upgrade the Checkmate's version. This command must be executed on the target server.

• Need some versioning features on the Client and Server side
• Only works if the Checkmate and the Databases(MongoDB and Redis) are installed system wide. To use commands in the terminal, admins should use ssh connection or something.

Database connections must be made with Mongo and Redis clients. If we don't want to make cli dependent to system wide installed mongodb and redis databases we must pack the client tools with the cli.

---

Proposal 2: External CLI

Golang

External means that the CLI is a separate executable that is not part of the Checkmate codebase.

Usage

checkmate [options] [command] [command options]

checkmate monitors [add, remove, list]
checkmate users [add, remove, list]
checkmate incidents [list]
checkmate pagespeed [list]
checkmate backup [mongo, redis] | using packed db drivers and remote connections
checkmate restore [mongo, redis] | using packed db drivers and remote connections

Technical Details

1. The CLI is implemented using the Go Cobra framework.
2. Admins can add downloaded binary to their system path and use it everywhere.
3. Authentication/connection mechanism will made with Checkmate's API. More portable.
4. Distribution: Brew, Go Packages, GitHub Releases, Linux Package(deb, rpm)

Impact

Administrators can manage their Checkmate instances on their PCs terminal. They just need to authenticate with an admin/superuser level API token.

[gorkem-bwl]

Hi Mert. My take is this CLI will mostly be used for bulk monitor adding, adding/removing users, doing a backup and restoring.

I am good with both options in fact. The second option is more friendly, but takes additional step to install. First option is straightforward but requires logging in in case it's needed (which, by nature, won't be quite often). Hence, there are advantages and disadvantages to both approaches.

I'd say that for the sake of simplicity, we can assume that MongoDB and Redis are on the same server, and that 1st option can be used initially to see how it goes.

@ajhollid what do you think?

[mertssmnoglu]

Checkmate CLI

Manage your Checkmate monitoring setup with the Checkmate CLI.

Overview

The Checkmate CLI is a command-line interface for system administrators to manage monitoring setup, users, data, and configurations of the Checkmate monitoring tool. The CLI will be a standalone tool that can be installed on the same machine with the Checkmate setup.

Checkmate is an open-source, self-hosted tool designed to track and monitor server hardware, uptime, response times, and incidents in real-time with beautiful visualizations.

Checkmate CLI Core Requirements

🟢 Runtime Configuration

Users will be able to configure the Checkmate CLI runtime with a configuration file. The configuration file will be in YAML format.

Linux: ~/.checkmate/config.yaml

Windows: ~\.checkmate\config.yaml

Please don't forget to look at action-list item 3 for the configuration file location.

base_url: "URL_TO_CHECKMATE_API" # Only base url without the trailing slash or path.
api_key: "YOUR_CHECKMATE_API_KEY" # The api key for the Checkmate API.
# Please don't forget to look at action-list item 2 for the token system.

settings:
  # CLI settings will be here, if any.  
  ...

🟡 Backup and Restore

Users will be able to use Checkmate CLI to backup and restore their monitoring setup.

! These commands will be available only for the Docker Compose setup.
! Users should install the Checkmate CLI on the same machine with the Checkmate setup.

Docker Compose files will be used to determine the backup and restore process. Backup command will extract the volumes to a tarball. This backup tarboll will be restored to the specified volume with the restore command.

• 🟢 checkmate backup [volume-name] [backup-directory]
  • volume-name: The name of the volume to backup. (This will be the volume name in the docker-compose file)
• 🟡 checkmate restore [volume-name] [backup-file]
  • volume-name: The name of the volume to restore. (This will be the volume name in the docker-compose file)
  • backup-file: The backup file to restore the volume from.

---

🟡 Bulk Monitor Adding

Users will be able to add multiple monitors at once with a single command.

Bulk monitor adding will be done by importing a JSON file containing the monitor definitions. The CLI will parse the JSON file and add the monitors to the Checkmate API.

• checkmate monitor bulk-import [file]
  • file: The file containing the monitor definitions.

Example CSV File

MonitorName,Address,Type
Google,https://google.com,HTTP(S)
Facebook,https://facebook.com,HTTP(S)
Twitter,https://twitter.com,HTTP(S)
LinkedIn,https://www.linkedin.com,HTTP(S)
Mert Sismanoglu,https://mertsismanoglu.com/demo,HTTP(S)

• Issue/PR: Bulk Monitor Adding

Depends on Checkmate API. It will be a wrapper around the Checkmate API. Users should export their authentication token to the environment variable CHECKMATE_TOKEN or fill the token in the configuration file.

🟡 Add/Remove Users

Admins will be able to add and remove users from the Checkmate CLI.

• checkmate users add [options]

  • options: The user options to add.
  • ! Read password from the terminal(os.Stdin) without echoing it.

• checkmate users remove username

  • username: The username to remove.

Depends on Checkmate API. It will be a wrapper around the Checkmate API. Admins should export their authentication token to the environment variable CHECKMATE_TOKEN or fill the token in the configuration file.

Action List

1. Add volume name specification to all of the docker-compose files. See Docker Compose Volumes
2. Decide on the Checkmate CLI Token system. Tokens should be custom signed JWT tokens with roles. Users should see their tokens in the Checkmate UI.
3. The configuration file should be in the user's home directory. Is it in a seperate folder or directly in the home directory?
4. Should we create a separate repository for the CLI? Will it be hard to maintain the Client, Server and CLI at the same time?

[mertssmnoglu]

I solved data backup and restore mechanisms with managing the Docker Volumes. While the "External CLI" can be executed from anywhere, backup and restore operations must be performed on the device where Checkmate is installed. Which is the host machine.

Actions

1. I am about to create a PR to update the compose files.
2. I remember we could sign a custom tokens, please tell me if I'm wrong.
3. I'm using ~/.checkmate/config.yml in my machine, it works, but we can easily change it.
4. I have a local repository, where can I push my changes?

[ajhollid]

Hey @mertssmnoglu,

I think you're right, a separate repository for the CLI tool makes more sense, especially since it is an external CLI.

As for tokens, we'll have to work that into the backend at some point, it shouldn't take too long to implement. We're planning an overhaul of the auth system anyways so that can be added to the TODO.

@gorkem-bwl can you set up an empty repository for this CLI tool? I think we're good to go ahead and add it to our documentation too.

Looking really cool!

[gorkem-bwl]

Sure, what is your suggestion for the repo name @mertssmnoglu ? Either checkmate-cli or you can choose a cooler name if you want.

[mertssmnoglu]

Sure, what is your suggestion for the repo name @mertssmnoglu ? Either checkmate-cli or you can choose a cooler name if you want.

I don't have any cool options in my mind, It could be checkmate-cli for now. @gorkem-bwl

[ajhollid]

How about CheckmateMate?

It's a helper (mate) for Checkmate, and it's a bit silly which makes me smile 😂.

Plus we can then one day have a plugin for CheckmateMate called CheckmateMateMate

It's turtles all the way down!

checkmate-cli is fine for a serious name though if that's the direction 🤔

[mertssmnoglu]

How about CheckmateMate?

It's a helper (mate) for Checkmate, and it's a bit silly which makes me smile 😂.

Plus we can then one day have a plugin for CheckmateMate called CheckmateMateMate

It's turtles all the way down!

checkmate-cli is fine for a serious name though if that's the direction 🤔

It will hard to remember and type in the terminal.

checkmate backup

checkmate is not recognized

checkmatemate backup

ohh finally