XPRMNTL Dashboard.js
Dashboard component of the XPRMNTL Experiments as a Service product
Contents
Features
The XPRMNTL dashboard is a UI for the API, which allows you to:
- Select Github repositories to add to Experiments
- 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:createCreated http://random-thing-23.herokuapp.com/ | git@heroku.com: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 git@heroku.com: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)
- This url is the root of your application. It is used for OAuth on the server and the
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 yourBASE_URL
+ "/auth/github/callback"
- The OAuth ClientID obtained from github.com. When it asks for your homepage URL, use the
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:
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.