Home

Awesome

Descartes

Build Status

dashboard

Purpose

Provide an additional level of insight and collaboration that is neither available nor appropriate for a real-time utility such as Tasseo.

Objectives

Design, build and deploy a dashboard that allows users to correlate multiple metrics in a single chart, review long-term trends across one or more charts, and to collaborate with other users through a combination of annotations and related comment threads. This product should be capable of the following sample tasks:

Deployment

Descartes stores configuration data in PostgreSQL and Google OpenID state in Redis. It is assumed you have local PostgreSQL and Redis servers running for local development.

Service Dependencies

Options

Sessions and Authorization

The default session cookie should be randomized by setting SESSION_SECRET to a random string.

If your Graphite web server requires Basic Authentication, these credentials can be set using the GRAPHITE_USER and GRAPHITE_PASS environment variables.

Descartes provides organizational authorization using either Google OpenID or GitHub OAuth. The OAUTH_PROVIDER environment variable can be set to either google or github to determine which type to use.

Based on OAUTH_PROVIDER, some additional environment variables must be set:

Google OpenID

GitHub OAuth

A new GitHub application will need to be registered. The Main and Callback URLs should be the URL of your application.

Important: Don't forget to go over to your organization's member page and set yourself as a public member. This can be found at https://github.com/YOUR-ORG?tab=members (replace YOUR-ORG with your actual organization name). Once there, ensure that the button says "Conceal membership". If that's the button you see this means you're already public, otherwise click "Publicize membership".

Graphite Server Configuration

In order to support CORS with JSON instead of JSONP, we need to allow specific headers and allow the cross-domain origin request. The base URL of your Descartes application will need to be allowed as an origin. The following example is suitable for a test Descartes application running on localhost connecting to a remote Graphite/Apache 2.x server. Adjust as necessary for your environment or webserver.

Header set Access-Control-Allow-Origin "http://127.0.0.1:5000"
Header set Access-Control-Allow-Methods "GET, OPTIONS"
Header set Access-Control-Allow-Headers "origin, authorization, accept"
Header set Access-Control-Allow-Credentials true

If your Graphite composer is protected by basic authentication, you have to ensure that the HTTP verb OPTIONS is allowed unauthenticated. This looks like the following for Apache:

<Location />
    AuthName "graphs restricted"
    AuthType Basic
    AuthUserFile /etc/apache2/htpasswd
    <LimitExcept OPTIONS>
      require valid-user
    </LimitExcept>
</Location>

See http://blog.rogeriopvl.com/archives/nginx-and-the-http-options-method/ for an Nginx example.

Local

Descartes uses the Sinatra web framework under Ruby 1.9. Anyone wishing to run Descartes as a local service should be familiar with common Ruby packaging and dependency management utilities such as RVM and Bundler. If you are installing a new Ruby version with RVM, make sure that you have the appropriate OpenSSL development libraries installed before compiling Ruby.

All environment variables can be set from the command-line, although it's suggested to use .env instead. This file will automatically be picked up by foreman, which is also helpful when debugging (e.g. foreman run pry). This file will not be committed (unless you remove or modify .gitignore) so you shouldn't have to worry about accidentally leaking credentials.

$ rvm use 1.9.2
$ bundle install
$ createdb descartes
$ cp .env.example .env
$ $EDITOR .env
$ bundle exec rake db:migrate:up
$ foreman start
$ open http://127.0.0.1:5000

Heroku - The Old Way

$ export DEPLOY=production/staging/you
$ heroku create -r $DEPLOY -s cedar
$ heroku addons:add redistogo -r $DEPLOY
$ heroku addons:add heroku-postgresql:dev -r $DEPLOY
$ heroku config:set -r $DEPLOY OAUTH_PROVIDER=...
$ heroku config:set -r $DEPLOY <auth provider tokens>=...
$ heroku config:set -r $DEPLOY GRAPHITE_URL=...
$ heroku config:set -r $DEPLOY METRICS_UPDATE_INTERVAL=1h
$ heroku config:set -r $DEPLOY SESSION_SECRET...
$ heroku config:set -r $DEPLOY RAKE_ENV=production
$ git push $DEPLOY master
$ heroku run -r $DEPLOY bundle exec rake db:migrate:up
$ heroku scale -r $DEPLOY web=1
$ heroku open -r $DEPLOY

Heroku - The Easy Way

Deploy

Upgrades

Upgrades are typically performed by updating your in-place copy of the Descartes checkout. If you are using a third-party package, please refer to their upgrade documentation.

Migrations

Database upgrades (or downgrades) should use the built-in rake migration targets. For upgrading to the newest version in your development or non-Heroku production environment:

$ bundle exec rake db:migrate:up

If for some reason you need to downgrade to a previous migration target, make sure to set the VERSION number:

$ bundle exec VERSION=3 rake db:migrate:to

If you're running on Heroku, simply prefix the aforementioned commands with heroku run (and any other relevant options).

License

Descartes is distributed under the MIT license. Third-party software libraries included with this project are distributed under their respective licenses.