marcells/node-build-monitor

node-build-monitor

A Build Monitor written in Node.js, which supports several build services. It can be easily extended to support new services. You can mix different services as you like and you'll always see the newest builds in its responsive and themable web frontend automatically. And finally, everything is prepared to run as a Docker container.

Here's a demo: http://builds.mspi.es _{^{(other themes)}
(automatically deployed from this repository with Docker Cloud as a Docker container to the Microsoft Azure Cloud)}

Supported services

• Travis CI _{^{(Configuration)}}
• Jenkins _{^{(Configuration)}}
• TeamCity _{^{(Configuration)}}
• Azure DevOps and Team Foundation Server Builds _{^{(Configuration)}}
• Azure DevOps and Team Foundation Server Releases _{^{(Configuration)}}
• Team Foundation Server 2013 and lower (on-premise) via tfs-proxy _{^{(Configuration)}}
• Team Foundation Server 2015/2017 (on-premise) _{^{(Configuration)}}
• GitLab (on-premise, beta) _{^{(Configuration)}}
• BuddyBuild _{^{(Configuration)}}
• Bamboo _{^{(Configuration)}}
• BambooDeploy _{^{(Configuration)}}
• Bitbucket Pipelines _{^{(Configuration)}}
• Buildkite _{^{(Configuration)}}
• Bitrise _{^{(Configuration)}}
• CCTray _{^{(Configuration)}}
• Shippable _{^{(Configuration)}}
• PRTG _{^{(Configuration)}}
• Circle CI _{^{(Configuration)}}
• Drone _{^{(Configuration)}}

Feel free to make a Fork of this repository and add another service.

Jump to the configuration documentation and see how the services are configured.

Quickstart

You have four options:

• Run node-build-monitor by downloading the standalone version _{^{(easiest way to run it)}}
• Run node-build-monitor manually with node _{^{(preferred during development)}}
• Run node-build-monitor with Docker Compose _{^{(preferred in production)}}
• Run node-build-monitor in kubernetes _{^{(as a helm chart)}}

Configuration

The build monitor configuration can be placed in one of the following locations:

1. %HomeDirectory%/node-build-monitor-config.json
2. %PathOfExecutable%/config.json (only for the standalone version)
3. app/config.json

{
  "monitor": {
    "interval": 30000,
    "numberOfBuilds": 12,
    "latestBuildOnly": false,
    "sortOrder": "date",
    "errorsFirst": false,
    "expandEnvironmentVariables": false,
    "debug": true
  },
  "services": [
    {
      "name": "Travis",
      "configuration": {
        "slug": "node-build-monitor"
      }
    },
    {
      "name": "Travis",
      "configuration": {
        "slug": "marcells/bloggy",
        "latestBuildOnly": true
      }
    }
  ]
}

In the monitor section you can set up some general settings:

The services section accepts an array, each describing a single build service configuration (you are allowed to mix different services):

• the name setting refers to the used service
• the configuration setting refers to its configuration, which may differ from each service (see below)

Travis CI

Supports the Travis CI build service.

{
  "name": "Travis",
  "configuration": {
    "slug": "marcells/node-build-monitor"
  }
}

Jenkins

Supports the Jenkins build service. The service can operate in single-job or single-view mode. In single-job mode, the builds of a selected Jenkins job are shown. In single-view mode, the builds of all the jobs in a given Jenkins view are shown. In both modes, one can limit the maximum number of recent builds per job.

{
  "name": "Jenkins",
  "configuration": {
    "url": "http://jenkins-server:8080",
    "username": "jenkins_username",
    "password": "jenkins_password",
    "job": "JenkinsJobName",
    "numberOfBuildsPerJob": 3,
    "options": {
      "strictSSL": false
    }
  }
}

TeamCity

Supports the TeamCity build service.

{
  "name": "TeamCity",
  "configuration": {
    "url": "http://teamcity_username:teamcity_password@teamcity-server:8111",
    "buildConfigurationId": "TeamCityProject_TeamCityBuildConfiguration",
    "branch": "master",
    "authentication": "ntlm",
    "username": "teamcity_username",
    "password": "teamcity_password",
    "useGuest": true,
    "reportFailedToStart": true
  }
}

Azure DevOps and Team Foundation Server Builds

Supports Azure Pipelines, the Azure DevOps and Team Foundation Server build service.

{
  "name": "Tfs",
  "configuration": {
    "url": "https://{youraccount}.visualstudio.com or http://tfs-server:8080/tfs",
    "collection": "DefaultCollection",
    "project": "projectname",
    "username": "username",
    "pat": "personalaccesstoken",
    "queryparams": "&branchName=refs/heads/master&definitions=4,5,6,7&maxBuildsPerDefinition=1",
    "includeQueued": false,
    "showBuildStep": false
  }
}

Note:

• Create a peronal access token with access to read builds.
• The url formed is of the following format: https://{instance}/{collection}/{project}/_apis/build/builds?api-version=2.0[queryparams]
• Please note that all the configuration fields are mandatory. If a field is not required like queryparams, please provide empty string in the configuration.

Azure DevOps and Team Foundation Server Releases

Supports Azure Piplines, the Azure DevOps and Team Foundation Server (Releases) release service.

{
  "name": "TfsRelease",
  "configuration": {
    "protocol": "protocol",
    "project": "projectname",
    "instance": "instance",
    "username": "username",
    "pat": "personalaccesstoken",
    "queryparams" : "&$top=10",
    "groupbyrelease": false,
    "apiVersion": "4.1-preview"
  }
}

Note: Create a personal access token with access to read builds.

• The url formed is of the following format: https://{instance}/{project}/_apis/release/deployments?api-version={apiVersion}[queryparams]
• Please note that all the configuration fields are mandatory. If a field is not required like queryparams, please provide empty string in the configuration.

Team Foundation Server 2013 and lower (on-premise)

Supports an on-premise Microsoft Team Foundation Server via the tfs-proxy bridge.

{
  "name": "TfsProxy",
  "configuration": {
    "tfsProxyUrl": "http://tfs-proxy:4567/builds",
    "url": "http://tfs-server:8080/tfs/DefaultCollection",
    "username": "domain\\buildadmin",
    "password": "buildadmin_password"
  }
}

Team Foundation Server 2015/2017 (on-premise)

Supports an on-premise Microsoft Team Foundation Server 2015/2017 (and later).

{
  "name": "Tfs2015",
  "configuration": {
    "url": "http://tfs-server:8080/tfs/DefaultCollection/TeamProject",
    "username": "domain\\buildadmin",
    "password": "buildadmin_password"
  }
}

Important: For TFS 2017 you have to create a personal access token. It only needs the permission to read builds. Please use your username and the generated token as the password.

GitLab (on-premise, beta)

Supports an on-premise GitLab Community Edition/Enterprise Edition with built-in CI server. Also supports hosted gitlab.

{
  "name": "GitLab",
  "configuration": {
    "url": "http://gitlab.example.com:8080",
    "token": "secret_user_token",
    "additional_query": "&search=gitlab-org&starred=true",
    "numberOfPipelinesPerProject": 3,
    "pipeline": {
      "status": ["running", "pending", "success", "failed", "canceled", "skipped"]
    },
    "slugs": [
      {
        "project": "gitlab-org/gitlab-ci-multi-runner",
        "ref": "master"
      }
    ]
  }
}

Because API V4 returns all internal and public projects by default, you propably want to set additional_query as well. Good choices could be &owned=true or &membership=true. If you want to filter the pipeline status you'll need to set pipeline.status otherwise it will show every status.

BuddyBuild

Supports BuddyBuild build service

{
  "name": "BuddyBuild",
  "configuration": {
    "project_name": "Android",
    "app_id": "Your-App-ID",
    "url": "https://api.buddybuild.com/v1/apps",
    "access_token": "Your-Access-Token",
    "build_id": "",
    "branch": "develop"
  }
}

Bamboo

Supports Bamboo build service

{
  "name": "Bamboo",
  "configuration": {
    "url": "http://yourbamboo.com",
    "planKey": "Plan-Key",
    "username": "user",
    "password": "pass",
    "includeAllStates": true,
    "latestBuildPerBuildPlanOnly": true
  }
}

BambooDeploy

Supports BambooDeploy deployment service

{
  "name": "BambooDeploy",
  "configuration": {
    "url": "http://yourbamboo.com",
    "planKey": "Plan-Key",
    "username": "user",
    "password": "pass",
    "includeAllStates": true,
    "latestBuildPerBuildPlanOnly": true,
    "environmentName": "dev",
    "projectId": 123
  }
}

Bitbucket Pipelines

Supports Bitbucket Pipelines build service.

In order to monitor a Bitbucket pipeline, one has to create an app-password by navigating to https://bitbucket.org/account/user/<username>/app-passwords

Once "Create app password" has been clicked, one has to ensure that the "read pipelines" box has been checked. Once this box has been checked, click "create" and an AppPassword will be returned that has to be copied to the config.json:

{
  "name": "BitbucketPipelines",
  "configuration": {
    "apiKey": "key",
    "username": "username",
    "slug": "slug",
    "teamname": "teamname"
  }
}

Buildkite

Supports Buildkite build service

{
  "name": "Buildkite",
  "configuration": {
    "orgSlug": "your-organisation-slug",
    "teamSlug": "everyone"
  }
}

Bitrise

Supports the Bitrise build service.

{
  "name": "Bitrise",
  "configuration": {
    "slug": "<ID OF YOUR APPLICATION>",
    "token": "<YOUR PERSONAL API TOKEN>"
  }
}

CCTray

Supports CCTray format. CCTray is part of CruiseControl.NET.

{
  "name": "CCTray",
  "configuration": {
    "url": "<URL FOR CCTRAY>"
  }
}

Shippable

Supports the Shippable build service.

{
  "name": "Shippable",
  "configuration": {
    "url": "https://api.shippable.com",
    "token": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeee",
    "projects": "123456789012345678901234,098765432109876543210987,...",
    "branch": "master",
    "limit": 12
  }
}

PRTG

Supports the PRTG monitoring service.

{
  "name": "PRTG",
  "configuration": {
    "url": "https://myprtg.myserver",
    "sensorId": "1234",
    "username": "username",
    "passhash": "123456789"
  }
}

CircleCI

Supports the CircleCI service

{
  "name": "CircleCI",
  "configuration": {
    "debug": false,
    "token": "somePersonalToken",
    "vcs": "bitbucket",
    "username": "marcells",
    "project": "node-build-monitor",
    "branch": "master",
    "groupByWorkflow": true
  }
}

Drone

Supports the Drone build service (version 1.0 minimum)

{
  "name": "Drone",
  "configuration": {
    "debug": false,
    "url": "drone.company.io",
    "token": "s0meDr0neMachineToken",
    "slug": "marcells/node-build-monitor"
  }
}

Run the standalone version (easiest way)

1. Download the latest release for Linux (x64), MacOS (x64) or Windows (x64)
2. For MacOS and Linux you need to set the execute permission to run it
   • MacOS: chmod +x node-build-monitor-macos
   • Linux: chmod +x node-build-monitor-linux
3. Place a file config.json next to the executable (see the description of the file in the configuration section above)
4. Run the executable
5. Open your browser and navigate to http://localhost:3000 (switch to fullscreen for the best experience)

Run it manually (during development)

1. Pull the repository
2. Run npm install
3. Place a file config.json in the app folder (see the description of the file in the configuration section above)
4. If you connect to services, which are using self signed certificates, then you have to set the environment variableNODE_TLS_REJECT_UNAUTHORIZED=0. (More Info)
5. Run the build monitor with node app/app.js
6. Open your browser and navigate to http://localhost:3000 (switch to fullscreen for the best experience)

Run grunt to execute the tests and check the source code with JSHint.

Run it with Docker Compose (in production)

You can try out or install the build monitor with Docker Compose easily.

TL;DR: Go to the docker directory, rename the file config.example.json to config.json and edit with your configuration or create config.json file directly. Then run the following commands, which you need.

Below, each commands is explained in detail.

1. Create configuration and set up the build monitor

Place a file config.json next to the docker-compose.*.yml and configure the services:

{
  "monitor": {
    "interval": 30000,
    "numberOfBuilds": 12,
    "latestBuildOnly": false,
    "sortOrder": "date",
    "debug": true
  },
  "services": [
    {
      "name": "Travis",
      "configuration": {
        "slug": "marcells/bloggy"
      }
    },
    {
      "name": "Travis",
      "configuration": {
        "slug": "marcells/node-build-monitor"
      }
    }
  ]
}

See the description of this file in the configuration section above.

2. Build your custom build monitor image and run the container

Build your custom node-build-monitor docker image. This will also include your configuration from the previous step. Afterwards the container is started.

a. Without tfs-proxy

Installing and running node-build-monitor in a docker container for use on the same machine is simple with the following commands:

Run docker-compose from your custom docker-compose.yml:

docker-compose build --pull
docker-compose up -d

b. With tfs-proxy

If you want to get access to the tfs-proxy, then you need a slighly different command, which allows the build monitor container to access the tfs-proxy container.

Run docker-compose from your custom docker-compose.with-tfs-proxy.yml:

docker-compose -f docker-compose.with-tfs-proxy.yml build --pull
docker-compose -f docker-compose.with-tfs-proxy.yml up -d

Ensure that you omit the tfsProxyUrl setting in your config.json, so that it can be determined automatically. Here you'll get more information about container linking.

c. With self-signed-certs

If you connect to services which are using self signed certificates, run docker-compose from your custom docker-compose.with-self-signed-certs.yml:

docker-compose -f docker-compose.with-self-signed-certs.yml build --pull
docker-compose -f docker-compose.with-self-signed-certs.yml up -d

3. Access it with your browser

Now open your browser and navigate to http://localhost:3000 to see your running or finished builds. Switch to fullscreen for the best experience.

(4. Access logs)

You can take a look at the logs of the build monitor by using this command:

docker-compose logs

Run it in Kubernetes as a helm chart

You can use the helm chart to deploy node-build-monitor in your kubernetes cluster.

TL;DR: Go to the charts directory, and deploy it to your cluster with helm install . --name build-monitor. To set the configuration you need to modify the values.yaml file. See Readme in chart folder for more informations.

Theming support

Here you can check out the existing themes. Feel free to add your own and make a pull request. It can be done very easy.

You can switch the themes by the url parameter theme. e.g.: http://localhost:3000?theme=list

Creating a new theme

If you want to create a new theme, you simply have to create one template file and one stylesheet in the following paths.

• Stylesheet: app/public/stylesheets/themes/[name of theme]/style.css (you can place dependent css files in this folder)
• Template: app/public/templates/themes/[name of theme]/.html

Please use a unique class prefix like [name of theme]-theme for your css, so that we do not run into any conflicts with other themes.

A list with the name builds with Knockout.js ViewModels BuildViewModel will be bound to the template. Knockout.js has a very low learning curve and provides a powerful data-binding mechanism.

Just check out the other themes to get sample code. It's quite easy to create new themes.

Additional: Raspberry Pi Configuration

Here are some useful links, how to run the build monitor frontend on a Raspberry Pi.

• Boot to browser
• Automatically turn the monitor off in the evening

This sample script can be used in a cronjob to automatically send your screen to sleep mode in the evening and wake it up in the morning.

#!/bin/bash

if [ $1 = 'on' ]; then
  tvservice -p;
  fbset -depth 8;
  fbset -depth 16;
  chvt 6;
  chvt 7;
  echo 'Switched Screen ON!'
fi

if [ $1 = 'off' ]; then
  tvservice -o
  echo 'Switched Screen OFF!'
fi

License

The MIT License (MIT)

Copyright (c) 2017 Marcell Spies (@marcells | http://mspi.es)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.