@nrk/odashboard v0.0.9

Odashboard

A configurable dashboard with a simple plugin architecture. Written in Node.js with Express, Socket.io and Angular.

Getting started

Installing Odashboard as a dependency

Odashboard can be installed from npm as a dependency.

Example usage In your folder my-dashboard/

npm i @nrk/odashboard -S

Create configuration files:

my-dashboard/
├── config/
│   ├── widgets.js
│   └── dataSources.js
└── package.json

Check out config examples of dataSources and widgets

Add npm script to package.json start dashboard

{
  "scripts": {
    "start": "odashboard"
  }
}

Command line arguments

You can pass arguments to odashboard to override default options

• -w, --widgetconfig - path to config file
• -d, --datasourceconfig - path to config file
• -p, --port - port to run on

Forking and using odashboard

> npm install

> npm run test

> npm run build

> npm start

The application answers on port 3000.

How it may look:

For some use cases, having access to all code and plugins might be better than installing as a dependency.

To configure your dashboard you need to edit two files:

• In config/widgets.js you define your widgets and their properties.
• In config/dataSources.js you define the datasources to your widgets.

Most widgets need a compatible datasource to run, but some (like the iframe-plugin) only need you to define a widget.

Plugins

Below you find current list of available plugins. The generic plugin lets you combine different sources with different plugins.

Generic plugin

The generic plugin makes it possible to use a wide range of widgets with a set of different datasources. The availabe widgets are:

The widgets can display data from the following datasources:

Each plugin is documented in the plugin folder

How to setup widgets

Widgets are defined in config/widgets.js. Each widget is defined as a json-object with the following fields:

In addition each plugin may have it's own fields. Default values are defined in widgetDefaults in config/appconfig.js

This is an example config for a number widget using the Generic-plugin:

var myWidget = {
    plugin: "generic"
    datasourceId: "myDataSource1",
    url: "http://moreinfoaboutmywidget.com",
    // Plugin specific fields
    widgetType: "number",
    displayName: "Look ma, a number",
    fieldName: "field",
 }

How to setup datasources

Datasources are defined in config/dataSources.js. Each datasource is defined as a json-object with the following fields:

A datasource has an id, a plugin, and an updateInterval. In addition each plugin will have it's own specific fields. In this example we use the Simple-plugin, which only has a url. Notice how the id corresponds to the datasourceId in our widget above.

{
    id: 'myDataSource1',
    plugin: 'generic',
    updateInterval: 6000,
    timeout: 2500,
    auth: undefined,

    // Plugin specific fields
    source: 'json-endpoint',
    config: {
      url: "http://myhost.com/myapi/test"
    } 
}

Datasources Authentication

Odashboard supports basic authentication, ntlm and header api keys. To use the authentication you must first define the auth object in the datasource.

For Basic autentication, set the type to basic and provide username and password in the options-object.

Basic auth example:

auth: {
  type: "basic",
  options: {
    username: 'user',
    password: 'password'
  }
}

For Api-keys, set the type to apiKey. In the options object you should provide your key in the key field. Because the field to provide API-keys vary from API to API, you must also provide what header field to put it under in the headerName field.

Api key example:

auth: {
  type: "apiKey",
  options: {
    key: 'mySecretKey',
    headerName: 'X-Api-Key'
  }
}

For NTML you must set the type to ntlm. In the options object you must provide username, password, domain and workstation. The NTLM auth is built using the httpntlm package.

NTML example:

auth: {
  type: "ntlm",
  options: {
    username: 'user',
    password: 'password',
    domain: 'WORKGROUP',
    workstation: 'MY-COMPUTER'
  }
}

Tabs and rows

To make the widget available you need to add it to a row in the dashboard. A row has an array of widgets. A row is defined like this:

var myFirstRow = {
    title: "My widgets",
    widgets: [myWidget, myOtherWidget]
}

The rows in turn need to be included in the dashboardConfig-object. The rows can be added in two different ways, depending on if you need multiple tabs (pages) in your dashboard or not.

If you only want one page, you can add the rows directly in the rows-field.

var dashboardConfig = {
    title: "My Dashboard",
    rows: [myRow, mySecondRow]
};

If you have so many widgets that you need multiple pages, define an array of row-arrays in the tabs-field:

var dashboardConfig = {
    title: "My Dashboard",
    tabs: [
      [myFirstRow, mySecondRow],
      [pageTwoRow, pageTwoSecondRow]
    ]
};

If both tabs and rows are present, tabs will be used.

Tab cycling

In config/appconfig.js you'll find 2 settings

• tabCycleAutoStart: boolean - control if cycle is started automatically or not
• tabCycleInterval: number - control the time to spend on each tab (milliseconds)

Why another dashboard?

Odashboard origins from a hackathon at NRK. We wanted to display build information from TeamCity together with queue information from RabbitMQ on a big screen in our office. Instead of looking to existing open source dashboards like Dashing, we wanted to get some experience with Node.js, and thus Odashboard was born. At first it was a hard coded mess, but over time it evolved to the plugin oriented configurable application it is today. And then we thought other people might enjoy it as much as we do, so we open sourced it.

The strength of Odashboard is that you can get your dashboard up and running in minutes, and all you need to do is edit some config files. Try it out!