A simple platform for publishing metrics, both as JSON, and as embeddable visualisations and dashboards
Switch branches/tags
Clone or download
Floppy Merge pull request #327 from theodi/dependabot/bundler/grape-swagger-…

Bump grape-swagger-entity from 0.2.1 to 0.2.3
Latest commit 0bd0fa3 Dec 22, 2017
Failed to load latest commit information.
.github update PR template to remove auto-tag Sep 18, 2017
docs Add screenshots to illustrate configuration upgrade steps Aug 17, 2017
features fix error handling for from < to dates Dec 20, 2017
lib fix error handling for from < to dates Dec 20, 2017
spec require api in spec helper Dec 20, 2017
.gitignore Ignore guard file Aug 31, 2017
.rspec Rspec enabled Feb 4, 2016
.ruby-version switch to ruby 2.4.1 Aug 1, 2017
.travis.yml Include cmake to resolve heroku build fail Aug 14, 2017
CODE_OF_CONDUCT.md Refactor .github to only GH relevant MD files Jul 28, 2017
CONTRIBUTING.md Refactor .github to only GH relevant MD files Jul 28, 2017
Gemfile include grape-entity and swagger Sep 12, 2017
Gemfile.lock Bump grape-swagger-entity from 0.2.1 to 0.2.3 Dec 21, 2017
Guardfile Rspec enabled Feb 4, 2016
Guardfile.shotgun Break these out Feb 4, 2016
LICENSE.md License, README Dec 3, 2013
Procfile Well that was fun Feb 1, 2016
README.md Merge branch 'master' into upgrade-instructions Sep 20, 2017
Rakefile YTD demo value should be lower than annual target demo value Apr 13, 2017
UPGRADING.md Add some contact information seems appropriate Aug 21, 2017
Vagrantfile Launch stuff Dec 6, 2013
app.json buildpack order is important! Aug 16, 2017
config.rb Start with Compass Jul 1, 2016
config.ru mount grape API and Sinatra bothan app with rack cascade Aug 31, 2017
console Add a console startup script Apr 28, 2017
mongoid.yml Put development creds back to default Sep 26, 2016
questions.md Render iframes Feb 2, 2016


Build Status Dependency Status Coverage Status Code Climate License


A simple platform for publishing metrics, both as JSON, and as embeddable visualisations and dashboards.

Bothan's live instance contains API documentation and tutorials on deploying your personal instance of Bothan to Heroku and intergrating with Zapier

There are also two software libraries that make interfacing with Bothan super easy:

Summary of features

Bothan is a Sinatra web app that provides a simple wrapper around MongoDB to allow storage of time series metrics. Bothan provides a REST API for storing and retrieving time-series data, as well as human-readable views which can be customised and embedded in other sites, allowing it to be used for building dashboards. It is designed for open publication of metrics data and includes licensing metadata for simple generation of an Open Data Certificate Read the Documentation for the API here


Follow the public feature roadmap for Bothan


Most updates should not require intervention, but manual steps are occasionally required. If you are experiencing deployment problems, see the upgrade guide.



ruby version 2.3.0p0

The application uses mongodb for data persistence

The application requires capybara-webkit for testing (for install instuctions see below)

Environment variables

METRICS_API_DESCRIPTION='This API contains a list of all metrics collected by the Open Data Institute since 2013'
METRICS_API_LICENSE_NAME='Creative Commons Attribution-ShareAlike'

See below for Pusher configuration instructions

Specific Development Instructions

Pusher setup
  1. Log in to https://pusher.com
  2. Create a new application and call it something sensible
  3. Select the App Keys tab and note the following values

You can create the PUSHER_URL variable required for your .env file by concatenating the above variables as follows: PUSHER_KEY:PUSHER_SECRET@api-eu.pusher.com/apps/PUSHER_APP_ID


To run bothan locally requires capybara-webkit. Specific instructions to get this running is as follows


At present Capybara depends on Qt 5. This requires the full Xcode, rather than xcode developer tools, to be installed

Database Configuration

Install mongo:
brew install mongo redis (if using brew)

make a data directory for mongo databases
sudo mkdir -p /data/db

change directory ownership so that mongodb can operate
sudo chown -R $USERNAME /data/

Development: Running the full application locally

Checkout the repository

run mongod to establish a database for persistence

run brew install cmake or sudo apt-get install cmake

run bundle in the checked out directory.

optional: run rake demo:setup to establish some demo metrics for use locally

The app is loaded via Rack Middleware.
execute bundle exec rackup config.ru to start the application


A MongoDB instance must be running prior to executing test suites (see steps above from Running the full application locally for installation)

Execute mongod

The entire suite of unit tests (rspec) and user features (cucumber) can be executed with the rake command

alternatively execute each suite separately with

  • for unit tests execute bundle exec rspec
  • for Cucumber features execute bundle exec cucumber

Rake Tasks

rake demo:setup will establish one metric of each type that Bothan supports


Deployment On Heroku

Bothan can deploy a personal instance to Heroku.

You can employ this as an alternative to running a full local dev instance if you couple your heroku instance with the heroku toolbelt.