Documentation

Get started

How it works?

Monitoror is a single file app written in Go which can be run on these platforms:

  • Linux x64 ARM
  • macOS
  • Windows x64

The app is divided into two parts: Core and UI.

Core is the server-side Monitoror HTTP API, configured by the environment variables or .env file.

UI is the client-side Monitoror loaded in browser, which is the wallboard itself.

Installation

Run the Core

On Linux or macOS, open you terminal, make monitoror executable, and run it:


chmod +x monitoror
./monitoror
      

On Windows, you can double click on the executable, or run it from PowerShell:


.\monitoror.exe
      

Access the UI

Once the Core is launched, loading animation must be visible here out of the box: http://localhost:8080

Note Change localhost to the Monitoror host IP if needed

Guides by platform

  • RaspberryPi — Auto-launch Monitoror and Chrome on boot

Configuration

There are two types of configuration:

  • Core configuration: credentials, timeouts, cache, ...
  • UI configuration: tiles and layout definition.

Core configuration

Core configuration is set with environment variables. Alternatively, .env file can also be used beside of monitoror binary.

MO_PORT number
Application port
Default: 8080

Most of tile type have specific Core configuration which are documented in the Tile definitions section.

See Advanced options section to see more about advanced Core configuration.

UI configuration

UI configuration must be stored in .json file.

There is two way to load the configuration file:

  • By URL:
    http://localhost:8080?configUrl=https://example.com/config.json
  • By path:
    http://localhost:8080?configPath=./config.json
UI query string parameters

Note One of configUrl or configPath is required to get the UI working.

configUrl string
URL to a .json file accessible via HTTP(S)
configPath string
A path to a .json file, relative to Monitoror installation folder
theme string
One of the following supported themes:
UI configuration file sample

The file is structured like this:


{
  "version": "1.0",
  "columns": 2,
  "tiles": [
    {
      "type": "PING",
      "label": "Localhost",
      "params": { "hostname": "127.0.0.1" }
    },
    {
      "type": "PORT",
      "label": "Dev server",
      "params": { "hostname": "127.0.0.1", "port": 8080 }
    }
  ]
}
      
UI root properties
version string required
The configuration format version.

Note Current version is "1.0"

columns number required
Number of columns the grid is based on.
zoom number
Zoom factor applied to all tiles.
Default: 1
tiles Tile[] required
List of tile definitions. See below to know more about that.
Tile common properties

Each tile definition has common properties:

type string required
Tile type, must be one of those available in the Tile definitions section.
label string
Allow override the automatic Core fill (example: for PING, it's the hostname)
columnSpan number
Number of columns to use.
Must not be greater than number of columns defined in root.
Default: 1

Example On a 4 columns grid, you can extend a tile full width with columnSpan: 4

TIP Fill all previous cells with EMPTY tiles if needed.

rowSpan number
Number of rows to use.
Default: 1

Example Tile can take two rows with rowSpan: 2

configVariant string
Some tiles can have different core configuration.
See Configuration Variants.

Tile definitions

Empty

Add an empty tile (to fill lines, columns, align things, ...).


{ "type": "EMPTY" }
      

Group

Group sub tiles in one tile to get the global status of all sub tiles.

Note Group will only show non-successful tiles. If the tile is empty: everything is fine!

UI configuration
tiles Tile[] required
List of tile definitions

Note Cannot contain GROUP nor EMPTY tiles


{
  "type": "GROUP",
  "label": "Group name",
  "tiles": [
    {
      "type": "PING",
      "label": "Test",
      "params": {
        "hostname": "example.com"
      }
    },
    {
      "type": "AZUREDEVOPS-BUILD",
      "params": {
        "project": "project",
        "definition": 1,
        "branch": "master"
      }
    },
    {
      "type": "PINGDOM-CHECK",
      "params": {
        "id": 42
      }
    }
  ]
}
        
Group name
Test
master
0:42
Check name
3 / 3
3 / 3
1 / 3

Azure DevOps

Show the status of builds and releases.

Core configuration
MO_MONITORABLE_AZUREDEVOPS_URL number required
Azure DevOps base URL
MO_MONITORABLE_AZUREDEVOPS_TOKEN number required
Your private API token
MO_MONITORABLE_AZUREDEVOPS_TIMEOUT number
Timeout in milliseconds before returning error
Default: 1000

Configuration Variants are available for Azure DevOps

AZUREDEVOPS-BUILD

Show the status of a build using its definition. In the case of a multi-branch definition, a filter can be specified.

UI configuration
project string required
Azure DevOps project name
definition number required
Pipeline definition ID (from URL definitionId query parameter)
branch string
Branch name
Default: show the last build

{
  "type": "AZUREDEVOPS-BUILD",
  "params": {
    "project": "project",
    "definition": 1,
    "branch": "master"
  }
}
        
Build name
0:42
5 minutes ago
5 minutes ago
John Doe

AZUREDEVOPS-RELEASE

Show the status of a release using its definition.

UI configuration
project string required
Azure DevOps project name
definition number required
Release definition ID (from URL definitionId query parameter)

{
  "type": "AZUREDEVOPS-RELEASE",
  "params": {
    "project": "project",
    "definition": 1
  }
}
        
Release name
0:42
5 minutes ago
5 minutes ago
John Doe

GitHub

Show branch checks status and display search result counters.

Core configuration
MO_MONITORABLE_GITHUB_TOKEN string required
Personal access token
Create a personal access token for Monitoror
MO_MONITORABLE_GITHUB_TIMEOUT number
Timeout in milliseconds before returning error
Default: 5000
MO_MONITORABLE_GITHUB_COUNTCACHEEXPIRATION number
Count cache duration in milliseconds.
GITHUB-COUNT tile use a specific GitHub API with a reduced rate-limit.

Tip If you encounter issues with numerous GITHUB-COUNT tiles, please consider increase this value, and/or use multiple tokens across multiple Configuration Variants.

Default: 30000

Configuration Variants are available for GitHub

GITHUB-COUNT

Show a counter of issues and pull requests matching a GitHub query.

UI configuration
query string required
Your custom GitHub search query.
See the GitHub documentation to build your own query .

Note This tile only works for issues and pull requests.


{
  "type": "GITHUB-COUNT",
  "label": "Monitoror open issues",
  "params": {
    "query": "is:issue is:open repo:monitoror/monitoror"
  }
}
        
Monitoror open issues
18

GITHUB-CHECKS

Show the status of all checks for a given commit reference.

UI configuration
owner string required
GitHub group or user (from URL)
repository string required
GitHub repository name (from URL)
ref string required
A git reference, commonly a branch name

{
  "type": "GITHUB-CHECKS",
  "params": {
    "owner": "monitoror",
    "repository": "monitoror",
    "ref": "develop"
  }
}
        
monitoror @ develop
0:42
5 minutes ago
5 minutes ago
John Doe

GITHUB-PULLREQUESTS

Show each open pull request status.

Note This tile is a dynamic tile that will be replaced by N classic GITHUB-CHECKS tiles.
N being the number of open pull requests.

UI configuration
owner string required
GitHub group or user (from URL)
repository string required
GitHub repository name (from URL)

{
  "type": "GITHUB-PULLREQUESTS",
  "params": {
    "owner": "monitoror",
    "repository": "monitoror"
  }
}
        

HTTP

Send a GET request to a URL, then check the status code and the content.

Core configuration
MO_MONITORABLE_HTTP_TIMEOUT number
Timeout in milliseconds before returning error
Default: 1000
MO_MONITORABLE_HTTP_SSLVERIFY boolean
Check if SSL certificate is valid
Default: true

Configuration Variants are available for HTTP

HTTP-STATUS

Will only check that status code is in range.

UI configuration
url string required
URL to fetch over HTTP(S)
statusCodeMin number
Minimum HTTP status code
Default: 200
statusCodeMax number
Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-STATUS",
  "params": {
    "url": "http://localhost/test",
    "statusCodeMax": 299
  }
}
        
http://localhost/test

HTTP-RAW

Performed checks:

  • status code in range
  • content matches the regex correctly
UI configuration
url string required
URL to fetch over HTTP(S)
statusCodeMin number
Minimum HTTP status code
Default: 200
statusCodeMax number
Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399
regex string
Match or first group will be show in tile.
Regex format is RE2, described at https://golang.org/s/re2syntax
Default: .*

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-RAW",
  "params": {
    "url": "http://localhost/tag",
    "regex": "version:\s*([^\s]*)"
  }
}
        
http://localhost/tag
v2020.1.42

HTTP-FORMATTED

Performed checks:

  • status code in range
  • content can be parsed as JSON, XML or YAML (see format)
  • presence of the key
  • the key value matches the regex correctly
UI configuration
url string required
URL to fetch over HTTP(S)
format string required
Must be one of following:
  • JSON
  • XML
  • YAML
key string required
statusCodeMin number
Minimum HTTP status code
Default: 200
statusCodeMax number
Maximum HTTP status code
Must be superior or equal to statusCodeMin
Default: 399
regex string
Match or first group will be show in tile.
Regex format is RE2, described at https://golang.org/s/re2syntax
Default: .*

Tip To check a single HTTP status code, set the same value in both statusCodeMin and statusCodeMax


{
  "type": "HTTP-FORMATTED",
  "params": {
    "url": "http://localhost/count",
    "format": "JSON",
    "key": "sub.\"dotted.key\".[0]"
  }
}
        
http://localhost/count
1337

Jenkins

Jenkins tiles are used to display the status of a build.

Core configuration
MO_MONITORABLE_JENKINS_URL string required
Jenkins base URL
MO_MONITORABLE_JENKINS_LOGIN string required
Your login
MO_MONITORABLE_JENKINS_TOKEN string required
Your private API token
MO_MONITORABLE_JENKINS_TIMEOUT number
Timeout in milliseconds before returning error
Default: 2000
MO_MONITORABLE_JENKINS_SSLVERIFY boolean
Check if SSL certificate is valid
Default: true

Configuration Variants are available for Jenkins

JENKINS-BUILD

Show the status of a build, pipeline or specific branch of a multi-branch job or pipeline.

UI configuration
job string required
Jenkins job ID
branch string required if multi-branch
Branch name

{
  "type": "JENKINS-BUILD",
  "params": {
    "job": "test-job",
    "branch": "master"
  }
}
        
Test job
0:42
5 minutes ago
5 minutes ago
John Doe

JENKINS-MULTIBRANCH

Show the status of all branches of a multi-branch pipeline.

Note This tile is a dynamic tile that will be replaced by N classic JENKINS-BUILD tiles.
N being the number of checks that match the filters that have been set.

UI configuration
job string required
Jenkins job ID
match string
Filter branch names with a regex (whitelist)
Regex format is RE2, described at https://golang.org/s/re2syntax
unmatch string
Inverted regex filter based on branch names (blacklist)
Regex format is RE2, described at https://golang.org/s/re2syntax
Note match and unmatch options cannot be used at the same time.

{
  "type": "JENKINS-MULTIBRANCH",
  "params": {
    "job": "eu-west",
    "match": "^feat/"
  }
}
      

Ping

Get ping status and duration from a hostname.

Core configuration
MO_MONITORABLE_PING_COUNT number
Number of ping sent, used to retrieve an average value
Default: 2
MO_MONITORABLE_PING_INTERVAL number
Interval between ping in milliseconds
Default: 100
MO_MONITORABLE_PING_TIMEOUT number
Global time in milliseconds before returning error
Default: 1000

Configuration Variants are available for Ping

Note for Linux and macOS users
If you see PING: disabled at Monitoror launch, you need to relaunch Monitoror as super-user to get PING tiles working.

On Linux, a cleaner solution is to run setcap as super-user to allow Monitoror to bind to raw sockets: setcap cap_net_raw=+ep monitoror

PING

Show ping to a hostname status and duration.

UI configuration
hostname string required
Hostname to ping

{
  "type": "PING",
  "params": {
    "hostname": "localhost"
  }
}
        
localhost
42ms

Pingdom

Pingdom checks interface with pingdom.com/website-monitoring

Core configuration
MO_MONITORABLE_PINGDOM_URL string
Pingdom API base URL
Default: https://api.pingdom.com/api/3.1
MO_MONITORABLE_PINGDOM_TOKEN number required
Your private API token
On Pingdom, go to Integrations > The Pingdom API, then click Add API token
MO_MONITORABLE_PINGDOM_TIMEOUT number
Timeout in milliseconds before returning error
Default: 1000
MO_MONITORABLE_PINGDOM_CACHEEXPIRATION number
Specific cache duration for Pingdom check
Default: 30000

Configuration Variants are available for Pingdom

PINGDOM-CHECK

Show state of a Pingdom specific check.

UI configuration
id number required
Pingdom check ID

{
  "type": "PINGDOM-CHECK",
  "params": {
    "id": 10
  }
}
        
Check name

PINGDOM-CHECKS

Show state of all Pingdom checks.

Note This tile is a dynamic tile that will be replaced by N classic PINGDOM-CHECK tiles.
N being the number of checks that match the filters that have been set.

UI configuration
tags string
Pingdom check tag list separated by commas
sortBy string
Allow to sort checks by following:
  • name

{
  "type": "PINGDOM-CHECKS",
  "params": {
    "tags": "eu-west",
    "sortBy": "name"
  }
}
      

Port

Check if a port is open with something listening behind.

Core configuration
MO_MONITORABLE_PORT_TIMEOUT number
Timeout in milliseconds before returning error
Default: 1000

Configuration Variants are available for Port

PORT

Will success when the port is open with something listening behind.

UI configuration
hostname string required
Hostname to scan
port number required
Port to scan

{
  "type": "PORT",
  "params": {
    "hostname": "localhost",
    "port": 443
  }
}
        
localhost:443

Travis CI

Show Travis CI build status and progress.

Core configuration
MO_MONITORABLE_TRAVISCI_URL string
Travis CI API base URL
Default: https://api.travis-ci.com/
MO_MONITORABLE_TRAVISCI_TOKEN string required
Your private API token
MO_MONITORABLE_TRAVISCI_TIMEOUT number
Timeout in milliseconds before returning error
Default: 2000

Configuration Variants are available for Travis CI

TRAVISCI-BUILD

Show the status of the build of the branch of a specific project.

UI configuration
owner string required
GitHub group or user (from URL)
repository string required
GitHub repository name (from URL)
branch string
Branch name
Default: show the last build

{
  "type": "TRAVISCI-BUILD",
  "params": {
    "owner": "Alex-D",
    "repository": "check-disk-space",
    "branch": "master"
  }
}
        
Build name
0:42
5 minutes ago
5 minutes ago
John Doe

In this example, the tile will show the status of github.com/Alex-D/check-disk-space@master

Advanced options

Configuration Variants

Configuration Variants allow you to monitor multiple servers (e.g.: multiple Jenkins servers).

To do so, you will need some more lines in your core configuration and some additional configVariant field in UI configuration.


# In your .env file
MO_MONITORABLE_JENKINS_URL="http://jenkins.example.com"
MO_MONITORABLE_JENKINS_LOGIN="username"
MO_MONITORABLE_JENKINS_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxx"

MO_MONITORABLE_JENKINS_PROD_URL="http://jenkins-prod.example.com"
MO_MONITORABLE_JENKINS_PROD_LOGIN="username"
MO_MONITORABLE_JENKINS_PROD_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxx"
      

{
  "columns": 2,
  "tiles": [
    {
      "type": "JENKINS-BUILD",
      "params": { "job": "build", "branch": "master" }
    },
    {
      "type": "JENKINS-BUILD",
      "params": { "job": "deploy-internal" }
    },
    {
      "type": "JENKINS-BUILD",
      "configVariant": "prod",
      "params": { "job": "deploy-prod" }
    },
  ]
}
      

In this example:

  • the first 2 builds will fetch their data from http://jenkins.example.com
  • the last one from http://jenkins-prod.example.com

Core cache

MO_UPSTREAMCACHEEXPIRATION number
Throttle delay in milliseconds for external requests. Avoid overloading services
Default: 10000
MO_DOWNSTREAMCACHEEXPIRATION number
Duration in milliseconds of the previous result by URL which is returned in case of timeout. Avoid false negative on CI checks
Default: 120000