Server that runs and renders Jupyter notebooks as interactive dashboards
JavaScript Jupyter Notebook Makefile CSS HTML Shell
Latest commit 4027607 Dec 4, 2016 @parente parente committed on GitHub Merge pull request #306 from parente/project-scope-readme
Some README cleanup
Permalink
Failed to load latest commit information.
app Merge pull request #297 from danielfrg/auth-auth0 Oct 19, 2016
bin Add missing admin script to package Nov 14, 2016
client Merge pull request #292 from jhpedemonte/260-prefix-url Oct 16, 2016
data/INTRO Update to use new metadata spec Jun 3, 2016
etc Fixes typo with proxied URL Sep 27, 2016
public Re-add moved favicon Jul 26, 2016
routes Adds section to README about proxy support Sep 26, 2016
test Fix race condition in decl widgets test case Nov 13, 2016
views Fix regression in title link nav Nov 14, 2016
.cfignore Improve NOTEBOOKS_DIR config support Apr 20, 2016
.dockerignore Avoid recursive make, excessive params May 18, 2016
.gitignore Improve NOTEBOOKS_DIR config support Apr 20, 2016
.npmignore Fix npmignore May 2, 2016
.travis.yml Remove build as an implicit dep May 18, 2016
CHANGELOG.md Update changelog for release 0.8.0 Aug 12, 2016
Dockerfile.installed Improve install-test Apr 20, 2016
Dockerfile.kernel Bump to 1.1.x kernel gateway Nov 12, 2016
Dockerfile.server Remove build as an implicit dep May 18, 2016
Dockerfile.test [Issue 130] Move test script to `etc/scripts` Mar 22, 2016
LICENSE.md Metadata updates before first tag Feb 3, 2016
Makefile Improves support for running behind proxy Sep 26, 2016
README.md Use footnote syntax for reference Nov 24, 2016
app.js Improves support for running behind proxy Sep 26, 2016
config.json Comments out TRUST_PROXY config Sep 26, 2016
gulpfile.js Improves support for running behind proxy Sep 26, 2016
package.json Add missing admin script to package Nov 14, 2016

README.md

npm version Build
Status Google
Group

Jupyter Dashboards Server

A NodeJS application that can display Jupyter notebooks as dynamic dashboards outside of the Jupyter Notebook server.

Dashboards server screenshot

The Jupyter Incubator Dashboards effort covers:

  1. Arranging notebook outputs in a grid- or report-like layout
  2. Bundling notebooks and associated assets for deployment as dashboards
  3. Serving notebook-defined dashboards as standalone web apps

This repository focuses on (3) above, while jupyter-incubator/dashboards handles (1) and jupyter-incubator/dashboards_bundlers implements (2).

See https://github.com/jupyter-incubator/dashboards/wiki for an overview of the entire dashboard incubation effort.

What it Gives You

  • Ability to run some Jupyter notebooks as standalone dashboard applications [1]
  • Ability to navigate a list of multiple notebooks and select one to run as a dashboard
  • Optional shared login to secure access to the dashboard server
  • Ability to add custom authentication mechanisms using the Passport middleware for Node.js
  • An API for POSTing notebooks to the server at runtime with optional authentication (/_api/notebooks)

The qualification in [1] stems from the fact that supporting one-click deploy of notebooks with arbitrary JavaScript and kernel dependencies is a "Really Hard Problem." We've invested effort in getting these dashboard, visualization, and widget libraries working in the dashboard server.

  • jupyter_dashboards 0.6.x
  • jupyter_dashboards_bundlers 0.8.x
  • ipywidgets 5.2.x
  • jupyter_declarativewidgets 0.6.x
  • matplotlib 1.5.x
  • Bokeh 0.11.x
  • Plotly 1.9.x

If you try another library and find that it does not work in the dashboard server, see the wiki page about Widget Support below for steps you might take to resolve the problem.

Install it

Install Node 5.x and npm 3.5.x. Use npm to install the jupyter-dashboards-server package.

npm install -g jupyter-dashboards-server

You can then run the dashboard server from the command line. See the next section about how to install and configure the other prerequisite components.

# shows a list of all nconf options
jupyter-dashboards-server --help

# runs the server pointing to a public kernel gateway
jupyter-dashboards-server --KERNEL_GATEWAY_URL=http://my.gateway.com/

# runs the server pointing to a kernel gateway that requires token auth
export KG_AUTH_TOKEN='somesecretinenvironment'
jupyter-dashboards-server --KERNEL_GATEWAY_URL=http://my.gateway.com/

Run It

The dashboard server is meant to support the layout-bundler-deploy workflow described on the project overview page. This workflow requires multiple components working in concert.

Minimal dashboard app deployment diagram

To bring all of these pieces together, you can start with the recipes in the jupyter-incubator/dashboards_setup repo. (We'll gladly take PRs that reduce the complexity of getting everything set up!)

Alternatively, you can clone this git repository and build the Docker images we use for development in order to run the demos in etc/notebooks. After setting up Docker (e.g. using docker-machine), run the following and then visit http://<your docker host ip>:3000.

make build
make examples
make demo-container

Run Behind a Proxy

The dashboards server can be run behind a reverse proxy. In order to do so, you will need to set the following options as command line args or in environment vars.

  • TRUST_PROXY - The simple option is to just set this to true. However, if you require further configuration on which requests to trust, this option can also take values as specified by the Express documentation.
  • BASE_URL - Specify the base URL (prefix) at which the dashboards server will run. The server supports two options here: passing the prefix along with the request or stripping the prefix off the request.

For example:

# allow proxying of "http://proxy_host/db/..." to "http://dashboards_host/db/..."
jupyter-dashboards-server --TRUST_PROXY=true --BASE_URL=/db --KERNEL_GATEWAY_URL=http://my.gateway.com/

# allow proxying of "http://proxy_host/db/..." to "http://dashboards_host/..."
jupyter-dashboards-server --TRUST_PROXY=true --BASE_URL='[/db]' --KERNEL_GATEWAY_URL=http://my.gateway.com/

Develop It

To setup a development environment, install these minimum versions on your host machine.

  • Node 5.5.0
  • npm 3.5.3
  • gulp 3.9.0
  • Docker 1.9.1

With these installed, you can use the make dev-* targets. Run make help to see the full gamut of targets and options. See the next few sections for the most common patterns.

Setup

# re-run if the Dockerfile.kernel changes
make kernel-gateway-image
# re-run if package.json changes
make dev-install
# run if you want to try the preliminary jupyter-incubator/declarativewidgets support
make examples

Dashboard Server w/ Auto Restart

# uses gulp:watch to restart on any changes
make dev
# mac shortcut for visiting URL in a browser
open http://127.0.0.1:3000

Dashboard Server w/ Auto Restart and Debug Console Logging

make dev-logging
# mac shortcut for visiting URL in a browser
open http://127.0.0.1:3000

Dashboard Server w/ Auto Restart and Remote Debugging

npm install -g node-inspector
make dev-debug
# a browser tab should open with the debugger visible
# refresh if it errors: the server might not be running yet

Dashboard Server w/ Auto Restart and Form Auth

make dev USERNAME=admin PASSWORD=password
# mac shortcut for visiting URL in a browser
open http://127.0.0.1:3000

See the Authentication wiki page for information about configuring alternative authentication mechanisms.

Dashboard Server w/ Auto Restart and Self-Signed HTTPS Certificate

make certs
make dev HTTPS_KEY_FILE=certs/server.pem HTTPS_CERT_FILE=certs/server.pem
# mac shortcut for visiting URL in a browser
open https://127.0.0.1:3001

Dashboard Server Tests

# unit tests
make test
# backend integration tests
make integration-test
# installation tests
make install-test

Technical Details

See the wiki attached to this project for additional technical details including the server API, authentication plugins, adding support for new widgets, and more.