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
Download and run the latest release.
Linux x64 |
Download Monitoror for Linux x64
|
Linux ARM |
Download Monitoror for Linux ARM
|
macOS |
Download Monitoror for macOS
|
Windows x64 |
Download Monitoror for Windows
|
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:
default
— Default theme demodark
— Dark theme demo
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
norEMPTY
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
}
}
]
}
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"
}
}
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
}
}
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
Default:GITHUB-COUNT
tiles, please consider increase this value, and/or use multiple tokens across multiple Configuration Variants.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"
}
}
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"
}
}
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 tostatusCodeMin
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-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 tostatusCodeMin
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-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
requiredstatusCodeMin
number
-
Minimum HTTP status code
Default:200
statusCodeMax
number
-
Maximum HTTP status code
Must be superior or equal tostatusCodeMin
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]"
}
}
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"
}
}
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
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"
}
}
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
}
}
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
}
}
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"
}
}
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