xpr-dashboard

XPRMNTL Dashboard.js

Dashboard component of the XPRMNTL Experiments as a Service product

Contents

1. Features
2. Deployment

• Heroku
  • Automated
  • Manual
• Anywhere Else

1. API Documentation

• Coupling Endpoint
• Dashboard Endpoints

Features

The XPRMNTL dashboard is a UI for the API, which allows you to:

1. Select Github repositories to add to Experiments
2. Modify experiment configuration

The current implementation requires a Github Organization with repositories for the code and uses Github's OAuth2 strategies for authentication/authorization.

Deployment

Heroku

Automated

Manual

Create the Heroku repository

$ heroku apps:create
Created http://random-thing-23.herokuapp.com/ | [e-mail]:random-thing-23.git

Clone the repository

$ git clone https://github.com/XPRMNTL/xpr-dashboard

Set the necessary environment variables

$ heroku config:set GITHUB_CLIENT_ID=idhere GITHUB_CLIENT_SECRET=secrethere GITHUB_ORGS=comma,separated,values BASE_URL=http://random-thing-23.herokuapp.com -a random-thing-23

Git push to Heroku

$ git remote add heroku [e-mail]:random-thing-23.git
$ git push heroku master

Anywhere else

Deploy it however makes you happy.

Required environment variables:

• BASE_URL
  • This url is the root of your application. It is used for OAuth on the server and the <base> tag on the client.
  • Example: "http://appname.herokuapp.com" (no trailing slash)
• PORT
  • The port on which the Express.js app will listen.
• GITHUB_CLIENT_ID
  • The OAuth ClientID obtained from github.com. When it asks for your homepage URL, use the BASE_URL above. Authorization callback URL is your BASE_URL+ "/auth/github/callback"
• GITHUB_CLIENT_SECRET
  • The OAuth Client secret obtained from github.com
• GITHUB_ORGS
  • A comma-separated (no spaces) list of Github Organizations from which to pull repos for experiments
  • Example: "heroku,github,something"

Optional environment variables:

• ALLOW_NEW_EXP_DEFAULT
  • A boolean value which determines if client apps are allowed to set the default value for new experiments
  • Default: false

Services required for localdev

• local mongodb server
• local redis-server (can't save github auth session without it)

API Documentation

There are two endpoint groups of the API. There are the Dashboard endpoints, which are used internally by this dashboard, and the Coupling endpoint, which is what your experimenting apps will use.

Coupling Endpoint

The Coupling endpoint is the way that applications "announce":

• What app it is (devKey)
• What experiments it is using
• Which reference it's coming from (optional)
• Shared Experiments information (if applicable)
  • Which data it is sharing (devKey)
  • Which experiments that share us using

And receive back:

• The app and shared experiment configurations

Example

Request

Method:

POST

Headers:

  x-feature-key: asdf-qwer-asdf-qwer
  x-feature-key-shared: qwer-1234-qwer-1234

Body:

{
  "experiments": [
    {
      "name": "expName1",
      "default": true
    }
  ],
  "reference": "local",
  "shared": {
    "experiments" : [
      {
        "name" : "sharedExp1",
        "default": false,
        "description": "Here's my description. You likey? String"
      }
    ]
  }
}

Explanation

Method:

• POST currently required.

Headers:

• x-feature-key - This id the devKey assigned to the application. It is generated by adding an app via the dashboard.
• x-feature-key-shared - This (optional) id is the devKey assigned to the application you're using as your "shared" set of configurations.

Body:

• experiments - An array of experiment objects. If not present, this is a read-only request.
  • name - String name of the experiment. Any change creates a new one.
  • default - Boolean value default for the experiment. This is only read on experiment create.
  • description - (optional) Description of the experiment. This gets updated on any change.
• reference - (optional) String of which reference this request is for. Currently supported: "local" (for localhost), "int" (integration), "beta", "prod" (production).
• shared - (optional) Object of shared configuration.
  • experiments - (optional) Array of experiment objects (see body.experiments). If not present, this is a read-only request.

Dashboard Endpoints

This stuff is all used internally. In the future, this may be open to the external API, but it currently requires use of the Github OAuth, so external systems would need to be authenticated separately (user-based devkeys?). Totally doable, just not yet done.