release 0.8.1

remove bower

.bowerrc

@@ -1,3 +0,0 @@
-{
-  "directory": "share/jupyter/hub/static/components"
-}

.coveragerc

@@ -1,4 +1,17 @@
 [run]
+branch = False
 omit =
     jupyterhub/tests/*
     jupyterhub/alembic/*
+
+[report]
+exclude_lines =
+    if self.debug:
+    pragma: no cover
+    raise NotImplementedError
+    if __name__ == .__main__.:
+ignore_errors = True
+omit =
+    jupyterhub/tests/*
+    jupyterhub/alembic/*
+    */site-packages/*

.dockerignore

@@ -4,3 +4,7 @@ jupyterhub_cookie_secret
 jupyterhub.sqlite
 jupyterhub_config.py
 node_modules
+docs
+.git
+dist
+build

.flake8

@@ -0,0 +1,25 @@
+[flake8]
+# Ignore style and complexity
+# E: style errors
+# W: style warnings
+# C: complexity
+# F401: module imported but unused
+# F403: import *
+# F811: redefinition of unused `name` from line `N`
+# F841: local variable assigned but never used
+# E402: module level import not at top of file
+# I100: Import statements are in the wrong order
+# I101: Imported names are in the wrong order. Should be
+ignore = E, C, W, F401, F403, F811, F841, E402, I100, I101
+
+exclude =
+    .cache,
+    .github,
+    docs,
+    examples,
+    jupyterhub/alembic*,
+    onbuild,
+    scripts,
+    share,
+    tools,
+    setup.py

.gitignore

@@ -3,9 +3,10 @@ node_modules
 *~
 .cache
 .DS_Store
-build
+/build
 dist
 docs/_build
+docs/build
 docs/source/_static/rest-api
 .ipynb_checkpoints
 # ignore config file at the top-level of the repo

.travis.yml

@@ -1,22 +1,71 @@
-# http://travis-ci.org/#!/jupyter/jupyterhub
 language: python
 sudo: false
+cache:
+  - pip
 python:
-    - 3.6-dev
-    - 3.5
-    - 3.4
-    - 3.3
+  - nightly
+  - 3.6
+  - 3.5
+  - 3.4
+env:
+  global:
+    - ASYNC_TEST_TIMEOUT=15
+services:
+  - postgres
+  - docker
+
+# installing dependencies
 before_install:
-    - npm install
-    - npm install -g configurable-http-proxy
-    - git clone --quiet --depth 1 https://github.com/minrk/travis-wheels travis-wheels
+  - nvm install 6; nvm use 6
+  - npm install
+  - npm install -g configurable-http-proxy
+  - |
+    if [[ $JUPYTERHUB_TEST_DB_URL == mysql* ]]; then
+      unset MYSQL_UNIX_PORT
+      DB=mysql bash ci/docker-db.sh
+      DB=mysql bash ci/init-db.sh
+      pip install 'mysql-connector<2.2'
+    elif [[ $JUPYTERHUB_TEST_DB_URL == postgresql* ]]; then
+      DB=postgres bash ci/init-db.sh
+      pip install psycopg2
+    fi
 install:
-    - pip install --pre -f travis-wheels/wheelhouse -r dev-requirements.txt .
+  - pip install -U pip
+  - pip install --pre -r dev-requirements.txt .
+  - pip freeze
+
+# running tests
 script:
-    - travis_retry py.test --cov jupyterhub jupyterhub/tests -v
+  - |
+    if [[ ! -z "$JUPYTERHUB_TEST_DB_URL" ]]; then
+      # if testing upgrade-db, run `jupyterhub token` with 0.7
+      # to initialize an old db. Used in upgrade-tests
+      export JUPYTERHUB_TEST_UPGRADE_DB_URL=${JUPYTERHUB_TEST_DB_URL}_upgrade
+      # use virtualenv instead of venv because venv doesn't work here
+      python -m pip install virtualenv
+      python -m virtualenv old-hub-env
+      ./old-hub-env/bin/python -m pip install jupyterhub==0.7.2 psycopg2 'mysql-connector<2.2'
+      ./old-hub-env/bin/jupyterhub token kaylee \
+        --JupyterHub.db_url=$JUPYTERHUB_TEST_UPGRADE_DB_URL \
+        --Authenticator.whitelist="{'kaylee'}" \
+        --JupyterHub.authenticator_class=jupyterhub.auth.Authenticator
+    fi
+  - pytest -v --maxfail=2 --cov=jupyterhub jupyterhub/tests
 after_success:
-    - codecov
+  - codecov
+
 matrix:
+  fast_finish: true
   include:
-    - python: 3.5
-      env: JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://127.0.0.1.xip.io:8000
+    - python: 3.6
+      env: JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://localhost.jovyan.org:8000
+    - python: 3.6
+      env:
+        - MYSQL_HOST=127.0.0.1
+        - MYSQL_TCP_PORT=13306
+        - JUPYTERHUB_TEST_DB_URL=mysql+mysqlconnector://root@127.0.0.1:$MYSQL_TCP_PORT/jupyterhub
+    - python: 3.6
+      env:
+        - JUPYTERHUB_TEST_DB_URL=postgresql://postgres@127.0.0.1/jupyterhub
+  allow_failures:
+    - python: nightly

CONTRIBUTING.md

@@ -1,3 +1,3 @@
 # Contributing
 
-We mainly follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+Welcome! As a [Jupyter](https://jupyter.org) project, we follow the [Jupyter contributor guide](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).

Dockerfile

@@ -42,7 +42,9 @@ ENV LANG C.UTF-8
 RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-4.2.12-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
     echo 'd0c7c71cc5659e54ab51f2005a8d96f3 */tmp/miniconda.sh' | md5sum -c - && \
     bash /tmp/miniconda.sh -f -b -p /opt/conda && \
-    /opt/conda/bin/conda install --yes -c conda-forge python=3.5 sqlalchemy tornado jinja2 traitlets requests pip nodejs configurable-http-proxy && \
+    /opt/conda/bin/conda install --yes -c conda-forge \
+      python=3.5 sqlalchemy tornado jinja2 traitlets requests pip pycurl \
+      nodejs configurable-http-proxy && \
     /opt/conda/bin/pip install --upgrade pip && \
     rm /tmp/miniconda.sh
 ENV PATH=/opt/conda/bin:$PATH
@@ -50,7 +52,8 @@ ENV PATH=/opt/conda/bin:$PATH
 ADD . /src/jupyterhub
 WORKDIR /src/jupyterhub
 
-RUN python setup.py js && pip install . && \
+RUN npm install --unsafe-perm && \
+    pip install . && \
     rm -rf $PWD ~/.cache ~/.npm
 
 RUN mkdir -p /srv/jupyterhub/

MANIFEST.in

@@ -1,7 +1,7 @@
 include README.md
 include COPYING.md
 include setupegg.py
-include bower.json
+include bower-lite
 include package.json
 include *requirements.txt
 include Dockerfile
@@ -10,18 +10,21 @@ graft onbuild
 graft jupyterhub
 graft scripts
 graft share
+graft singleuser
+graft ci
 
 # Documentation
 graft docs
 prune docs/node_modules
 
 # prune some large unused files from components
-prune share/jupyter/hub/static/components/bootstrap/css
-exclude share/jupyter/hub/static/components/components/fonts/*.svg
-exclude share/jupyter/hub/static/components/bootstrap/less/*.js
-exclude share/jupyter/hub/static/components/font-awesome/css
+prune share/jupyter/hub/static/components/bootstrap/dist/css
+exclude share/jupyter/hub/static/components/bootstrap/dist/fonts/*.svg
+prune share/jupyter/hub/static/components/font-awesome/css
+prune share/jupyter/hub/static/components/font-awesome/scss
 exclude share/jupyter/hub/static/components/font-awesome/fonts/*.svg
-exclude share/jupyter/hub/static/components/jquery/*migrate*.js
+prune share/jupyter/hub/static/components/jquery/external
+prune share/jupyter/hub/static/components/jquery/src
 prune share/jupyter/hub/static/components/moment/lang
 prune share/jupyter/hub/static/components/moment/min
 

README.md

@@ -1,82 +1,74 @@
-**[Technical overview](#technical-overview)** |
-**[Prerequisites](#prerequisites)** |
+**[Technical Overview](#technical-overview)** |
 **[Installation](#installation)** |
-**[Running the Hub Server](#running-the-hub-server)** |
 **[Configuration](#configuration)** |
 **[Docker](#docker)** |
 **[Contributing](#contributing)** |
 **[License](#license)** |
-**[Getting help](#getting-help)**
+**[Help and Resources](#help-and-resources)**
+
 
 # [JupyterHub](https://github.com/jupyterhub/jupyterhub)
 
+
+[![PyPI](https://img.shields.io/pypi/v/jupyterhub.svg)](https://pypi.python.org/pypi/jupyterhub)
+[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
+[![Documentation Status](http://readthedocs.org/projects/jupyterhub/badge/?version=0.7.2)](http://jupyterhub.readthedocs.io/en/0.7.2/?badge=0.7.2)
 [![Build Status](https://travis-ci.org/jupyterhub/jupyterhub.svg?branch=master)](https://travis-ci.org/jupyterhub/jupyterhub)
 [![Circle CI](https://circleci.com/gh/jupyterhub/jupyterhub.svg?style=shield&circle-token=b5b65862eb2617b9a8d39e79340b0a6b816da8cc)](https://circleci.com/gh/jupyterhub/jupyterhub)
 [![codecov.io](https://codecov.io/github/jupyterhub/jupyterhub/coverage.svg?branch=master)](https://codecov.io/github/jupyterhub/jupyterhub?branch=master)
-"
-[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
-"
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+[![Google Group](https://img.shields.io/badge/google-group-blue.svg)](https://groups.google.com/forum/#!forum/jupyter)
 
 With [JupyterHub](https://jupyterhub.readthedocs.io) you can create a
 **multi-user Hub** which spawns, manages, and proxies multiple instances of the
-single-user [Jupyter notebook *(IPython notebook)* ](https://jupyter-notebook.readthedocs.io) server.
+single-user [Jupyter notebook (IPython notebook)](https://jupyter-notebook.readthedocs.io)
+server.
 
-JupyterHub provides **single-user notebook servers to many users**. For example,
-JupyterHub could serve notebooks to a class of students, a corporate
-workgroup, or a science research group.
-
-by [Project Jupyter](https://jupyter.org)
-
-----
+[Project Jupyter](https://jupyter.org) created JupyterHub to support many
+users. The Hub can offer notebook servers to a class of students, a corporate
+data science workgroup, a scientific research project, or a high performance
+computing group.
 
 ## Technical overview
+
 Three main actors make up JupyterHub:
 
 - multi-user **Hub** (tornado process)
 - configurable http **proxy** (node-http-proxy)
 - multiple **single-user Jupyter notebook servers** (Python/IPython/tornado)
 
-JupyterHub's basic principles for operation are:
+Basic principles for operation are:
 
-- Hub spawns a proxy
-- Proxy forwards all requests to Hub by default
-- Hub handles login, and spawns single-user servers on demand
-- Hub configures proxy to forward url prefixes to the single-user servers
+- Hub spawns a proxy.
+- Proxy forwards all requests to Hub by default.
+- Hub handles login, and spawns single-user servers on demand.
+- Hub configures proxy to forward url prefixes to the single-user notebook
+  servers.
 
 JupyterHub also provides a
 [REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
-for administration of the Hub and users.
+for administration of the Hub and its users.
 
-----
+## Installation
 
-## Prerequisites
-Before installing JupyterHub, you need:
+### Check prerequisites
 
-- [Python](https://www.python.org/downloads/) 3.3 or greater
+A Linux/Unix based system with the following:
 
-  An understanding of using [`pip`](https://pip.pypa.io/en/stable/) for installing
-  Python packages is recommended.
-
-- [nodejs/npm](https://www.npmjs.com/)
-
-  [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node), which is available from your
-  package manager. For example, install on Linux (Debian/Ubuntu) using:
+- [Python](https://www.python.org/downloads/) 3.4 or greater
+- [nodejs/npm](https://www.npmjs.com/) Install a recent version of
+  [nodejs/npm](https://docs.npmjs.com/getting-started/installing-node)
+  For example, install it on Linux (Debian/Ubuntu) using:
 
       sudo apt-get install npm nodejs-legacy
 
-  (The `nodejs-legacy` package installs the `node` executable and is currently
-  required for npm to work on Debian/Ubuntu.)
+  The `nodejs-legacy` package installs the `node` executable and is currently
+  required for npm to work on Debian/Ubuntu.
 
 - TLS certificate and key for HTTPS communication
-
 - Domain name
 
-Before running the single-user notebook servers (which may be on the same system as the Hub or not):
+### Install packages
 
-- [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html) version 4 or greater
-
-## Installation
 JupyterHub can be installed with `pip`, and the proxy with `npm`:
 
 ```bash
@@ -85,84 +77,108 @@ pip3 install jupyterhub
 ```
 
 If you plan to run notebook servers locally, you will need to install the
-Jupyter notebook:
+[Jupyter notebook](https://jupyter.readthedocs.io/en/latest/install.html)
+package:
 
     pip3 install --upgrade notebook
 
-## Running the Hub server
+### Run the Hub server
+
 To start the Hub server, run the command:
 
     jupyterhub
 
-Visit `https://localhost:8000` in your browser, and sign in with your unix credentials.
+Visit `https://localhost:8000` in your browser, and sign in with your unix
+PAM credentials.
 
-To allow multiple users to sign into the server, you will need to
+*Note*: To allow multiple users to sign into the server, you will need to
 run the `jupyterhub` command as a *privileged user*, such as root.
 The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
-describes how to run the server as a *less privileged user*, which requires more
-configuration of the system.
-
-----
+describes how to run the server as a *less privileged user*, which requires
+more configuration of the system.
 
 ## Configuration
-The [getting started document](docs/source/getting-started.md) contains the
-basics of configuring a JupyterHub deployment.
 
-The JupyterHub **tutorial** provides a video and documentation that explains and illustrates the fundamental steps for installation and configuration. [Repo](https://github.com/jupyterhub/jupyterhub-tutorial)
-| [Tutorial documentation](http://jupyterhub-tutorial.readthedocs.io/en/latest/)
+The [Getting Started](http://jupyterhub.readthedocs.io/en/latest/getting-started/index.html) section of the
+documentation explains the common steps in setting up JupyterHub.
 
-#### Generate a default configuration file
-Generate a default config file:
+The [**JupyterHub tutorial**](https://github.com/jupyterhub/jupyterhub-tutorial)
+provides an in-depth video and sample configurations of JupyterHub.
+
+### Create a configuration file
+
+To generate a default config file with settings and descriptions:
 
     jupyterhub --generate-config
 
-#### Customize the configuration, authentication, and process spawning
-Spawn the server on ``10.0.1.2:443`` with **https**:
+### Start the Hub
+
+To start the Hub on a specific url and port ``10.0.1.2:443`` with **https**:
 
     jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
 
-The authentication and process spawning mechanisms can be replaced,
-which should allow plugging into a variety of authentication or process control environments.
-Some examples, meant as illustration and testing of this concept:
+### Authenticators
 
-- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator)
-- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner)
+| Authenticator                                                               | Description                                       |
+| --------------------------------------------------------------------------- | ------------------------------------------------- |
+| PAMAuthenticator                                                            | Default, built-in authenticator                   |
+| [OAuthenticator](https://github.com/jupyterhub/oauthenticator)              | OAuth + JupyterHub Authenticator = OAuthenticator |
+| [ldapauthenticator](https://github.com/jupyterhub/ldapauthenticator)        | Simple LDAP Authenticator Plugin for JupyterHub   |
+| [kdcAuthenticator](https://github.com/bloomberg/jupyterhub-kdcauthenticator)| Kerberos Authenticator Plugin for JupyterHub      |
 
-----
+### Spawners
+
+| Spawner                                                        | Description                                                                |
+| -------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| LocalProcessSpawner                                            | Default, built-in spawner starts single-user servers as local processes    |
+| [dockerspawner](https://github.com/jupyterhub/dockerspawner)   | Spawn single-user servers in Docker containers                             |
+| [kubespawner](https://github.com/jupyterhub/kubespawner)       | Kubernetes spawner for JupyterHub                                          |
+| [sudospawner](https://github.com/jupyterhub/sudospawner)       | Spawn single-user servers without being root                               |
+| [systemdspawner](https://github.com/jupyterhub/systemdspawner) | Spawn single-user notebook servers using systemd                           |
+| [batchspawner](https://github.com/jupyterhub/batchspawner)     | Designed for clusters using batch scheduling software                      |
+| [wrapspawner](https://github.com/jupyterhub/wrapspawner)       | WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners |
 
 ## Docker
-A starter [docker image for JupyterHub](https://hub.docker.com/r/jupyterhub/jupyterhub/) gives a baseline deployment of JupyterHub.
 
-**Important:** This `jupyterhub/jupyterhub` image contains only the Hub itself, with no configuration. In general, one needs
-to make a derivative image, with at least a `jupyterhub_config.py` setting up an Authenticator and/or a Spawner. To run the
-single-user servers, which may be on the same system as the Hub or not, Jupyter Notebook version 4 or greater must be installed.
+A starter [**docker image for JupyterHub**](https://hub.docker.com/r/jupyterhub/jupyterhub/)
+gives a baseline deployment of JupyterHub using Docker.
+
+**Important:** This `jupyterhub/jupyterhub` image contains only the Hub itself,
+with no configuration. In general, one needs to make a derivative image, with
+at least a `jupyterhub_config.py` setting up an Authenticator and/or a Spawner.
+To run the single-user servers, which may be on the same system as the Hub or
+not, Jupyter Notebook version 4 or greater must be installed.
 
-#### Starting JupyterHub with docker
 The JupyterHub docker image can be started with the following command:
 
     docker run -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
 
-This command will create a container named `jupyterhub` that you can **stop and resume** with `docker stop/start`.
+This command will create a container named `jupyterhub` that you can
+**stop and resume** with `docker stop/start`.
 
-The Hub service will be listening on all interfaces at port 8000, which makes this a good choice for **testing JupyterHub on your desktop or laptop**.
+The Hub service will be listening on all interfaces at port 8000, which makes
+this a good choice for **testing JupyterHub on your desktop or laptop**.
 
-If you want to run docker on a computer that has a public IP then you should (as in MUST) **secure it with ssl** by
-adding ssl options to your docker configuration or using a ssl enabled proxy.
+If you want to run docker on a computer that has a public IP then you should
+(as in MUST) **secure it with ssl** by adding ssl options to your docker
+configuration or by using a ssl enabled proxy.
 
 [Mounting volumes](https://docs.docker.com/engine/userguide/containers/dockervolumes/) will
 allow you to **store data outside the docker image (host system) so it will be persistent**, even when you start
 a new image.
 
 The command `docker exec -it jupyterhub bash` will spawn a root shell in your docker
-container. You can **use the root shell to create system users in the container**. These accounts will be used for authentication
-in JupyterHub's default configuration.
-
-----
+container. You can **use the root shell to create system users in the container**.
+These accounts will be used for authentication in JupyterHub's default configuration.
 
 ## Contributing
-If you would like to contribute to the project, please read our [contributor documentation](http://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html) and the [`CONTRIBUTING.md`](CONTRIBUTING.md).
 
-For a **development install**, clone the [repository](https://github.com/jupyterhub/jupyterhub) and then install from source:
+If you would like to contribute to the project, please read our
+[contributor documentation](http://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html)
+and the [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+For a **development install**, clone the [repository](https://github.com/jupyterhub/jupyterhub)
+and then install from source:
 
 ```bash
 git clone https://github.com/jupyterhub/jupyterhub
@@ -170,41 +186,68 @@ cd jupyterhub
 pip3 install -r dev-requirements.txt -e .
 ```
 
-If the `pip3 install` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional JavaScript dependencies:
+If the `pip3 install` command fails and complains about `lessc` being
+unavailable, you may need to explicitly install some additional JavaScript
+dependencies:
 
     npm install
 
 This will fetch client-side JavaScript dependencies necessary to compile CSS.
 
-You may also need to manually update JavaScript and CSS after some development updates, with:
+You may also need to manually update JavaScript and CSS after some development
+updates, with:
 
 ```bash
 python3 setup.py js    # fetch updated client-side js
 python3 setup.py css   # recompile CSS from LESS sources
 ```
 
-We use [pytest](http://doc.pytest.org/en/latest/) for testing. To run tests:
+We use [pytest](http://doc.pytest.org/en/latest/) for **running tests**:
 
 ```bash
 pytest jupyterhub/tests
 ```
 
-----
+### A note about platform support
+
+JupyterHub is supported on Linux/Unix based systems.
+
+JupyterHub officially **does not** support Windows. You may be able to use
+JupyterHub on Windows if you use a Spawner and Authenticator that work on
+Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not
+be accepted, and the test suite will not run on Windows. Small patches that fix
+minor Windows compatibility issues (such as basic installation) **may** be accepted,
+however. For Windows-based systems, we would recommend running JupyterHub in a
+docker container or Linux VM.
+
+[Additional Reference:](http://www.tornadoweb.org/en/stable/#installation) Tornado's documentation on Windows platform support
+
 ## License
+
 We use a shared copyright model that enables all contributors to maintain the
 copyright on their contributions.
 
 All code is licensed under the terms of the revised BSD license.
 
-## Getting help
-We encourage you to ask questions on the [mailing list](https://groups.google.com/forum/#!forum/jupyter),
-and you may participate in development discussions or get live help on [Gitter](https://gitter.im/jupyterhub/jupyterhub).
+## Help and resources
+
+We encourage you to ask questions on the [Jupyter mailing list](https://groups.google.com/forum/#!forum/jupyter).
+To participate in development discussions or get help, talk with us on
+our JupyterHub [Gitter](https://gitter.im/jupyterhub/jupyterhub) channel.
 
-## Resources
 - [Reporting Issues](https://github.com/jupyterhub/jupyterhub/issues)
-- JupyterHub tutorial | [Repo](https://github.com/jupyterhub/jupyterhub-tutorial)
-  | [Tutorial documentation](http://jupyterhub-tutorial.readthedocs.io/en/latest/)
+- [JupyterHub tutorial](https://github.com/jupyterhub/jupyterhub-tutorial)
 - [Documentation for JupyterHub](http://jupyterhub.readthedocs.io/en/latest/) | [PDF (latest)](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf) | [PDF (stable)](https://media.readthedocs.org/pdf/jupyterhub/stable/jupyterhub.pdf)
 - [Documentation for JupyterHub's REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
 - [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) | [PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)
 - [Project Jupyter website](https://jupyter.org)
+
+---
+
+**[Technical Overview](#technical-overview)** |
+**[Installation](#installation)** |
+**[Configuration](#configuration)** |
+**[Docker](#docker)** |
+**[Contributing](#contributing)** |
+**[License](#license)** |
+**[Help and Resources](#help-and-resources)**

bower-lite

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+"""
+bower-lite
+
+Since Bower's on its way out,
+stage frontend dependencies from node_modules into components
+"""
+
+import json
+import os
+from os.path import join
+import shutil
+
+HERE = os.path.abspath(os.path.dirname(__file__))
+
+
+components = join(HERE, "share", "jupyter", "hub", "static", "components")
+node_modules = join(HERE, "node_modules")
+
+if os.path.exists(components):
+    shutil.rmtree(components)
+os.mkdir(components)
+
+with open(join(HERE, 'package.json')) as f:
+    package_json = json.load(f)
+
+dependencies = package_json['dependencies']
+for dep in dependencies:
+    src = join(node_modules, dep)
+    dest = join(components, dep)
+    print("%s -> %s" % (src, dest))
+    shutil.copytree(src, dest)

bower.json

@@ -1,11 +0,0 @@
-{
-  "name": "jupyterhub-deps",
-  "version": "0.0.0",
-  "dependencies": {
-    "bootstrap": "components/bootstrap#~3.1",
-    "font-awesome": "components/font-awesome#~4.1",
-    "jquery": "components/jquery#~2.0",
-    "moment": "~2.7",
-    "requirejs": "~2.1"
-  }
-}

ci/docker-db.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# source this file to setup postgres and mysql
+# for local testing (as similar as possible to docker)
+
+set -e
+
+export MYSQL_HOST=127.0.0.1
+export MYSQL_TCP_PORT=${MYSQL_TCP_PORT:-13306}
+export PGHOST=127.0.0.1
+NAME="hub-test-$DB"
+DOCKER_RUN="docker run --rm -d --name $NAME"
+
+docker rm -f "$NAME" 2>/dev/null || true
+
+case "$DB" in
+"mysql")
+  RUN_ARGS="-e MYSQL_ALLOW_EMPTY_PASSWORD=1 -p $MYSQL_TCP_PORT:3306 mysql:5.7"
+  CHECK="mysql --host $MYSQL_HOST --port $MYSQL_TCP_PORT --user root -e \q"
+  ;;
+"postgres")
+  RUN_ARGS="-p 5432:5432 postgres:9.5"
+  CHECK="psql --user postgres -c \q"
+  ;;
+*)
+  echo '$DB must be mysql or postgres'
+  exit 1
+esac
+
+$DOCKER_RUN $RUN_ARGS
+
+echo -n "waiting for $DB "
+for i in {1..60}; do
+  if $CHECK; then
+    echo 'done'
+    break
+  else
+    echo -n '.'
+    sleep 1
+  fi
+done
+$CHECK
+
+
+echo -e "
+Set these environment variables:
+
+    export MYSQL_HOST=127.0.0.1
+    export MYSQL_TCP_PORT=$MYSQL_TCP_PORT
+    export PGHOST=127.0.0.1
+"

ci/init-db.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# initialize jupyterhub databases for testing
+
+set -e
+
+MYSQL="mysql --user root --host $MYSQL_HOST --port $MYSQL_TCP_PORT -e "
+PSQL="psql --user postgres -c "
+
+case "$DB" in
+"mysql")
+  EXTRA_CREATE='CHARACTER SET utf8 COLLATE utf8_general_ci'
+  SQL="$MYSQL"
+  ;;
+"postgres")
+  SQL="$PSQL"
+  ;;
+*)
+  echo '$DB must be mysql or postgres'
+  exit 1
+esac
+
+set -x
+
+$SQL 'DROP DATABASE jupyterhub;' 2>/dev/null || true
+$SQL "CREATE DATABASE jupyterhub ${EXTRA_CREATE};"
+$SQL 'DROP DATABASE jupyterhub_upgrade;' 2>/dev/null || true
+$SQL "CREATE DATABASE jupyterhub_upgrade ${EXTRA_CREATE};"

dev-requirements.txt

@@ -1,7 +1,9 @@
 -r requirements.txt
 mock
 codecov
+cryptography
 pytest-cov
+pytest-tornado
 pytest>=2.8
 notebook
 requests-mock

docs/environment.yml

@@ -3,14 +3,17 @@ channels:
   - conda-forge
 dependencies:
 - nodejs
-- python=3
+- python=3.5
+- alembic
 - jinja2
 - pamela
 - requests
 - sqlalchemy>=1
 - tornado>=4.1
 - traitlets>=4.1
-- sphinx>=1.3.6
+- sphinx>=1.4, !=1.5.4
 - sphinx_rtd_theme
 - pip:
-    - recommonmark==0.4.0
+  - jupyter_alabaster_theme
+  - python-oauth2
+  - recommonmark==0.4.0

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyterhub-docs-build",
-  "version": "0.0.0",
+  "version": "0.8.0",
   "description": "build JupyterHub swagger docs",
   "scripts": {
     "rest-api": "bootprint openapi ./rest-api.yml source/_static/rest-api"
@@ -8,7 +8,7 @@
   "author": "",
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "bootprint": "^0.10.0",
-    "bootprint-openapi": "^0.17.0"
+    "bootprint": "^1.0.0",
+    "bootprint-openapi": "^1.0.0"
   }
 }

docs/requirements.txt

@@ -1,3 +1,3 @@
 -r ../requirements.txt
-sphinx>=1.3.6
-recommonmark==0.4.0
+sphinx>=1.4
+recommonmark==0.4.0

docs/rest-api.yml

@@ -3,7 +3,7 @@ swagger: '2.0'
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 0.7.0
+  version: 0.8.0dev
   license:
     name: BSD-3-Clause
 schemes:
@@ -203,6 +203,43 @@ paths:
           description: The user's notebook server has stopped
         '202':
           description: The user's notebook server has not yet stopped as it is taking a while to stop
+  /users/{name}/servers/{server_name}:
+    post:
+      summary: Start a user's single-user named-server notebook server
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+        - name: server_name
+          description: name given to a named-server
+          in: path
+          required: true
+          type: string
+      responses:
+        '201':
+          description: The user's notebook named-server has started
+        '202':
+          description: The user's notebook named-server has not yet started, but has been requested
+    delete:
+      summary: Stop a user's named-server
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+        - name: server_name
+          description: name given to a named-server
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The user's notebook named-server has stopped
+        '202':
+          description: The user's notebook named-server has not yet stopped as it is taking a while to stop
   /users/{name}/admin-access:
     post:
       summary: Grant admin access to this user's notebook server
@@ -215,6 +252,13 @@ paths:
       responses:
         '200':
           description: Sets a cookie granting the requesting administrator access to the user's notebook server
+  /user:
+    summary: Return authenticated user's model
+    description:
+    parameters:
+    responses:
+      '200':
+        description: The authenticated user's model is returned.
   /groups:
     get:
       summary: List groups
@@ -377,9 +421,38 @@ paths:
       responses:
         '200':
           description: Success
+  /authorizations/token:
+    post:
+      summary: Request a new API token
+      description: |
+        Request a new API token to use with the JupyterHub REST API.
+        If not already authenticated, username and password can be sent
+        in the JSON request body.
+        Logging in via this method is only available when the active Authenticator
+        accepts passwords (e.g. not OAuth).
+      parameters:
+        - name: username
+          in: body
+          required: false
+          type: string
+        - name: password
+          in: body
+          required: false
+          type: string
+      responses:
+        '200':
+          description: The new API token
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+                description: The new API token.
+        '403':
+          description: The user can not be authenticated.
   /authorizations/token/{token}:
     get:
-      summary: Identify a user from an API token
+      summary: Identify a user or service from an API token
       parameters:
       - name: token
         in: path
@@ -387,9 +460,9 @@ paths:
         type: string
       responses:
         '200':
-          description: The user identified by the API token
-          schema:
-            $ref: '#/definitions/User'
+          description: The user or service identified by the API token
+        '404':
+          description: A user or service is not found.
   /authorizations/cookie/{cookie_name}/{cookie_value}:
     get:
       summary: Identify a user from a cookie
@@ -408,6 +481,81 @@ paths:
           description: The user identified by the cookie
           schema:
             $ref: '#/definitions/User'
+        '404':
+          description: A user is not found.
+  /oauth2/authorize:
+    get:
+      summary: 'OAuth 2.0 authorize endpoint'
+      description: |
+        Redirect users to this URL to begin the OAuth process.
+        It is not an API endpoint.
+      parameters:
+        - name: client_id
+          description: The client id
+          in: query
+          required: true
+          type: string
+        - name: response_type
+          description: The response type (always 'code')
+          in: query
+          required: true
+          type: string
+        - name: state
+          description: A state string
+          in: query
+          required: false
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: query
+          required: true
+          type: string
+  /oauth2/token:
+    post:
+      summary: Request an OAuth2 token
+      description: |
+        Request an OAuth2 token from an authorization code.
+        This request completes the OAuth process.
+      consumes:
+        - application/x-www-form-urlencoded
+      parameters:
+        - name: client_id
+          description: The client id
+          in: form
+          required: true
+          type: string
+        - name: client_secret
+          description: The client secret
+          in: form
+          required: true
+          type: string
+        - name: grant_type
+          description: The grant type (always 'authorization_code')
+          in: form
+          required: true
+          type: string
+        - name: code
+          description: The code provided by the authorization redirect
+          in: form
+          required: true
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: form
+          required: true
+          type: string
+      responses:
+        '200':
+          description: JSON response including the token
+          schema:
+            type: object
+            properties:
+              access_token:
+                type: string
+                description: The new API token for the user
+              token_type:
+                type: string
+                description: Will always be 'Bearer'
   /shutdown:
     post:
       summary: Shutdown the Hub
@@ -419,10 +567,7 @@ paths:
         - name: servers
           in: body
           type: boolean
-          description: Whether users's notebook servers should be shutdown as well (default from Hub config)
-      responses:
-        '200':
-          description: Hub has shutdown
+          description: Whether users' notebook servers should be shutdown as well (default from Hub config)
 definitions:
   User:
     type: object

docs/source/api/app.rst

@@ -0,0 +1,16 @@
+=========================
+Application configuration
+=========================
+
+Module: :mod:`jupyterhub.app`
+=============================
+
+.. automodule:: jupyterhub.app
+
+.. currentmodule:: jupyterhub.app
+
+:class:`JupyterHub`
+-------------------
+
+.. autoconfigurable:: JupyterHub
+

docs/source/api/auth.rst

@@ -9,13 +9,20 @@ Module: :mod:`jupyterhub.auth`
 
 .. currentmodule:: jupyterhub.auth
 
+:class:`Authenticator`
+----------------------
 
-
-.. autoclass:: Authenticator
+.. autoconfigurable:: Authenticator
     :members:
 
-.. autoclass:: LocalAuthenticator
+:class:`LocalAuthenticator`
+---------------------------
+
+.. autoconfigurable:: LocalAuthenticator
     :members:
 
-.. autoclass:: PAMAuthenticator
+:class:`PAMAuthenticator`
+-------------------------
+
+.. autoconfigurable:: PAMAuthenticator
 

docs/source/api/index.rst

@@ -1,19 +1,21 @@
 .. _api-index:
 
-####################
- The JupyterHub API
-####################
+##################
+The JupyterHub API
+##################
 
 :Release: |release|
 :Date: |today|
 
 JupyterHub also provides a REST API for administration of the Hub and users.
-The documentation on `Using JupyterHub's REST API <../rest.html>`_ provides
+The documentation on `Using JupyterHub's REST API <../reference/rest.html>`_ provides
 information on:
 
-- Creating an API token
-- Adding tokens to the configuration file (optional)
-- Making an API request
+- what you can do with the API
+- creating an API token
+- adding API tokens to the config files
+- making an API request programmatically using the requests library
+- learning more about JupyterHub's API
 
 The same JupyterHub API spec, as found here, is available in an interactive form
 `here (on swagger's petstore) <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default>`__.
@@ -24,9 +26,12 @@ JupyterHub API Reference:
 
 .. toctree::
 
+    app
     auth
     spawner
+    proxy
     user
+    service
     services.auth
 
 

docs/source/api/proxy.rst

@@ -0,0 +1,23 @@
+=======
+Proxies
+=======
+
+Module: :mod:`jupyterhub.proxy`
+===============================
+
+.. automodule:: jupyterhub.proxy
+
+.. currentmodule:: jupyterhub.proxy
+
+:class:`Proxy`
+--------------
+
+.. autoconfigurable:: Proxy
+    :members:
+
+:class:`ConfigurableHTTPProxy`
+------------------------------
+
+.. autoconfigurable:: ConfigurableHTTPProxy
+    :members: debug, auth_token, check_running_interval, api_url, command
+

docs/source/api/service.rst

@@ -0,0 +1,17 @@
+========
+Services
+========
+
+Module: :mod:`jupyterhub.services.service`
+==========================================
+
+.. automodule:: jupyterhub.services.service
+
+.. currentmodule:: jupyterhub.services.service
+
+:class:`Service`
+----------------
+
+.. autoconfigurable:: Service
+    :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec
+

docs/source/api/services.auth.rst

@@ -1,5 +1,5 @@
 =======================
-Authenticating Services
+Services Authentication
 =======================
 
 Module: :mod:`jupyterhub.services.auth`
@@ -10,9 +10,32 @@ Module: :mod:`jupyterhub.services.auth`
 .. currentmodule:: jupyterhub.services.auth
 
 
-.. autoclass:: HubAuth
+:class:`HubAuth`
+----------------
+
+.. autoconfigurable:: HubAuth
     :members:
 
+:class:`HubOAuth`
+-----------------
+
+.. autoconfigurable:: HubOAuth
+    :members:
+
+
+:class:`HubAuthenticated`
+-------------------------
+
 .. autoclass:: HubAuthenticated
     :members:
 
+:class:`HubOAuthenticated`
+--------------------------
+
+.. autoclass:: HubOAuthenticated
+
+:class:`HubOAuthCallbackHandler`
+--------------------------------
+
+.. autoclass:: HubOAuthCallbackHandler
+

docs/source/api/spawner.rst

@@ -1,6 +1,6 @@
-==============
-   Spawners
-==============
+========
+Spawners
+========
 
 Module: :mod:`jupyterhub.spawner`
 =================================
@@ -12,7 +12,11 @@ Module: :mod:`jupyterhub.spawner`
 :class:`Spawner`
 ----------------
 
-.. autoclass:: Spawner
+.. autoconfigurable:: Spawner
     :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string
 
-.. autoclass:: LocalProcessSpawner
+:class:`LocalProcessSpawner`
+----------------------------
+
+.. autoconfigurable:: LocalProcessSpawner
+

docs/source/api/user.rst

@@ -1,6 +1,6 @@
-=============
-   Users
-=============
+=====
+Users
+=====
 
 Module: :mod:`jupyterhub.user`
 ==============================
@@ -9,11 +9,16 @@ Module: :mod:`jupyterhub.user`
 
 .. currentmodule:: jupyterhub.user
 
+:class:`UserDict`
+-----------------
+
+.. autoclass:: UserDict
+    :members:
+
+
 :class:`User`
 -------------
 
-.. class:: Server
-
 .. autoclass:: User
     :members: escaped_name
     
@@ -29,3 +34,4 @@ Module: :mod:`jupyterhub.user`
     .. attribute:: spawner
     
         The user's :class:`~.Spawner` instance.
+

docs/source/authenticators.md

@@ -1,113 +0,0 @@
-# Authenticators
-
-The [Authenticator][] is the mechanism for authorizing users.
-Basic authenticators use simple username and password authentication.
-JupyterHub ships only with a [PAM][]-based Authenticator,
-for logging in with local user accounts.
-
-You can use custom Authenticator subclasses to enable authentication via other systems.
-One such example is using [GitHub OAuth][].
-
-Because the username is passed from the Authenticator to the Spawner,
-a custom Authenticator and Spawner are often used together.
-
-See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
-
-
-## Basics of Authenticators
-
-A basic Authenticator has one central method:
-
-### Authenticator.authenticate
-
-    Authenticator.authenticate(handler, data)
-
-This method is passed the tornado RequestHandler and the POST data from the login form.
-Unless the login form has been customized, `data` will have two keys:
-
-- `username` (self-explanatory)
-- `password` (also self-explanatory)
-
-`authenticate`'s job is simple:
-
-- return a username (non-empty str)
-  of the authenticated user if authentication is successful
-- return `None` otherwise
-
-Writing an Authenticator that looks up passwords in a dictionary
-requires only overriding this one method:
-
-```python
-from tornado import gen
-from IPython.utils.traitlets import Dict
-from jupyterhub.auth import Authenticator
-
-class DictionaryAuthenticator(Authenticator):
-
-    passwords = Dict(config=True,
-        help="""dict of username:password for authentication"""
-    )
-
-    @gen.coroutine
-    def authenticate(self, handler, data):
-        if self.passwords.get(data['username']) == data['password']:
-            return data['username']
-```
-
-### Authenticator.whitelist
-
-Authenticators can specify a whitelist of usernames to allow authentication.
-For local user authentication (e.g. PAM), this lets you limit which users
-can login.
-
-
-## Normalizing and validating usernames
-
-Since the Authenticator and Spawner both use the same username,
-sometimes you want to transform the name coming from the authentication service
-(e.g. turning email addresses into local system usernames) before adding them to the Hub service.
-Authenticators can define `normalize_username`, which takes a username.
-The default normalization is to cast names to lowercase
-
-For simple mappings, a configurable dict `Authenticator.username_map` is used to turn one name into another:
-
-```python
-c.Authenticator.username_map  = {
-  'service-name': 'localname'
-}
-```
-
-### Validating usernames
-
-In most cases, there is a very limited set of acceptable usernames.
-Authenticators can define `validate_username(username)`,
-which should return True for a valid username and False for an invalid one.
-The primary effect this has is improving error messages during user creation.
-
-The default behavior is to use configurable `Authenticator.username_pattern`,
-which is a regular expression string for validation.
-
-To only allow usernames that start with 'w':
-
-```python
-c.Authenticator.username_pattern = r'w.*'
-```
-
-## OAuth and other non-password logins
-
-Some login mechanisms, such as [OAuth][], don't map onto username+password.
-For these, you can override the login handlers.
-
-You can see an example implementation of an Authenticator that uses [GitHub OAuth][]
-at [OAuthenticator][].
-
-
-## Writing a custom authenticator
-
-If you are interested in writing a custom authenticator, you can read [this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
-
-[Authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py
-[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
-[OAuth]: https://en.wikipedia.org/wiki/OAuth
-[GitHub OAuth]: https://developer.github.com/v3/oauth/
-[OAuthenticator]: https://github.com/jupyterhub/oauthenticator

docs/source/changelog.md

@@ -1,19 +1,147 @@
-# Change log summary
+# Changelog
 
 For detailed changes from the prior release, click on the version number, and
 its link will bring up a GitHub listing of changes. Use `git log` on the
 command line for details.
 
 
-## [Unreleased] 0.8
+## [Unreleased]
 
-## 0.7
+## 0.8
 
-### [0.7.1] - 2016-01-02
+### [0.8.1] 2017-11-07
+
+JupyterHub 0.8.1 is a collection of bugfixes and small improvements on 0.8.
 
 #### Added
 
-- `Spawner.will_resume` for signalling that a single-user server is paused instead of stopped.
+- Run tornado with AsyncIO by default
+- Add `jupyterhub --upgrade-db` flag for automatically upgrading the database as part of startup.
+  This is useful for cases where manually running `jupyterhub upgrade-db`
+  as a separate step is unwieldy.
+- Avoid creating backups of the database when no changes are to be made by
+  `jupyterhub upgrade-db`.
+
+#### Fixed
+
+- Add some further validation to usernames - `/` is not allowed in usernames.
+- Fix empty logout page when using auto_login
+- Fix autofill of username field in default login form.
+- Fix listing of users on the admin page who have not yet started their server.
+- Fix ever-growing traceback when re-raising Exceptions from spawn failures.
+- Remove use of deprecated `bower` for javascript client dependencies.
+
+
+### [0.8.0] 2017-10-03
+
+JupyterHub 0.8 is a big release!
+
+Perhaps the biggest change is the use of OAuth to negotiate authentication
+between the Hub and single-user services.
+Due to this change, it is important that the single-user server
+and Hub are both running the same version of JupyterHub.
+If you are using containers (e.g. via DockerSpawner or KubeSpawner),
+this means upgrading jupyterhub in your user images at the same time as the Hub.
+In most cases, a
+
+    pip install jupyterhub==version
+
+in your Dockerfile is sufficient.
+
+#### Added
+
+- JupyterHub now defined a `Proxy` API for custom
+  proxy implementations other than the default.
+  The defaults are unchanged,
+  but configuration of the proxy is now done on the `ConfigurableHTTPProxy` class instead of the top-level JupyterHub.
+  TODO: docs for writing a custom proxy.
+- Single-user servers and services
+  (anything that uses HubAuth)
+  can now accept token-authenticated requests via the Authentication header.
+- Authenticators can now store state in the Hub's database.
+  To do so, the `authenticate` method should return a dict of the form
+
+  ```python
+  {
+      'username': 'name'
+      'state': {}
+  }
+  ```
+
+  This data will be encrypted and requires `JUPYTERHUB_CRYPT_KEY` environment variable to be set
+  and the `Authenticator.enable_auth_state` flag to be True.
+  If these are not set, auth_state returned by the Authenticator will not be stored.
+- There is preliminary support for multiple (named) servers per user in the REST API.
+  Named servers can be created via API requests, but there is currently no UI for managing them.
+- Add `LocalProcessSpawner.popen_kwargs` and `LocalProcessSpawner.shell_cmd`
+  for customizing how user server processes are launched.
+- Add `Authenticator.auto_login` flag for skipping the "Login with..." page explicitly.
+- Add `JupyterHub.hub_connect_ip` configuration
+  for the ip that should be used when connecting to the Hub.
+  This is promoting (and deprecating) `DockerSpawner.hub_ip_connect`
+  for use by all Spawners.
+- Add `Spawner.pre_spawn_hook(spawner)` hook for customizing
+  pre-spawn events.
+- Add `JupyterHub.active_server_limit` and `JupyterHub.concurrent_spawn_limit`
+  for limiting the total number of running user servers and the number of pending spawns, respectively.
+
+
+#### Changed
+
+- more arguments to spawners are now passed via environment variables (`.get_env()`)
+  rather than CLI arguments (`.get_args()`)
+- internally generated tokens no longer get extra hash rounds,
+  significantly speeding up authentication.
+  The hash rounds were deemed unnecessary because the tokens were already
+  generated with high entropy.
+- `JUPYTERHUB_API_TOKEN` env is available at all times,
+  rather than being removed during single-user start.
+  The token is now accessible to kernel processes,
+  enabling user kernels to make authenticated API requests to Hub-authenticated services.
+- Cookie secrets should be 32B hex instead of large base64 secrets.
+- pycurl is used by default, if available.
+
+#### Fixed
+
+So many things fixed!
+
+- Collisions are checked when users are renamed
+- Fix bug where OAuth authenticators could not logout users
+  due to being redirected right back through the login process.
+- If there are errors loading your config files,
+  JupyterHub will refuse to start with an informative error.
+  Previously, the bad config would be ignored and JupyterHub would launch with default configuration.
+- Raise 403 error on unauthorized user rather than redirect to login,
+  which could cause redirect loop.
+- Set `httponly` on cookies because it's prudent.
+- Improve support for MySQL as the database backend
+- Many race conditions and performance problems under heavy load have been fixed.
+- Fix alembic tagging of database schema versions.
+
+#### Removed
+
+- End support for Python 3.3 
+
+## 0.7
+
+### [0.7.2] - 2017-01-09
+
+#### Added
+
+- Support service environment variables and defaults in `jupyterhub-singleuser`
+  for easier deployment of notebook servers as a Service.
+- Add `--group` parameter for deploying `jupyterhub-singleuser` as a Service with group authentication.
+- Include URL parameters when redirecting through `/user-redirect/`
+
+### Fixed
+
+- Fix group authentication for HubAuthenticated services
+
+### [0.7.1] - 2017-01-02
+
+#### Added
+
+- `Spawner.will_resume` for signaling that a single-user server is paused instead of stopped.
   This is needed for cases like `DockerSpawner.remove_containers = False`,
   where the first API token is re-used for subsequent spawns.
 - Warning on startup about single-character usernames,
@@ -132,7 +260,10 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 First preview release
 
 
-[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/0.7.1...HEAD
+[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/0.8.1...HEAD
+[0.8.1]: https://github.com/jupyterhub/jupyterhub/compare/0.8.0...0.8.1
+[0.8.0]: https://github.com/jupyterhub/jupyterhub/compare/0.7.2...0.8.0
+[0.7.2]: https://github.com/jupyterhub/jupyterhub/compare/0.7.1...0.7.2
 [0.7.1]: https://github.com/jupyterhub/jupyterhub/compare/0.7.0...0.7.1
 [0.7.0]: https://github.com/jupyterhub/jupyterhub/compare/0.6.1...0.7.0
 [0.6.1]: https://github.com/jupyterhub/jupyterhub/compare/0.6.0...0.6.1

docs/source/conf.py

@@ -8,7 +8,7 @@ import shlex
 import recommonmark.parser
 
 # Set paths
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
@@ -20,6 +20,8 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'autodoc_traits',
+    'jupyter_alabaster_theme',
 ]
 
 templates_path = ['_templates']
@@ -37,6 +39,7 @@ from os.path import dirname
 docs = dirname(dirname(__file__))
 root = dirname(docs)
 sys.path.insert(0, root)
+sys.path.insert(0, os.path.join(docs, 'sphinxext'))
 
 import jupyterhub
 # The short X.Y version.
@@ -49,6 +52,9 @@ exclude_patterns = []
 pygments_style = 'sphinx'
 todo_include_todos = False
 
+# Set the default role so we can use `foo` instead of ``foo``
+default_role = 'literal'
+
 # -- Source -------------------------------------------------------------
 
 source_parsers = {
@@ -61,7 +67,7 @@ source_suffix = ['.rst', '.md']
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'jupyter_alabaster_theme'
 
 #html_theme_options = {}
 #html_theme_path = []
@@ -158,17 +164,15 @@ epub_exclude_files = ['search.html']
 
 # -- Intersphinx ----------------------------------------------------------
 
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}
 
 # -- Read The Docs --------------------------------------------------------
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
 if not on_rtd:
-    # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    import jupyter_alabaster_theme
+    html_theme = 'jupyter_alabaster_theme'
+    html_theme_path = [jupyter_alabaster_theme.get_path()]
 else:
     # readthedocs.org uses their theme by default, so no need to specify it
     # build rest-api, since RTD doesn't run make

docs/source/config-examples.md

@@ -1,194 +0,0 @@
-# Configuration examples
-
-This section provides configuration files and tips for the following
-configurations:
-
-- Example with GitHub OAuth
-- Example with nginx reverse proxy
-
-
-## Example with GitHub OAuth
-
-In the following example, we show a configuration files for a fairly standard JupyterHub deployment with the following assumptions:
-
-* JupyterHub is running on a single cloud server
-* Using SSL on the standard HTTPS port 443
-* You want to use GitHub OAuth (using oauthenticator) for login
-* You need the users to exist locally on the server
-* You want users' notebooks to be served from `~/assignments` to allow users to browse for notebooks within
-  other users home directories
-* You want the landing page for each user to be a Welcome.ipynb notebook in their assignments directory.
-* All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
-
-Let's start out with `jupyterhub_config.py`:
-
-```python
-# jupyterhub_config.py
-c = get_config()
-
-import os
-pjoin = os.path.join
-
-runtime_dir = os.path.join('/srv/jupyterhub')
-ssl_dir = pjoin(runtime_dir, 'ssl')
-if not os.path.exists(ssl_dir):
-    os.makedirs(ssl_dir)
-
-
-# https on :443
-c.JupyterHub.port = 443
-c.JupyterHub.ssl_key = pjoin(ssl_dir, 'ssl.key')
-c.JupyterHub.ssl_cert = pjoin(ssl_dir, 'ssl.cert')
-
-# put the JupyterHub cookie secret and state db
-# in /var/run/jupyterhub
-c.JupyterHub.cookie_secret_file = pjoin(runtime_dir, 'cookie_secret')
-c.JupyterHub.db_url = pjoin(runtime_dir, 'jupyterhub.sqlite')
-# or `--db=/path/to/jupyterhub.sqlite` on the command-line
-
-# put the log file in /var/log
-c.JupyterHub.extra_log_file = '/var/log/jupyterhub.log'
-
-# use GitHub OAuthenticator for local users
-
-c.JupyterHub.authenticator_class = 'oauthenticator.LocalGitHubOAuthenticator'
-c.GitHubOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL']
-# create system users that don't exist yet
-c.LocalAuthenticator.create_system_users = True
-
-# specify users and admin
-c.Authenticator.whitelist = {'rgbkrk', 'minrk', 'jhamrick'}
-c.Authenticator.admin_users = {'jhamrick', 'rgbkrk'}
-
-# start single-user notebook servers in ~/assignments,
-# with ~/assignments/Welcome.ipynb as the default landing page
-# this config could also be put in
-# /etc/ipython/ipython_notebook_config.py
-c.Spawner.notebook_dir = '~/assignments'
-c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
-```
-
-Using the GitHub Authenticator [requires a few additional env variables][oauth-setup],
-which we will need to set when we launch the server:
-
-```bash
-export GITHUB_CLIENT_ID=github_id
-export GITHUB_CLIENT_SECRET=github_secret
-export OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback
-export CONFIGPROXY_AUTH_TOKEN=super-secret
-jupyterhub -f /path/to/aboveconfig.py
-```
-
-## Example with nginx reverse proxy
-
-In the following example, we show configuration files for a JupyterHub server running locally on port `8000` but accessible from the outside on the standard SSL port `443`. This could be useful if the JupyterHub server machine is also hosting other domains or content on `443`. The goal here is to have the following be true:
-
-* JupyterHub is running on a server, accessed *only* via `HUB.DOMAIN.TLD:443`
-* On the same machine, `NO_HUB.DOMAIN.TLD` strictly serves different content, also on port `443`
-* `nginx` is used to manage the web servers / reverse proxy (which means that only nginx will be able to bind two servers to `443`)
-* After testing, the server in question should be able to score an A+ on the Qualys SSL Labs [SSL Server Test](https://www.ssllabs.com/ssltest/)
-
-Let's start out with `jupyterhub_config.py`:
-
-```python
-# Force the proxy to only listen to connections to 127.0.0.1
-c.JupyterHub.ip = '127.0.0.1'
-```
-
-The `nginx` server config files are fairly standard fare except for the two `location` blocks within the `HUB.DOMAIN.TLD` config file:
-
-```bash
-# HTTP server to redirect all 80 traffic to SSL/HTTPS
-server {
-	listen 80;
-	server_name HUB.DOMAIN.TLD;
-
-	# Tell all requests to port 80 to be 302 redirected to HTTPS
-	return 302 https://$host$request_uri;
-}
-
-# HTTPS server to handle JupyterHub
-server {
-	listen 443;
-	ssl on;
-
-	server_name HUB.DOMAIN.TLD;
-
-	ssl_certificate /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem
-	ssl_certificate_key /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem
-
-	ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
-    ssl_prefer_server_ciphers on;
-    ssl_dhparam /etc/ssl/certs/dhparam.pem;
-    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
-    ssl_session_timeout 1d;
-    ssl_session_cache shared:SSL:50m;
-    ssl_stapling on;
-    ssl_stapling_verify on;
-    add_header Strict-Transport-Security max-age=15768000;
-
-	# Managing literal requests to the JupyterHub front end
-	location / {
-		proxy_pass https://127.0.0.1:8000;
-		proxy_set_header X-Real-IP $remote_addr;
-		proxy_set_header Host $host;
-		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-    }
-
-	# Managing WebHook/Socket requests between hub user servers and external proxy
-    location ~* /(api/kernels/[^/]+/(channels|iopub|shell|stdin)|terminals/websocket)/? {
-		proxy_pass https://127.0.0.1:8000;
-
-		proxy_set_header X-Real-IP $remote_addr;
-		proxy_set_header Host $host;
-		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-		# WebSocket support
-		proxy_http_version 1.1;
-		proxy_set_header Upgrade $http_upgrade;
-		proxy_set_header Connection $connection_upgrade;
-
-    }
-
-	# Managing requests to verify letsencrypt host
-    location ~ /.well-known {
-		allow all;
-    }
-
-
-}
-```
-
-`nginx` will now be the front facing element of JupyterHub on `443` which means it is also free to bind other servers, like `NO_HUB.DOMAIN.TLD` to the same port on the same machine and network interface. In fact, one can simply use the same server blocks as above for `NO_HUB` and simply add line for the root directory of the site as well as the applicable location call:
-
-```bash
-server {
-	listen 80;
-	server_name NO_HUB.DOMAIN.TLD;
-
-	# Tell all requests to port 80 to be 302 redirected to HTTPS
-	return 302 https://$host$request_uri;
-}
-
-server {
-	listen 443;
-	ssl on;
-
-	# INSERT OTHER SSL PARAMETERS HERE AS ABOVE
-
-	# Set the appropriate root directory
-	root /var/www/html
-
-	# Set URI handling
-	location / {
-		try_files $uri $uri/ =404;
-	}
-
-	# Managing requests to verify letsencrypt host
-    location ~ /.well-known {
-		allow all;
-    }
-
-}
-```
-
-Now just restart `nginx`, restart the JupyterHub, and enjoy accessing https://HUB.DOMAIN.TLD while serving other content securely on https://NO_HUB.DOMAIN.TLD.

docs/source/contributor-list.md

@@ -3,30 +3,44 @@
 Project Jupyter thanks the following people for their help and
 contribution on JupyterHub:
 
+- Analect
 - anderbubble
+- apetresc
+- barrachri
 - betatim
 - Carreau
+- charnpreetsingh
 - ckald
+- CRegenschein
 - cwaldbieser
 - danielballen
+- danoventa
 - daradib
 - datapolitan
 - dblockow-d2dcrc
+- DeepHorizons
+- dhirschfeld
 - dietmarw
+- dmartzol
 - DominicFollettSmith
 - dsblank
 - ellisonbg
 - evanlinde
 - Fokko
+- fperez
 - iamed18
 - JamiesHQ
+- jbweston
 - jdavidheiser
+- jencabral
 - jhamrick
 - josephtate
 - kinuax
 - KrishnaPG
+- kroq-gar78
 - ksolan
 - mbmilligan
+- mgeplf
 - minrk
 - mistercrunch
 - Mistobaan
@@ -37,6 +51,8 @@ contribution on JupyterHub:
 - parente
 - PeterDaveHello
 - peterruppel
+- pjamason
+- prasadkatti
 - rafael-ladislau
 - rgbkrk
 - robnagler
@@ -47,12 +63,16 @@ contribution on JupyterHub:
 - ssanderson
 - takluyver
 - temogen
+- ThomasMChen
 - TimShawver
 - Todd-Z-Li
 - toobaz
 - tsaeger
+- tschaume
 - vilhelmen
+- whitead
 - willingc
 - YannBrrd
 - yuvipanda
 - zoltan-fedor
+- zonca

docs/source/gallery-jhub-deployments.md

@@ -0,0 +1,169 @@
+# A Gallery of JupyterHub Deployments
+
+**A JupyterHub Community Resource**
+
+We've compiled this list of JupyterHub deployments to help the community
+see the breadth and growth of JupyterHub's use in education, research, and
+high performance computing.
+
+Please submit pull requests to update information or to add new institutions or uses.
+
+
+## Academic Institutions, Research Labs, and Supercomputer Centers
+
+### University of California Berkeley
+
+- [BIDS - Berkeley Institute for Data Science](https://bids.berkeley.edu/)
+    - [Teaching with Jupyter notebooks and JupyterHub](https://bids.berkeley.edu/resources/videos/teaching-ipythonjupyter-notebooks-and-jupyterhub)
+
+- [Data 8](http://data8.org/)
+    - [GitHub organization](https://github.com/data-8)
+
+- [NERSC](http://www.nersc.gov/)
+    - [Press release on Jupyter and Cori](http://www.nersc.gov/news-publications/nersc-news/nersc-center-news/2016/jupyter-notebooks-will-open-up-new-possibilities-on-nerscs-cori-supercomputer/)
+    - [Moving and sharing data](https://www.nersc.gov/assets/Uploads/03-MovingAndSharingData-Cholia.pdf)
+
+- [Research IT](http://research-it.berkeley.edu)
+    - [JupyterHub server supports campus research computation](http://research-it.berkeley.edu/blog/17/01/24/free-fully-loaded-jupyterhub-server-supports-campus-research-computation)
+
+### University of California Davis
+
+- [Spinning up multiple Jupyter Notebooks on AWS for a tutorial](https://github.com/mblmicdiv/course2017/blob/master/exercises/sourmash-setup.md)
+
+Although not technically a JupyterHub deployment, this tutorial setup
+may be helpful to others in the Jupyter community.
+
+Thank you C. Titus Brown for sharing this with the Software Carpentry
+mailing list.
+
+```
+* I started a big Amazon machine;
+* I installed Docker and built a custom image containing my software of
+  interest;
+* I ran multiple containers, one connected to port 8000, one on 8001,
+  etc. and gave each student a different port;
+* students could connect in and use the Terminal program in Jupyter to
+  execute commands, and could upload/download files via the Jupyter
+  console interface;
+* in theory I could have used notebooks too, but for this I didn’t have
+  need.
+
+I am aware that JupyterHub can probably do all of this including manage
+the containers, but I’m still a bit shy of diving into that; this was
+fairly straightforward, gave me disposable containers that were isolated
+for each individual student, and worked almost flawlessly.  Should be
+easy to do with RStudio too.
+```
+
+### Cal Poly San Luis Obispo
+
+- [jupyterhub-deploy-teaching](https://github.com/jupyterhub/jupyterhub-deploy-teaching) based on work by Brian Granger for Cal Poly's Data Science 301 Course
+
+### Clemson University
+
+- Advanced Computing
+    - [Palmetto cluster and JupyterHub](http://citi.sites.clemson.edu/2016/08/18/JupyterHub-for-Palmetto-Cluster.html)
+
+### University of Colorado Boulder
+
+- (CU Research Computing) CURC 
+    - [JupyterHub User Guide](https://www.rc.colorado.edu/support/user-guide/jupyterhub.html)
+        - Slurm job dispatched on Crestone compute cluster
+        - log troubleshooting
+        - Profiles in IPython Clusters tab
+    - [Parallel Processing with JupyterHub tutorial](https://www.rc.colorado.edu/support/examples-and-tutorials/parallel-processing-with-jupyterhub.html)
+    - [Parallel Programming with JupyterHub document](https://www.rc.colorado.edu/book/export/html/833)
+
+- Earth Lab at CU
+    - [Tutorial on Parallel R on JupyterHub](https://earthdatascience.org/tutorials/parallel-r-on-jupyterhub/)
+
+### HTCondor
+
+- [HTCondor Python Bindings Tutorial from HTCondor Week 2017 includes information on their JupyterHub tutorials](https://research.cs.wisc.edu/htcondor/HTCondorWeek2017/presentations/TueBockelman_Python.pdf)
+
+### University of Illinois
+
+- https://datascience.business.illinois.edu
+
+### MIT and Lincoln Labs
+
+
+### Michigan State University
+
+- [Setting up JupyterHub](https://mediaspace.msu.edu/media/Setting+Up+Your+JupyterHub+Password/1_hgv13aag/11980471)
+
+### University of Minnesota
+
+- [JupyterHub Inside HPC](https://insidehpc.com/tag/jupyterhub/)
+
+### University of Missouri
+
+- https://dsa.missouri.edu/faq/
+
+### University of Rochester CIRC 
+
+- [JupyterHub Userguide](https://info.circ.rochester.edu/Web_Applications/JupyterHub.html) - Slurm, beehive
+
+### University of California San Diego
+
+- San Diego Supercomputer Center - Andrea Zonca
+    - [Deploy JupyterHub on a Supercomputer with SSH](https://zonca.github.io/2017/05/jupyterhub-hpc-batchspawner-ssh.html)
+    - [Run Jupyterhub on a Supercomputer](https://zonca.github.io/2015/04/jupyterhub-hpc.html)
+    - [Deploy JupyterHub on a VM for a Workshop](https://zonca.github.io/2016/04/jupyterhub-sdsc-cloud.html)
+    - [Customize your Python environment in Jupyterhub](https://zonca.github.io/2017/02/customize-python-environment-jupyterhub.html)
+    - [Jupyterhub deployment on multiple nodes with Docker Swarm](https://zonca.github.io/2016/05/jupyterhub-docker-swarm.html)
+    - [Sample deployment of Jupyterhub in HPC on SDSC Comet](https://zonca.github.io/2017/02/sample-deployment-jupyterhub-hpc.html)
+
+- Educational Technology Services - Paul Jamason
+    - [jupyterhub.ucsd.edu](https://jupyterhub.ucsd.edu)
+    
+### TACC University of Texas
+
+### Texas A&M
+
+- Kristen Thyng - Oceanography
+    - [Teaching with JupyterHub and nbgrader](http://kristenthyng.com/blog/2016/09/07/jupyterhub+nbgrader/)
+
+
+
+## Service Providers
+
+### AWS
+
+- [running-jupyter-notebook-and-jupyterhub-on-amazon-emr](https://aws.amazon.com/blogs/big-data/running-jupyter-notebook-and-jupyterhub-on-amazon-emr/)
+
+### Google Cloud Platform
+
+- [Using Tensorflow and JupyterHub in Classrooms](https://cloud.google.com/solutions/using-tensorflow-jupyterhub-classrooms)
+- [using-tensorflow-and-jupyterhub blog post](https://opensource.googleblog.com/2016/10/using-tensorflow-and-jupyterhub.html)
+
+### Everware
+
+[Everware](https://github.com/everware) Reproducible and reusable science powered by jupyterhub and docker. Like nbviewer, but executable. CERN, Geneva [website](http://everware.xyz/)
+
+
+### Microsoft Azure
+
+- https://docs.microsoft.com/en-us/azure/machine-learning/machine-learning-data-science-linux-dsvm-intro
+
+### Rackspace Carina
+
+- https://getcarina.com/blog/learning-how-to-whale/
+- http://carolynvanslyck.com/talk/carina/jupyterhub/#/
+
+### Red Hat
+
+
+## Miscellaneous
+
+- https://medium.com/@ybarraud/setting-up-jupyterhub-with-sudospawner-and-anaconda-844628c0dbee#.rm3yt87e1
+- https://groups.google.com/forum/#!topic/jupyter/nkPSEeMr8c0 Mailing list UT deployment
+- JupyterHub setup on Centos https://gist.github.com/johnrc/604971f7d41ebf12370bf5729bf3e0a4
+- Deploy JupyterHub to Docker Swarm https://jupyterhub.surge.sh/#/welcome
+- http://www.laketide.com/building-your-lab-part-3/
+- http://estrellita.hatenablog.com/entry/2015/07/31/083202
+- http://www.walkingrandomly.com/?p=5734
+- https://wrdrd.com/docs/consulting/education-technology
+- https://bitbucket.org/jackhale/fenics-jupyter
+- [LinuxCluster blog](https://linuxcluster.wordpress.com/category/application/jupyterhub/)
+- [Network Technology](https://arnesund.com/tag/jupyterhub/) [Spark Cluster on OpenStack with Multi-User Jupyter Notebook](https://arnesund.com/2015/09/21/spark-cluster-on-openstack-with-multi-user-jupyter-notebook/)

docs/source/getting-started.md

@@ -1,526 +0,0 @@
-# Getting started with JupyterHub
-
-This section contains getting started information on the following topics:
-
-- [Technical Overview](getting-started.html#technical-overview)
-- [Installation](getting-started.html#installation)
-- [Configuration](getting-started.html#configuration)
-- [Networking](getting-started.html#networking)
-- [Security](getting-started.html#security)
-- [Authentication and users](getting-started.html#authentication-and-users)
-- [Spawners and single-user notebook servers](getting-started.html#spawners-and-single-user-notebook-servers)
-- [External Services](getting-started.html#external-services)
-
-
-## Technical Overview
-
-JupyterHub is a set of processes that together provide a single user Jupyter
-Notebook server for each person in a group.
-
-### Three subsystems
-Three major subsystems run by the `jupyterhub` command line program:
-
-- **Single-User Notebook Server**: a dedicated, single-user, Jupyter Notebook server is
-  started for each user on the system when the user logs in. The object that
-  starts these servers is called a **Spawner**.
-- **Proxy**: the public facing part of JupyterHub that uses a dynamic proxy
-  to route HTTP requests to the Hub and Single User Notebook Servers.
-- **Hub**: manages user accounts, authentication, and coordinates Single User
-  Notebook Servers using a Spawner.
-
-![JupyterHub subsystems](images/jhub-parts.png)
-
-
-### Deployment server
-To use JupyterHub, you need a Unix server (typically Linux) running somewhere
-that is accessible to your team on the network. The JupyterHub server can be
-on an internal network at your organization, or it can run on the public
-internet (in which case, take care with the Hub's
-[security](getting-started.html#security)).
-
-### Basic operation
-Users access JupyterHub through a web browser, by going to the IP address or
-the domain name of the server.
-
-Basic principles of operation:
-
-* Hub spawns proxy
-* Proxy forwards all requests to hub by default
-* Hub handles login, and spawns single-user servers on demand
-* Hub configures proxy to forward url prefixes to single-user servers
-
-Different **[authenticators](authenticators.html)** control access
-to JupyterHub. The default one (PAM) uses the user accounts on the server where
-JupyterHub is running. If you use this, you will need to create a user account
-on the system for each user on your team. Using other authenticators, you can
-allow users to sign in with e.g. a GitHub account, or with any single-sign-on
-system your organization has.
-
-Next, **[spawners](spawners.html)** control how JupyterHub starts
-the individual notebook server for each user. The default spawner will
-start a notebook server on the same machine running under their system username.
-The other main option is to start each server in a separate container, often
-using Docker.
-
-### Default behavior
-
-**IMPORTANT: You should not run JupyterHub without SSL encryption on a public network.**
-
-See [Security documentation](#security) for how to configure JupyterHub to use SSL,
-or put it behind SSL termination in another proxy server, such as nginx.
-
----
-
-**Deprecation note:** Removed `--no-ssl` in version 0.7.
-
-JupyterHub versions 0.5 and 0.6 require extra confirmation via `--no-ssl` to
-allow running without SSL using the command `jupyterhub --no-ssl`. The
-`--no-ssl` command line option is not needed anymore in version 0.7.
-
----
-
-To start JupyterHub in its default configuration, type the following at the command line:
-
-```bash
-    sudo jupyterhub
-```
-
-The default Authenticator that ships with JupyterHub authenticates users
-with their system name and password (via [PAM][]).
-Any user on the system with a password will be allowed to start a single-user notebook server.
-
-The default Spawner starts servers locally as each user, one dedicated server per user.
-These servers listen on localhost, and start in the given user's home directory.
-
-By default, the **Proxy** listens on all public interfaces on port 8000.
-Thus you can reach JupyterHub through either:
-
-- `http://localhost:8000`
-- or any other public IP or domain pointing to your system.
-
-In their default configuration, the other services, the **Hub** and **Single-User Servers**,
-all communicate with each other on localhost only.
-
-By default, starting JupyterHub will write two files to disk in the current working directory:
-
-- `jupyterhub.sqlite` is the sqlite database containing all of the state of the **Hub**.
-  This file allows the **Hub** to remember what users are running and where,
-  as well as other information enabling you to restart parts of JupyterHub separately. It is
-  important to note that this database contains *no* sensitive information other than **Hub**
-  usernames.
-- `jupyterhub_cookie_secret` is the encryption key used for securing cookies.
-  This file needs to persist in order for restarting the Hub server to avoid invalidating cookies.
-  Conversely, deleting this file and restarting the server effectively invalidates all login cookies.
-  The cookie secret file is discussed in the [Cookie Secret documentation](#cookie-secret).
-
-The location of these files can be specified via configuration, discussed below.
-
-## Installation
-
-See the project's [README](https://github.com/jupyterhub/jupyterhub/blob/master/README.md)
-for help installing JupyterHub.
-
-### Planning your installation
-
-Prior to beginning installation, it's helpful to consider some of the following:
-- deployment system (bare metal, Docker)
-- Authentication (PAM, OAuth, etc.)
-- Spawner of singleuser notebook servers (Docker, Batch, etc.)
-- Services (nbgrader, etc.)
-- JupyterHub database (default SQLite; traditional RDBMS such as PostgreSQL,)
-  MySQL, or other databases supported by [SQLAlchemy](http://www.sqlalchemy.org))  
-
-### Folders and File Locations
-
-It is recommended to put all of the files used by JupyterHub into standard
-UNIX filesystem locations.
-
-* `/srv/jupyterhub` for all security and runtime files
-* `/etc/jupyterhub` for all configuration files
-* `/var/log` for log files
-
-## Configuration
-
-JupyterHub is configured in two ways:
-
-1. Configuration file
-2. Command-line arguments
-
-### Configuration file
-By default, JupyterHub will look for a configuration file (which may not be created yet)
-named `jupyterhub_config.py` in the current working directory.
-You can create an empty configuration file with:
-
-```bash
-jupyterhub --generate-config
-```
-
-This empty configuration file has descriptions of all configuration variables and their default
-values. You can load a specific config file with:
-
-```bash
-jupyterhub -f /path/to/jupyterhub_config.py
-```
-
-See also: [general docs](http://ipython.org/ipython-doc/dev/development/config.html)
-on the config system Jupyter uses.
-
-### Command-line arguments
-Type the following for brief information about the command-line arguments:
-
-```bash
-jupyterhub -h
-```
-
-or:
-
-```bash
-jupyterhub --help-all
-```
-
-for the full command line help.
-
-All configurable options are technically configurable on the command-line,
-even if some are really inconvenient to type. Just replace the desired option,
-`c.Class.trait`, with `--Class.trait`. For example, to configure the
-`c.Spawner.notebook_dir` trait from the command-line:
-
-```bash
-jupyterhub --Spawner.notebook_dir='~/assignments'
-```
-
-## Networking
-
-### Configuring the Proxy's IP address and port
-The Proxy's main IP address setting determines where JupyterHub is available to users.
-By default, JupyterHub is configured to be available on all network interfaces
-(`''`) on port 8000. **Note**: Use of `'*'` is discouraged for IP configuration;
-instead, use of `'0.0.0.0'` is preferred.
-
-Changing the IP address and port can be done with the following command line
-arguments:
-
-```bash
-jupyterhub --ip=192.168.1.2 --port=443
-```
-
-Or by placing the following lines in a configuration file:
-
-```python
-c.JupyterHub.ip = '192.168.1.2'
-c.JupyterHub.port = 443
-```
-
-Port 443 is used as an example since 443 is the default port for SSL/HTTPS.
-
-Configuring only the main IP and port of JupyterHub should be sufficient for most deployments of JupyterHub.
-However, more customized scenarios may need additional networking details to
-be configured.
-
-
-### Configuring the Proxy's REST API communication IP address and port (optional)
-The Hub service talks to the proxy via a REST API on a secondary port,
-whose network interface and port can be configured separately.
-By default, this REST API listens on port 8081 of localhost only.
-
-If running the Proxy separate from the Hub,
-configure the REST API communication IP address and port with:
-
-```python
-# ideally a private network address
-c.JupyterHub.proxy_api_ip = '10.0.1.4'
-c.JupyterHub.proxy_api_port = 5432
-```
-
-### Configuring the Hub if Spawners or Proxy are remote or isolated in containers
-The Hub service also listens only on localhost (port 8080) by default.
-The Hub needs needs to be accessible from both the proxy and all Spawners.
-When spawning local servers, an IP address setting of localhost is fine.
-If *either* the Proxy *or* (more likely) the Spawners will be remote or
-isolated in containers, the Hub must listen on an IP that is accessible.
-
-```python
-c.JupyterHub.hub_ip = '10.0.1.4'
-c.JupyterHub.hub_port = 54321
-```
-
-## Security
-
-**IMPORTANT: You should not run JupyterHub without SSL encryption on a public network.**
-
----
-
-**Deprecation note:** Removed `--no-ssl` in version 0.7.
-
-JupyterHub versions 0.5 and 0.6 require extra confirmation via `--no-ssl` to
-allow running without SSL using the command `jupyterhub --no-ssl`. The
-`--no-ssl` command line option is not needed anymore in version 0.7.
-
----
-
-Security is the most important aspect of configuring Jupyter. There are four main aspects of the
-security configuration:
-
-1. SSL encryption (to enable HTTPS)
-2. Cookie secret (a key for encrypting browser cookies)
-3. Proxy authentication token (used for the Hub and other services to authenticate to the Proxy)
-4. Periodic security audits
-
-*Note* that the **Hub** hashes all secrets (e.g., auth tokens) before storing them in its
-database. A loss of control over read-access to the database should have no security impact
-on your deployment.
-
-### SSL encryption
-
-Since JupyterHub includes authentication and allows arbitrary code execution, you should not run
-it without SSL (HTTPS). This will require you to obtain an official, trusted SSL certificate or
-create a self-signed certificate. Once you have obtained and installed a key and certificate you
-need to specify their locations in the configuration file as follows:
-
-```python
-c.JupyterHub.ssl_key = '/path/to/my.key'
-c.JupyterHub.ssl_cert = '/path/to/my.cert'
-```
-
-It is also possible to use letsencrypt (https://letsencrypt.org/) to obtain
-a free, trusted SSL certificate. If you run letsencrypt using the default
-options, the needed configuration is (replace `mydomain.tld` by your fully
-qualified domain name):
-
-```python
-c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
-c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'
-```
-
-If the fully qualified domain name (FQDN) is `example.com`, the following
-would be the needed configuration:
-
-```python
-c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
-c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'
-```
-
-Some cert files also contain the key, in which case only the cert is needed. It is important that
-these files be put in a secure location on your server, where they are not readable by regular
-users.
-
-Note on **chain certificates**: If you are using a chain certificate, see also
-[chained certificate for SSL](troubleshooting.md#chained-certificates-for-ssl) in the JupyterHub troubleshooting FAQ).
-
-Note: In certain cases, e.g. **behind SSL termination in nginx**, allowing no SSL
-running on the hub may be desired.
-
-### Cookie secret
-
-The cookie secret is an encryption key, used to encrypt the browser cookies used for
-authentication. If this value changes for the Hub, all single-user servers must also be restarted.
-Normally, this value is stored in a file, the location of which can be specified in a config file
-as follows:
-
-```python
-c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/cookie_secret'
-```
-
-The content of this file should be a long random string encoded in MIME Base64. An example would be to generate this file as:
-
-```bash
-openssl rand -base64 2048 > /srv/jupyterhub/cookie_secret
-```
-
-In most deployments of JupyterHub, you should point this to a secure location on the file
-system, such as `/srv/jupyterhub/cookie_secret`. If the cookie secret file doesn't exist when
-the Hub starts, a new cookie secret is generated and stored in the file. The
-file must not be readable by group or other or the server won't start.
-The recommended permissions for the cookie secret file are 600 (owner-only rw).
-
-
-If you would like to avoid the need for files, the value can be loaded in the Hub process from
-the `JPY_COOKIE_SECRET` environment variable, which is a hex-encoded string. You
-can set it this way:
-
-```bash
-export JPY_COOKIE_SECRET=`openssl rand -hex 1024`
-```
-
-For security reasons, this environment variable should only be visible to the Hub.
-If you set it dynamically as above, all users will be logged out each time the
-Hub starts.
-
-You can also set the cookie secret in the configuration file itself,`jupyterhub_config.py`,
-as a binary string:
-
-```python
-c.JupyterHub.cookie_secret = bytes.fromhex('VERY LONG SECRET HEX STRING')
-```
-
-### Proxy authentication token
-
-The Hub authenticates its requests to the Proxy using a secret token that
-the Hub and Proxy agree upon. The value of this string should be a random
-string (for example, generated by `openssl rand -hex 32`). You can pass
-this value to the Hub and Proxy using either the `CONFIGPROXY_AUTH_TOKEN`
-environment variable:
-
-```bash
-export CONFIGPROXY_AUTH_TOKEN=`openssl rand -hex 32`
-```
-
-This environment variable needs to be visible to the Hub and Proxy.
-
-Or you can set the value in the configuration file, `jupyterhub_config.py`:
-
-```python
-c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
-```
-
-If you don't set the Proxy authentication token, the Hub will generate a random key itself, which
-means that any time you restart the Hub you **must also restart the Proxy**. If the proxy is a
-subprocess of the Hub, this should happen automatically (this is the default configuration).
-
-Another time you must set the Proxy authentication token yourself is if
-you want other services, such as [nbgrader](https://github.com/jupyter/nbgrader)
-to also be able to connect to the Proxy.
-
-### Security audits
-
-We recommend that you do periodic reviews of your deployment's security. It's
-good practice to keep JupyterHub, configurable-http-proxy, and nodejs 
-versions up to date.
-
-A handy website for testing your deployment is
-[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html).
-
-## Authentication and users
-
-The default Authenticator uses [PAM][] to authenticate system users with
-their username and password. The default behavior of this Authenticator
-is to allow any user with an account and password on the system to login.
-
-### Creating a whitelist of users
-
-You can restrict which users are allowed to login with `Authenticator.whitelist`:
-
-
-```python
-c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
-```
-
-### Managing Hub administrators
-
-Admin users of JupyterHub have the ability to take actions on users' behalf,
-such as stopping and restarting their servers,
-and adding and removing new users from the whitelist.
-Any users in the admin list are automatically added to the whitelist,
-if they are not already present.
-The set of initial Admin users can configured as follows:
-
-```python
-c.Authenticator.admin_users = {'mal', 'zoe'}
-```
-
-If `JupyterHub.admin_access` is True (not default),
-then admin users have permission to log in *as other users* on their respective machines, for debugging.
-**You should make sure your users know if admin_access is enabled.**
-
-Note: additional configuration examples are provided in this guide's
-[Configuration Examples section](./config-examples.html).
-
-### Add or remove users from the Hub
-
-Users can be added and removed to the Hub via the admin panel or REST API. These users will be
-added to the whitelist and database. Restarting the Hub will not require manually updating the
-whitelist in your config file, as the users will be loaded from the database. This means that
-after starting the Hub once, it is not sufficient to remove users from the whitelist in your
-config file. You must also remove them from the database, either by discarding the database file,
-or via the admin UI.
-
-The default `PAMAuthenticator` is one case of a special kind of authenticator, called a
-`LocalAuthenticator`, indicating that it manages users on the local system. When you add a user to
-the Hub, a `LocalAuthenticator` checks if that user already exists. Normally, there will be an
-error telling you that the user doesn't exist. If you set the configuration value
-
-```python
-c.LocalAuthenticator.create_system_users = True
-```
-
-however, adding a user to the Hub that doesn't already exist on the system will result in the Hub
-creating that user via the system `adduser` command line tool. This option is typically used on
-hosted deployments of JupyterHub, to avoid the need to manually create all your users before
-launching the service. It is not recommended when running JupyterHub in situations where
-JupyterHub users maps directly onto UNIX users.
-
-## Spawners and single-user notebook servers
-
-Since the single-user server is an instance of `jupyter notebook`, an entire separate
-multi-process application, there are many aspect of that server can configure, and a lot of ways
-to express that configuration.
-
-At the JupyterHub level, you can set some values on the Spawner. The simplest of these is
-`Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root
-notebook directory is the highest level directory users will be able to access in the notebook
-dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is
-expanded to the user's home directory.
-
-```python
-c.Spawner.notebook_dir = '~/notebooks'
-```
-
-You can also specify extra command-line arguments to the notebook server with:
-
-```python
-c.Spawner.args = ['--debug', '--profile=PHYS131']
-```
-
-This could be used to set the users default page for the single user server:
-
-```python
-c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
-```
-
-Since the single-user server extends the notebook server application,
-it still loads configuration from the `ipython_notebook_config.py` config file.
-Each user may have one of these files in `$HOME/.ipython/profile_default/`.
-IPython also supports loading system-wide config files from `/etc/ipython/`,
-which is the place to put configuration that you want to affect all of your users.
-
-## External services
-
-JupyterHub has a REST API that can be used by external services like the
-[cull_idle_servers](https://github.com/jupyterhub/jupyterhub/blob/master/examples/cull-idle/cull_idle_servers.py)
-script which monitors and kills idle single-user servers periodically. In order to run such an
-external service, you need to provide it an API token. In the case of `cull_idle_servers`, it is passed
-as the environment variable called `JPY_API_TOKEN`.
-
-Currently there are two ways of registering that token with JupyterHub. The first one is to use
-the `jupyterhub` command to generate a token for a specific hub user:
-
-```bash
-jupyterhub token <username>
-```
-
-As of [version 0.6.0](./changelog.html), the preferred way of doing this is to first generate an API token:
-
-```bash
-openssl rand -hex 32
-```
-
-
-and then write it to your JupyterHub configuration file (note that the **key** is the token while the **value** is the username):
-
-```python
-c.JupyterHub.api_tokens = {'token' : 'username'}
-```
-
-Upon restarting JupyterHub, you should see a message like below in the logs:
-
-```
-Adding API token for <username>
-```
-
-Now you can run your script, i.e. `cull_idle_servers`, by providing it the API token and it will authenticate through
-the REST API to interact with it.
-
-
-[oauth-setup]: https://github.com/jupyterhub/oauthenticator#setup
-[oauthenticator]: https://github.com/jupyterhub/oauthenticator
-[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module

docs/source/getting-started/authenticators-users-basics.md

@@ -0,0 +1,99 @@
+# Authentication and User Basics
+
+The default Authenticator uses [PAM][] to authenticate system users with
+their username and password. With the default Authenticator, any user
+with an account and password on the system will be allowed to login.
+
+## Create a whitelist of users
+
+You can restrict which users are allowed to login with a whitelist,
+`Authenticator.whitelist`:
+
+
+```python
+c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
+```
+
+Users in the whitelist are added to the Hub database when the Hub is
+started.
+
+## Configure admins (`admin_users`)
+
+Admin users of JupyterHub, `admin_users`, can add and remove users from
+the user `whitelist`. `admin_users` can take actions on other users'
+behalf, such as stopping and restarting their servers.
+
+A set of initial admin users, `admin_users` can configured be as follows:
+
+```python
+c.Authenticator.admin_users = {'mal', 'zoe'}
+```
+Users in the admin list are automatically added to the user `whitelist`,
+if they are not already present.
+
+## Give admin access to other users' notebook servers (`admin_access`)
+
+Since the default `JupyterHub.admin_access` setting is False, the admins
+do not have permission to log in to the single user notebook servers
+owned by *other users*. If `JupyterHub.admin_access` is set to True,
+then admins have permission to log in *as other users* on their
+respective machines, for debugging. **As a courtesy, you should make
+sure your users know if admin_access is enabled.**
+
+## Add or remove users from the Hub
+
+Users can be added to and removed from the Hub via either the admin
+panel or the REST API. When a user is **added**, the user will be
+automatically added to the whitelist and database. Restarting the Hub
+will not require manually updating the whitelist in your config file,
+as the users will be loaded from the database.
+
+After starting the Hub once, it is not sufficient to **remove** a user
+from the whitelist in your config file. You must also remove the user
+from the Hub's database, either by deleting the user from JupyterHub's
+admin page, or you can clear the `jupyterhub.sqlite` database and start
+fresh.
+
+## Use LocalAuthenticator to create system users
+
+The `LocalAuthenticator` is a special kind of authenticator that has
+the ability to manage users on the local system. When you try to add a
+new user to the Hub, a `LocalAuthenticator` will check if the user
+already exists. If you set the configuration value, `create_system_users`,
+to `True` in the configuration file, the `LocalAuthenticator` has
+the privileges to add users to the system. The setting in the config
+file is:
+
+```python
+c.LocalAuthenticator.create_system_users = True
+```
+
+Adding a user to the Hub that doesn't already exist on the system will
+result in the Hub creating that user via the system `adduser` command
+line tool. This option is typically used on hosted deployments of
+JupyterHub, to avoid the need to manually create all your users before
+launching the service. This approach is not recommended when running
+JupyterHub in situations where JupyterHub users map directly onto the
+system's UNIX users.
+
+## Use OAuthenticator to support OAuth with popular service providers
+
+JupyterHub's [OAuthenticator][] currently supports the following
+popular services:
+
+- Auth0
+- Bitbucket
+- CILogon
+- GitHub
+- GitLab
+- Globus
+- Google
+- MediaWiki
+- Okpy
+- OpenShift
+
+A generic implementation, which you can use for OAuth authentication
+with any provider, is also available.
+
+[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
+[OAuthenticator]: https://github.com/jupyterhub/oauthenticator

docs/source/getting-started/config-basics.md

@@ -0,0 +1,87 @@
+# Configuration Basics
+
+The section contains basic information about configuring settings for a JupyterHub
+deployment. The [Technical Reference](../reference/index.html)
+documentation provides additional details.
+
+This section will help you learn how to:
+
+- generate a default configuration file, `jupyterhub_config.py`
+- start with a specific configuration file
+- configure JupyterHub using command line options
+- find information and examples for some common deployments
+
+## Generate a default config file
+
+On startup, JupyterHub will look by default for a configuration file,
+`jupyterhub_config.py`, in the current working directory.
+
+To generate a default config file, `jupyterhub_config.py`:
+
+```bash
+jupyterhub --generate-config
+```
+
+This default `jupyterhub_config.py` file contains comments and guidance for all
+configuration variables and their default values. We recommend storing
+configuration files in the standard UNIX filesystem location, i.e.
+`/etc/jupyterhub`.
+
+## Start with a specific config file
+
+You can load a specific config file and start JupyterHub using:
+
+```bash
+jupyterhub -f /path/to/jupyterhub_config.py
+```
+
+If you have stored your configuration file in the recommended UNIX filesystem
+location, `/etc/jupyterhub`, the following command will start JupyterHub using
+the configuration file:
+
+```bash
+jupyterhub -f /etc/jupyterhub/jupyterhub_config.py
+```
+
+The IPython documentation provides additional information on the
+[config system](http://ipython.readthedocs.io/en/stable/development/config.html)
+that Jupyter uses.
+
+## Configure using command line options
+
+To display all command line options that are available for configuration:
+
+```bash
+    jupyterhub --help-all
+```
+
+Configuration using the command line options is done when launching JupyterHub.
+For example, to start JupyterHub on ``10.0.1.2:443`` with https, you
+would enter:
+
+```bash
+    jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
+```    
+
+All configurable options may technically be set on the command-line,
+though some are inconvenient to type. To set a particular configuration
+parameter, `c.Class.trait`, you would use the command line option,
+`--Class.trait`, when starting JupyterHub. For example, to configure the
+`c.Spawner.notebook_dir` trait from the command-line, use the
+`--Spawner.notebook_dir` option:
+
+```bash
+jupyterhub --Spawner.notebook_dir='~/assignments'
+```
+
+## Configure for various deployment environments
+
+The default authentication and process spawning mechanisms can be replaced, and
+specific [authenticators](./authenticators-users-basics.html) and
+[spawners](./spawners-basics.html) can be set in the configuration file.
+This enables JupyterHub to be used with a variety of authentication methods or
+process control and deployment environments. [Some examples](../reference/config-examples.html),
+meant as illustration, are:
+
+- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator)
+- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner)

docs/source/getting-started/index.rst

@@ -0,0 +1,12 @@
+Getting Started
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   config-basics
+   networking-basics
+   security-basics
+   authenticators-users-basics
+   spawners-basics
+   services-basics

docs/source/getting-started/networking-basics.md

@@ -0,0 +1,88 @@
+# Networking basics
+
+This section will help you with basic proxy and network configuration to:
+
+- set the proxy's IP address and port
+- set the proxy's REST API URL
+- configure the Hub if the Proxy or Spawners are remote or isolated
+- set the `hub_connect_ip` which services will use to communicate with the hub
+
+## Set the Proxy's IP address and port
+
+The Proxy's main IP address setting determines where JupyterHub is available to users.
+By default, JupyterHub is configured to be available on all network interfaces
+(`''`) on port 8000. *Note*: Use of `'*'` is discouraged for IP configuration;
+instead, use of `'0.0.0.0'` is preferred.
+
+Changing the Proxy's main IP address and port can be done with the following
+JupyterHub **command line options**:
+
+```bash
+jupyterhub --ip=192.168.1.2 --port=443
+```
+
+Or by placing the following lines in a **configuration file**,
+`jupyterhub_config.py`:
+
+```python
+c.JupyterHub.ip = '192.168.1.2'
+c.JupyterHub.port = 443
+```
+
+Port 443 is used in the examples since 443 is the default port for SSL/HTTPS.
+
+Configuring only the main IP and port of JupyterHub should be sufficient for
+most deployments of JupyterHub. However, more customized scenarios may need
+additional networking details to be configured.
+
+## Set the Proxy's REST API communication URL (optional)
+
+By default, this REST API listens on port 8081 of `localhost` only.
+The Hub service talks to the proxy via a REST API on a secondary port. The
+API URL can be configured separately and override the default settings.
+
+### Set api_url
+
+The URL to access the API, `c.configurableHTTPProxy.api_url`, is configurable.
+An example entry to set the proxy's API URL in `jupyterhub_config.py` is:
+
+```python
+c.ConfigurableHTTPProxy.api_url = 'http://10.0.1.4:5432'
+```
+
+### proxy_api_ip and proxy_api_port (Deprecated in 0.8)
+
+If running the Proxy separate from the Hub, configure the REST API communication
+IP address and port by adding this to the `jupyterhub_config.py` file:
+
+```python
+# ideally a private network address
+c.JupyterHub.proxy_api_ip = '10.0.1.4'
+c.JupyterHub.proxy_api_port = 5432
+```
+
+We recommend using the proxy's `api_url` setting instead of the deprecated
+settings, `proxy_api_ip` and `proxy_api_port`.
+
+## Configure the Hub if the Proxy or Spawners are remote or isolated
+
+The Hub service listens only on `localhost` (port 8081) by default.
+The Hub needs to be accessible from both the proxy and all Spawners.
+When spawning local servers, an IP address setting of `localhost` is fine.
+
+If *either* the Proxy *or* (more likely) the Spawners will be remote or
+isolated in containers, the Hub must listen on an IP that is accessible.
+
+```python
+c.JupyterHub.hub_ip = '10.0.1.4'
+c.JupyterHub.hub_port = 54321
+```
+
+**Added in 0.8:** The `c.JupyterHub.hub_connect_ip` setting is the ip address or
+hostname that other services should use to connect to the Hub. A common
+configuration for, e.g. docker, is:
+
+```python
+c.JupyterHub.hub_ip = '0.0.0.0'  # listen on all interfaces
+c.JupyterHub.hub_connect_ip = '10.0.1.4'  # ip as seen on the docker network. Can also be a hostname.
+```

docs/source/getting-started/security-basics.rst

@@ -0,0 +1,181 @@
+Security settings
+=================
+
+.. important::
+
+   You should not run JupyterHub without SSL encryption on a public network.
+
+Security is the most important aspect of configuring Jupyter. Three
+configuration settings are the main aspects of security configuration:
+
+1. :ref:`SSL encryption <ssl-encryption>` (to enable HTTPS)
+2. :ref:`Cookie secret <cookie-secret>` (a key for encrypting browser cookies)
+3. Proxy :ref:`authentication token <authentication-token>` (used for the Hub and
+   other services to authenticate to the Proxy)
+
+The Hub hashes all secrets (e.g., auth tokens) before storing them in its
+database. A loss of control over read-access to the database should have
+minimal impact on your deployment; if your database has been compromised, it
+is still a good idea to revoke existing tokens.
+
+.. _ssl-encryption:
+
+Enabling SSL encryption
+-----------------------
+
+Since JupyterHub includes authentication and allows arbitrary code execution,
+you should not run it without SSL (HTTPS).
+
+Using an SSL certificate
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+This will require you to obtain an official, trusted SSL certificate or create a
+self-signed certificate. Once you have obtained and installed a key and
+certificate you need to specify their locations in the ``jupyterhub_config.py``
+configuration file as follows:
+
+.. code-block:: python
+
+    c.JupyterHub.ssl_key = '/path/to/my.key'
+    c.JupyterHub.ssl_cert = '/path/to/my.cert'
+
+
+Some cert files also contain the key, in which case only the cert is needed. It
+is important that these files be put in a secure location on your server, where
+they are not readable by regular users.
+
+If you are using a **chain certificate**, see also chained certificate for SSL
+in the JupyterHub `troubleshooting FAQ <troubleshooting>`_.
+
+Using letsencrypt
+~~~~~~~~~~~~~~~~~
+
+It is also possible to use `letsencrypt <https://letsencrypt.org/>`_ to obtain
+a free, trusted SSL certificate. If you run letsencrypt using the default
+options, the needed configuration is (replace ``mydomain.tld`` by your fully
+qualified domain name):
+
+.. code-block:: python
+
+    c.JupyterHub.ssl_key = '/etc/letsencrypt/live/{mydomain.tld}/privkey.pem'
+    c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/{mydomain.tld}/fullchain.pem'
+
+If the fully qualified domain name (FQDN) is ``example.com``, the following
+would be the needed configuration:
+
+.. code-block:: python
+
+    c.JupyterHub.ssl_key = '/etc/letsencrypt/live/example.com/privkey.pem'
+    c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/example.com/fullchain.pem'
+
+
+If SSL termination happens outside of the Hub
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In certain cases, e.g. behind `SSL termination in NGINX <https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/>`_,
+allowing no SSL running on the hub may be the desired configuration option.
+
+.. _cookie-secret:
+
+Cookie secret
+-------------
+
+The cookie secret is an encryption key, used to encrypt the browser cookies
+which are used for authentication. Three common methods are described for
+generating and configuring the cookie secret.
+
+Generating and storing as a cookie secret file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cookie secret should be 32 random bytes, encoded as hex, and is typically
+stored in a ``jupyterhub_cookie_secret`` file. An example command to generate the
+``jupyterhub_cookie_secret`` file is:
+
+.. code-block:: bash
+
+    openssl rand -hex 32 > /srv/jupyterhub/jupyterhub_cookie_secret
+
+In most deployments of JupyterHub, you should point this to a secure location on
+the file system, such as ``/srv/jupyterhub/jupyterhub_cookie_secret``.
+
+The location of the ``jupyterhub_cookie_secret`` file can be specified in the
+``jupyterhub_config.py`` file as follows:
+
+.. code-block:: python
+
+    c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/jupyterhub_cookie_secret'
+
+If the cookie secret file doesn't exist when the Hub starts, a new cookie
+secret is generated and stored in the file. The file must not be readable by
+``group`` or ``other`` or the server won't start. The recommended permissions
+for the cookie secret file are ``600`` (owner-only rw).
+
+Generating and storing as an environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you would like to avoid the need for files, the value can be loaded in the
+Hub process from the ``JPY_COOKIE_SECRET`` environment variable, which is a
+hex-encoded string. You can set it this way:
+
+.. code-block:: bash
+
+    export JPY_COOKIE_SECRET=`openssl rand -hex 32`
+
+For security reasons, this environment variable should only be visible to the
+Hub. If you set it dynamically as above, all users will be logged out each time
+the Hub starts.
+
+Generating and storing as a binary string
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can also set the cookie secret in the configuration file
+itself, ``jupyterhub_config.py``, as a binary string:
+
+.. code-block:: python
+
+    c.JupyterHub.cookie_secret = bytes.fromhex('64 CHAR HEX STRING')
+
+
+.. important::
+
+   If the cookie secret value changes for the Hub, all single-user notebook
+   servers must also be restarted.
+
+
+.. _authentication-token:
+
+Proxy authentication token
+--------------------------
+
+The Hub authenticates its requests to the Proxy using a secret token that
+the Hub and Proxy agree upon. The value of this string should be a random
+string (for example, generated by ``openssl rand -hex 32``).
+
+Generating and storing token in the configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Or you can set the value in the configuration file, ``jupyterhub_config.py``:
+
+.. code-block:: python
+
+    c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
+
+Generating and storing as an environment variable
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can pass this value of the proxy authentication token to the Hub and Proxy
+using the ``CONFIGPROXY_AUTH_TOKEN`` environment variable:
+
+.. code-block:: bash
+
+    export CONFIGPROXY_AUTH_TOKEN='openssl rand -hex 32'
+
+This environment variable needs to be visible to the Hub and Proxy.
+
+Default if token is not set
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you don't set the Proxy authentication token, the Hub will generate a random
+key itself, which means that any time you restart the Hub you **must also
+restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen
+automatically (this is the default configuration).

docs/source/getting-started/services-basics.md

@@ -0,0 +1,121 @@
+# External services
+
+When working with JupyterHub, a **Service** is defined as a process
+that interacts with the Hub's REST API. A Service may perform a specific
+or action or task. For example, shutting down individuals' single user
+notebook servers that have been is a good example of a task that could
+be automated by a Service. Let's look at how the [cull_idle_servers][]
+script can be used as a Service.
+
+## Real-world example to cull idle servers
+
+JupyterHub has a REST API that can be used by external services. This
+document will:
+
+- explain some basic information about API tokens
+- clarify that API tokens can be used to authenticate to
+  single-user servers as of [version 0.8.0](../changelog.html)
+- show how the [cull_idle_servers][] script can be:
+    - used in a Hub-managed service
+    - run as a standalone script
+
+Both examples for `cull_idle_servers` will communicate tasks to the
+Hub via the REST API.
+
+## API Token basics
+
+### Create an API token
+
+To run such an external service, an API token must be created and
+provided to the service.
+
+As of [version 0.6.0](../changelog.html), the preferred way of doing
+this is to first generate an API token:
+
+```bash
+openssl rand -hex 32
+```
+
+In [version 0.8.0](../changelog.html), a TOKEN request page for
+generating an API token is available from the JupyterHub user interface:
+
+![Request API TOKEN page](../images/token-request.png)
+
+![API TOKEN success page](../images/token-request-success.png)
+
+### Pass environment variable with token to the Hub
+
+In the case of `cull_idle_servers`, it is passed as the environment
+variable called `JUPYTERHUB_API_TOKEN`.
+
+### Use API tokens for services and tasks that require external access
+
+While API tokens are often associated with a specific user, API tokens
+can be used by services that require external access for activities
+that may not correspond to a specific human, e.g. adding users during
+setup for a tutorial or workshop. Add a service and its API token to the
+JupyterHub configuration file, `jupyterhub_config.py`:
+
+```python
+c.JupyterHub.services = [
+    {'name': 'adding-users', 'api_token': 'super-secret-token'},
+]
+```
+
+### Restart JupyterHub
+
+Upon restarting JupyterHub, you should see a message like below in the
+logs:
+
+```
+Adding API token for <username>
+```
+
+## Authenticating to single-user servers using API token
+
+In JupyterHub 0.7, there is no mechanism for token authentication to
+single-user servers, and only cookies can be used for authentication.
+0.8 supports using JupyterHub API tokens to authenticate to single-user
+servers.
+
+## Configure `cull-idle` to run as a Hub-Managed Service
+
+In `jupyterhub_config.py`, add the following dictionary for the
+`cull-idle` Service to the `c.JupyterHub.services` list:
+
+```python
+c.JupyterHub.services = [
+    {
+        'name': 'cull-idle',
+        'admin': True,
+        'command': 'python cull_idle_servers.py --timeout=3600'.split(),
+    }
+]
+```
+
+where:
+
+- `'admin': True` indicates that the Service has 'admin' permissions, and
+- `'command'` indicates that the Service will be launched as a
+  subprocess, managed by the Hub.
+
+## Run `cull-idle` manually as a standalone script
+
+Now you can run your script, i.e. `cull_idle_servers`, by providing it
+the API token and it will authenticate through the REST API to
+interact with it.
+
+This will run `cull-idle` manually. `cull-idle` can be run as a standalone
+script anywhere with access to the Hub, and will periodically check for idle
+servers and shut them down via the Hub's REST API. In order to shutdown the
+servers, the token given to cull-idle must have admin privileges.
+
+Generate an API token and store it in the `JUPYTERHUB_API_TOKEN` environment
+variable. Run `cull_idle_servers.py` manually.
+
+```bash
+    export JUPYTERHUB_API_TOKEN='token'
+    python cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+```
+
+[cull_idle_servers]: https://github.com/jupyterhub/jupyterhub/blob/master/examples/cull-idle/cull_idle_servers.py

docs/source/getting-started/spawners-basics.md

@@ -0,0 +1,33 @@
+# Spawners and single-user notebook servers
+
+Since the single-user server is an instance of `jupyter notebook`, an entire separate
+multi-process application, there are many aspect of that server can configure, and a lot of ways
+to express that configuration.
+
+At the JupyterHub level, you can set some values on the Spawner. The simplest of these is
+`Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root
+notebook directory is the highest level directory users will be able to access in the notebook
+dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is
+expanded to the user's home directory.
+
+```python
+c.Spawner.notebook_dir = '~/notebooks'
+```
+
+You can also specify extra command-line arguments to the notebook server with:
+
+```python
+c.Spawner.args = ['--debug', '--profile=PHYS131']
+```
+
+This could be used to set the users default page for the single user server:
+
+```python
+c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
+```
+
+Since the single-user server extends the notebook server application,
+it still loads configuration from the `jupyter_notebook_config.py` config file.
+Each user may have one of these files in `$HOME/.jupyter/`.
+Jupyter also supports loading system-wide config files from `/etc/jupyter/`,
+which is the place to put configuration that you want to affect all of your users.

docs/source/howitworks.md

@@ -1,77 +0,0 @@
-# How JupyterHub works
-
-JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user Jupyter notebook server.
-
-There are three basic processes involved:
-
-- multi-user Hub (Python/Tornado)
-- [configurable http proxy](https://github.com/jupyterhub/configurable-http-proxy) (node-http-proxy)
-- multiple single-user IPython notebook servers (Python/IPython/Tornado)
-
-The proxy is the only process that listens on a public interface.
-The Hub sits behind the proxy at `/hub`.
-Single-user servers sit behind the proxy at `/user/[username]`.
-
-
-## Logging in
-
-When a new browser logs in to JupyterHub, the following events take place:
-
-- Login data is handed to the [Authenticator](#authentication) instance for validation
-- The Authenticator returns the username, if login information is valid
-- A single-user server instance is [Spawned](#spawning) for the logged-in user
-- When the server starts, the proxy is notified to forward `/user/[username]/*` to the single-user server
-- Two cookies are set, one for `/hub/` and another for `/user/[username]`,
-  containing an encrypted token.
-- The browser is redirected to `/user/[username]`, which is handled by the single-user server
-
-Logging into a single-user server is authenticated via the Hub:
-
-- On request, the single-user server forwards the encrypted cookie to the Hub for verification
-- The Hub replies with the username if it is a valid cookie
-- If the user is the owner of the server, access is allowed
-- If it is the wrong user or an invalid cookie, the browser is redirected to `/hub/login`
-
-
-## Customizing  JupyterHub
-
-There are two basic extension points for JupyterHub: How users are authenticated,
-and how their server processes are started.
-Each is governed by a customizable class,
-and JupyterHub ships with just the most basic version of each.
-
-To enable custom authentication and/or spawning,
-subclass Authenticator or Spawner,
-and override the relevant methods.
-
-
-### Authentication
-
-Authentication is customizable via the Authenticator class.
-Authentication can be replaced by any mechanism,
-such as OAuth, Kerberos, etc.
-
-JupyterHub only ships with [PAM](https://en.wikipedia.org/wiki/Pluggable_authentication_module) authentication,
-which requires the server to be run as root,
-or at least with access to the PAM service,
-which regular users typically do not have
-(on Ubuntu, this requires being added to the `shadow` group).
-
-[More info on custom Authenticators](authenticators.html).
-
-See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
-
-
-### Spawning
-
-Each single-user server is started by a Spawner.
-The Spawner represents an abstract interface to a process,
-and needs to be able to take three actions:
-
-1. start the process
-2. poll whether the process is still running
-3. stop the process
-
-[More info on custom Spawners](spawners.html).
-
-See a list of custom Spawners [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners).

docs/source/index.rst

@@ -1,106 +1,87 @@
 JupyterHub
 ==========
 
-With JupyterHub you can create a **multi-user Hub** which spawns, manages,
-and proxies multiple instances of the single-user
-`Jupyter notebook <https://jupyter-notebook.readthedocs.io/en/latest/>`_ server.
-Due to its flexibility and customization options, JupyterHub can be used to
-serve notebooks to a class of students, a corporate data science group, or a
-scientific research group.
-
+`JupyterHub`_, a multi-user **Hub**, spawns, manages, and proxies multiple
+instances of the single-user `Jupyter notebook`_ server.
+JupyterHub can be used to serve notebooks to a class of students, a corporate
+data science group, or a scientific research group.
 
 .. image:: images/jhub-parts.png
    :alt: JupyterHub subsystems
    :width: 40%
    :align: right
 
-
 Three subsystems make up JupyterHub:
 
 * a multi-user **Hub** (tornado process)
 * a **configurable http proxy** (node-http-proxy)
 * multiple **single-user Jupyter notebook servers** (Python/IPython/tornado)
 
-JupyterHub's basic flow of operations includes:
+JupyterHub performs the following functions:
 
 - The Hub spawns a proxy
 - The proxy forwards all requests to the Hub by default
 - The Hub handles user login and spawns single-user servers on demand
-- The Hub configures the proxy to forward URL prefixes to the single-user notebook servers
+- The Hub configures the proxy to forward URL prefixes to the single-user
+  notebook servers
 
-For convenient administration of the Hub, its users, and :doc:`services`
-(added in version 7.0), JupyterHub also provides a
-`REST API <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default>`__.
+For convenient administration of the Hub, its users, and services,
+JupyterHub also provides a `REST API`_.
 
 Contents
 --------
 
-**User Guide**
+**Installation Guide**
 
+* :doc:`installation-guide`
 * :doc:`quickstart`
-* :doc:`getting-started`
-* :doc:`howitworks`
-* :doc:`websecurity`
-* :doc:`rest`
+* :doc:`quickstart-docker`
+* :doc:`installation-basics`
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: User Guide
+**Getting Started**
 
-   quickstart
-   getting-started
-   howitworks
-   websecurity
-   rest
+* :doc:`getting-started/index`
+* :doc:`getting-started/config-basics`
+* :doc:`getting-started/networking-basics`
+* :doc:`getting-started/security-basics`
+* :doc:`getting-started/authenticators-users-basics`
+* :doc:`getting-started/spawners-basics`
+* :doc:`getting-started/services-basics`
 
-**Configuration Guide**
-
-* :doc:`authenticators`
-* :doc:`spawners`
-* :doc:`services`
-* :doc:`config-examples`
-* :doc:`upgrading`
-* :doc:`troubleshooting`
-
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: Configuration Guide
-
-   authenticators
-   spawners
-   services
-   config-examples
-   upgrading
-   troubleshooting
+**Technical Reference**
 
+* :doc:`reference/index`
+* :doc:`reference/technical-overview`
+* :doc:`reference/websecurity`
+* :doc:`reference/authenticators`
+* :doc:`reference/spawners`
+* :doc:`reference/services`
+* :doc:`reference/rest`
+* :doc:`reference/upgrading`
+* :doc:`reference/config-examples`
 
 **API Reference**
 
 * :doc:`api/index`
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: API Reference
+**Tutorials**
 
-   api/index
+* :doc:`tutorials/index`
+* :doc:`tutorials/upgrade-dot-eight`
+* `Zero to JupyterHub with Kubernetes <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_
 
+**Troubleshooting**
+
+* :doc:`troubleshooting`
 
 **About JupyterHub**
 
-* :doc:`changelog`
 * :doc:`contributor-list`
+* :doc:`gallery-jhub-deployments`
 
-.. toctree::
-   :maxdepth: 2
-   :hidden:
-   :caption: About JupyterHub
-
-   changelog
-   contributor-list
+**Changelog**
 
+* :doc:`changelog`
 
 Indices and tables
 ------------------
@@ -114,3 +95,26 @@ Questions? Suggestions?
 
 - `Jupyter mailing list <https://groups.google.com/forum/#!forum/jupyter>`_
 - `Jupyter website <https://jupyter.org>`_
+
+.. _contents:
+
+Full Table of Contents
+----------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation-guide
+   getting-started/index
+   reference/index
+   api/index
+   tutorials/index
+   troubleshooting
+   contributor-list
+   gallery-jhub-deployments
+   changelog
+
+
+.. _JupyterHub: https://github.com/jupyterhub/jupyterhub
+.. _Jupyter notebook: https://jupyter-notebook.readthedocs.io/en/latest/
+.. _REST API: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default

docs/source/installation-basics.md

@@ -0,0 +1,40 @@
+# Installation Basics
+
+## Platform support
+
+JupyterHub is supported on Linux/Unix based systems. To use JupyterHub, you need
+a Unix server (typically Linux) running somewhere that is accessible to your
+team on the network. The JupyterHub server can be on an internal network at your
+organization, or it can run on the public internet (in which case, take care
+with the Hub's [security](./security-basics.html)).
+
+JupyterHub officially **does not** support Windows. You may be able to use
+JupyterHub on Windows if you use a Spawner and Authenticator that work on
+Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not
+be accepted, and the test suite will not run on Windows. Small patches that fix
+minor Windows compatibility issues (such as basic installation) **may** be accepted,
+however. For Windows-based systems, we would recommend running JupyterHub in a
+docker container or Linux VM.
+
+[Additional Reference:](http://www.tornadoweb.org/en/stable/#installation)
+Tornado's documentation on Windows platform support
+
+## Planning your installation
+
+Prior to beginning installation, it's helpful to consider some of the following:
+
+- deployment system (bare metal, Docker)
+- Authentication (PAM, OAuth, etc.)
+- Spawner of singleuser notebook servers (Docker, Batch, etc.)
+- Services (nbgrader, etc.)
+- JupyterHub database (default SQLite; traditional RDBMS such as PostgreSQL,)
+  MySQL, or other databases supported by [SQLAlchemy](http://www.sqlalchemy.org))  
+
+## Folders and File Locations
+
+It is recommended to put all of the files used by JupyterHub into standard
+UNIX filesystem locations.
+
+- `/srv/jupyterhub` for all security and runtime files
+- `/etc/jupyterhub` for all configuration files
+- `/var/log` for log files

docs/source/installation-guide.rst

@@ -0,0 +1,9 @@
+Installation Guide
+==================
+
+.. toctree::
+   :maxdepth: 3
+
+   quickstart
+   quickstart-docker
+   installation-basics

docs/source/quickstart-docker.rst

@@ -0,0 +1,49 @@
+Using Docker
+============
+
+.. important::
+
+   We highly recommend following the `Zero to JupyterHub`_ tutorial for
+   installing JupyterHub.
+
+Alternate installation using Docker
+-----------------------------------
+
+A ready to go `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_
+gives a straightforward deployment of JupyterHub.
+
+.. note::
+
+    This ``jupyterhub/jupyterhub`` docker image is only an image for running
+    the Hub service itself. It does not provide the other Jupyter components,
+    such as Notebook installation, which are needed by the single-user servers.
+    To run the single-user servers, which may be on the same system as the Hub or
+    not, Jupyter Notebook version 4 or greater must be installed.
+
+Starting JupyterHub with docker
+-------------------------------
+
+The JupyterHub docker image can be started with the following command::
+
+    docker run -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
+
+This command will create a container named ``jupyterhub`` that you can
+**stop and resume** with ``docker stop/start``.
+
+The Hub service will be listening on all interfaces at port 8000, which makes
+this a good choice for **testing JupyterHub on your desktop or laptop**.
+
+If you want to run docker on a computer that has a public IP then you should
+(as in MUST) **secure it with ssl** by adding ssl options to your docker
+configuration or using a ssl enabled proxy.
+
+`Mounting volumes <https://docs.docker.com/engine/userguide/containers/dockervolumes/>`_
+will allow you to store data outside the docker image (host system) so it will
+be persistent, even when you start a new image.
+
+The command ``docker exec -it jupyterhub bash`` will spawn a root shell in your
+docker container. You can use the root shell to **create system users in the container**.
+These accounts will be used for authentication in JupyterHub's default
+configuration.
+
+.. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/

docs/source/quickstart.md

@@ -1,73 +1,60 @@
-# Quickstart - Installation
+# Quickstart
 
 ## Prerequisites
 
-**Before installing JupyterHub**, you will need:
+Before installing JupyterHub, you will need:
 
-- [Python](https://www.python.org/downloads/) 3.3 or greater
-
-  An understanding of using [`pip`](https://pip.pypa.io/en/stable/) or
-  [`conda`](http://conda.pydata.org/docs/get-started.html) for
+- a Linux/Unix based system
+- [Python](https://www.python.org/downloads/) 3.4 or greater. An understanding
+  of using [`pip`](https://pip.pypa.io/en/stable/) or
+  [`conda`](https://conda.io/docs/get-started.html) for
   installing Python packages is helpful.
-
-- [nodejs/npm](https://www.npmjs.com/)
-
-  [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
+- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
   using your operating system's package manager. For example, install on Linux
-  (Debian/Ubuntu) using:
+  Debian/Ubuntu using:
 
   ```bash
   sudo apt-get install npm nodejs-legacy
   ```
-  
-  (The `nodejs-legacy` package installs the `node` executable and is currently
-  required for npm to work on Debian/Ubuntu.)
 
+  The `nodejs-legacy` package installs the `node` executable and is currently
+  required for `npm` to work on Debian/Ubuntu.
 - TLS certificate and key for HTTPS communication
-
 - Domain name
 
-**Before running the single-user notebook servers** (which may be on the same
-system as the Hub or not):
+Before running the single-user notebook servers (which may be on the same
+system as the Hub or not), you will need:
 
 - [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html)
   version 4 or greater
 
 ## Installation
 
-JupyterHub can be installed with `pip` or `conda` and the proxy with `npm`:
+JupyterHub can be installed with `pip` (and the proxy with `npm`) or `conda`:
 
 **pip, npm:**
+
 ```bash
 python3 -m pip install jupyterhub
 npm install -g configurable-http-proxy
+python3 -m pip install notebook  # needed if running the notebook servers locally
 ```
 
 **conda** (one command installs jupyterhub and proxy):
+
 ```bash
-conda install -c conda-forge jupyterhub
+conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
+conda install notebook  # needed if running the notebook servers locally
 ```
 
-To test your installation:
+Test your installation. If installed, these commands should return the packages'
+help contents:
 
 ```bash
 jupyterhub -h
 configurable-http-proxy -h
 ```
 
-If you plan to run notebook servers locally, you will need also to install
-Jupyter notebook:
-
-**pip:**
-```bash
-python3 -m pip install notebook
-```
-
-**conda:**
-```bash
-conda install notebook
-```
-
 ## Start the Hub server
 
 To start the Hub server, run the command:
@@ -79,82 +66,13 @@ jupyterhub
 Visit `https://localhost:8000` in your browser, and sign in with your unix
 credentials.
 
-To allow multiple users to sign into the Hub server, you must start `jupyterhub` as a *privileged user*, such as root:
+To **allow multiple users to sign in** to the Hub server, you must start
+`jupyterhub` as a *privileged user*, such as root:
 
 ```bash
 sudo jupyterhub
 ```
 
 The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
-describes how to run the server as a *less privileged user*, which requires
+describes how to run the server as a *less privileged user*. This requires
 additional configuration of the system.
-
-----
-
-## Basic Configuration
-
-The [getting started document](docs/source/getting-started.md) contains
-detailed information abouts configuring a JupyterHub deployment.
-
-The JupyterHub **tutorial** provides a video and documentation that explains
-and illustrates the fundamental steps for installation and configuration.
-[Repo](https://github.com/jupyterhub/jupyterhub-tutorial)
-| [Tutorial documentation](http://jupyterhub-tutorial.readthedocs.io/en/latest/)
-
-#### Generate a default configuration file
-
-Generate a default config file:
-
-    jupyterhub --generate-config
-
-#### Customize the configuration, authentication, and process spawning
-
-Spawn the server on ``10.0.1.2:443`` with **https**:
-
-    jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
-
-The authentication and process spawning mechanisms can be replaced,
-which should allow plugging into a variety of authentication or process
-control environments. Some examples, meant as illustration and testing of this
-concept, are:
-
-- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyterhub/oauthenticator)
-- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyterhub/dockerspawner)
-
-----
-
-## Alternate Installation using Docker
-
-A ready to go [docker image for JupyterHub](https://hub.docker.com/r/jupyterhub/jupyterhub/)
-gives a straightforward deployment of JupyterHub.
-
-*Note: This `jupyterhub/jupyterhub` docker image is only an image for running
-the Hub service itself. It does not provide the other Jupyter components, such
-as Notebook installation, which are needed by the single-user servers.
-To run the single-user servers, which may be on the same system as the Hub or
-not, Jupyter Notebook version 4 or greater must be installed.*
-
-#### Starting JupyterHub with docker
-
-The JupyterHub docker image can be started with the following command:
-
-    docker run -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
-
-This command will create a container named `jupyterhub` that you can
-**stop and resume** with `docker stop/start`.
-
-The Hub service will be listening on all interfaces at port 8000, which makes
-this a good choice for **testing JupyterHub on your desktop or laptop**.
-
-If you want to run docker on a computer that has a public IP then you should
-(as in MUST) **secure it with ssl** by adding ssl options to your docker
-configuration or using a ssl enabled proxy.
-
-[Mounting volumes](https://docs.docker.com/engine/userguide/containers/dockervolumes/)
-will allow you to **store data outside the docker image (host system) so it will be persistent**,
-even when you start a new image.
-
-The command `docker exec -it jupyterhub bash` will spawn a root shell in your
-docker container. You can **use the root shell to create system users in the container**.
-These accounts will be used for authentication in JupyterHub's default
-configuration.

docs/source/reference/authenticators.md

@@ -0,0 +1,222 @@
+# Authenticators
+
+The [Authenticator][] is the mechanism for authorizing users to use the
+Hub and single user notebook servers.
+
+## The default PAM Authenticator
+
+JupyterHub ships only with the default [PAM][]-based Authenticator,
+for logging in with local user accounts via a username and password.
+
+## The OAuthenticator
+
+Some login mechanisms, such as [OAuth][], don't map onto username and
+password authentication, and instead use tokens. When using these
+mechanisms, you can override the login handlers.
+
+You can see an example implementation of an Authenticator that uses
+[GitHub OAuth][] at [OAuthenticator][].
+
+JupyterHub's [OAuthenticator][] currently supports the following
+popular services:
+
+- Auth0
+- Bitbucket
+- CILogon
+- GitHub
+- GitLab
+- Globus
+- Google
+- MediaWiki
+- Okpy
+- OpenShift
+
+A generic implementation, which you can use for OAuth authentication
+with any provider, is also available.
+
+## Additional Authenticators
+
+- ldapauthenticator for LDAP
+- tmpauthenticator for temporary accounts
+
+## Technical Overview of Authentication
+
+### How the Base Authenticator works
+
+The base authenticator uses simple username and password authentication.
+
+The base Authenticator has one central method:
+
+#### Authenticator.authenticate method
+
+    Authenticator.authenticate(handler, data)
+
+This method is passed the Tornado `RequestHandler` and the `POST data`
+from JupyterHub's login form. Unless the login form has been customized,
+`data` will have two keys:
+
+- `username`
+- `password`
+
+The `authenticate` method's job is simple:
+
+- return the username (non-empty str) of the authenticated user if
+  authentication is successful
+- return `None` otherwise
+
+Writing an Authenticator that looks up passwords in a dictionary
+requires only overriding this one method:
+
+```python
+from tornado import gen
+from IPython.utils.traitlets import Dict
+from jupyterhub.auth import Authenticator
+
+class DictionaryAuthenticator(Authenticator):
+
+    passwords = Dict(config=True,
+        help="""dict of username:password for authentication"""
+    )
+
+    @gen.coroutine
+    def authenticate(self, handler, data):
+        if self.passwords.get(data['username']) == data['password']:
+            return data['username']
+```
+
+
+#### Normalize usernames
+
+Since the Authenticator and Spawner both use the same username,
+sometimes you want to transform the name coming from the authentication service
+(e.g. turning email addresses into local system usernames) before adding them to the Hub service.
+Authenticators can define `normalize_username`, which takes a username.
+The default normalization is to cast names to lowercase
+
+For simple mappings, a configurable dict `Authenticator.username_map` is used to turn one name into another:
+
+```python
+c.Authenticator.username_map  = {
+  'service-name': 'localname'
+}
+```
+
+#### Validate usernames
+
+In most cases, there is a very limited set of acceptable usernames.
+Authenticators can define `validate_username(username)`,
+which should return True for a valid username and False for an invalid one.
+The primary effect this has is improving error messages during user creation.
+
+The default behavior is to use configurable `Authenticator.username_pattern`,
+which is a regular expression string for validation.
+
+To only allow usernames that start with 'w':
+
+```python
+c.Authenticator.username_pattern = r'w.*'
+```
+
+
+### How to write a custom authenticator
+
+You can use custom Authenticator subclasses to enable authentication
+via other mechanisms. One such example is using [GitHub OAuth][].
+
+Because the username is passed from the Authenticator to the Spawner,
+a custom Authenticator and Spawner are often used together.
+For example, the Authenticator methods, [pre_spawn_start(user, spawner)][]
+and [post_spawn_stop(user, spawner)][], are hooks that can be used to do
+auth-related startup (e.g. opening PAM sessions) and cleanup
+(e.g. closing PAM sessions).
+
+
+See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+
+If you are interested in writing a custom authenticator, you can read
+[this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
+
+
+### Authentication state
+
+JupyterHub 0.8 adds the ability to persist state related to authentication,
+such as auth-related tokens.
+If such state should be persisted, `.authenticate()` should return a dictionary of the form:
+
+```python
+{
+  'username': 'name',
+  'auth_state': {
+    'key': 'value',
+  }
+}
+```
+
+where `username` is the username that has been authenticated,
+and `auth_state` is any JSON-serializable dictionary.
+
+Because `auth_state` may contain sensitive information,
+it is encrypted before being stored in the database.
+To store auth_state, two conditions must be met:
+
+1. persisting auth state must be enabled explicitly via configuration
+   ```python
+   c.Authenticator.enable_auth_state = True
+   ```
+2. encryption must be enabled by the presence of `JUPYTERHUB_CRYPT_KEY` environment variable,
+   which should be a hex-encoded 32-byte key.
+   For example:
+   ```bash
+   export JUPYTERHUB_CRYPT_KEY=$(openssl rand -hex 32)
+   ```
+
+
+JupyterHub uses [Fernet](https://cryptography.io/en/latest/fernet/) to encrypt auth_state.
+To facilitate key-rotation, `JUPYTERHUB_CRYPT_KEY` may be a semicolon-separated list of encryption keys.
+If there are multiple keys present, the **first** key is always used to persist any new auth_state.
+
+
+#### Using auth_state
+
+Typically, if `auth_state` is persisted it is desirable to affect the Spawner environment in some way.
+This may mean defining environment variables, placing certificate in the user's home directory, etc.
+The `Authenticator.pre_spawn_start` method can be used to pass information from authenticator state
+to Spawner environment:
+
+```python
+class MyAuthenticator(Authenticator):
+    @gen.coroutine
+    def authenticate(self, handler, data=None):
+        username = yield identify_user(handler, data)
+        upstream_token = yield token_for_user(username)
+        return {
+            'name': username,
+            'auth_state': {
+                'upstream_token': upstream_token,
+            },
+        }
+
+    @gen.coroutine
+    def pre_spawn_start(self, user, spawner):
+        """Pass upstream_token to spawner via environment variable"""
+        auth_state = yield user.get_auth_state()
+        if not auth_state:
+            # auth_state not enabled
+            return
+        spawner.environment['UPSTREAM_TOKEN'] = auth_state['upstream_token']
+```
+
+
+
+## JupyterHub as an OAuth provider
+
+Beginning with version 0.8, JupyterHub is an OAuth provider.
+
+
+[Authenticator]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/auth.py
+[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module
+[OAuth]: https://en.wikipedia.org/wiki/OAuth
+[GitHub OAuth]: https://developer.github.com/v3/oauth/
+[OAuthenticator]: https://github.com/jupyterhub/oauthenticator
+[pre_spawn_start(user, spawner)]: http://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.pre_spawn_start
+[post_spawn_stop(user, spawner)]: http://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.post_spawn_stop

docs/source/reference/config-examples.md

@@ -0,0 +1,272 @@
+# Configuration examples
+
+This section provides examples, including configuration files and tips, for the
+following configurations:
+
+- Using GitHub OAuth
+- Using nginx reverse proxy
+
+## Using GitHub OAuth
+
+In this example, we show a configuration file for a fairly standard JupyterHub
+deployment with the following assumptions:
+
+* Running JupyterHub on a single cloud server
+* Using SSL on the standard HTTPS port 443
+* Using GitHub OAuth (using oauthenticator) for login
+* Users exist locally on the server
+* Users' notebooks to be served from `~/assignments` to allow users to browse
+  for notebooks within other users' home directories
+* You want the landing page for each user to be a `Welcome.ipynb` notebook in
+  their assignments directory.
+* All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
+
+The `jupyterhub_config.py` file would have these settings:
+
+```python
+# jupyterhub_config.py file
+c = get_config()
+
+import os
+pjoin = os.path.join
+
+runtime_dir = os.path.join('/srv/jupyterhub')
+ssl_dir = pjoin(runtime_dir, 'ssl')
+if not os.path.exists(ssl_dir):
+    os.makedirs(ssl_dir)
+
+# Allows multiple single-server per user
+c.JupyterHub.allow_named_servers = True
+
+# https on :443
+c.JupyterHub.port = 443
+c.JupyterHub.ssl_key = pjoin(ssl_dir, 'ssl.key')
+c.JupyterHub.ssl_cert = pjoin(ssl_dir, 'ssl.cert')
+
+# put the JupyterHub cookie secret and state db
+# in /var/run/jupyterhub
+c.JupyterHub.cookie_secret_file = pjoin(runtime_dir, 'cookie_secret')
+c.JupyterHub.db_url = pjoin(runtime_dir, 'jupyterhub.sqlite')
+# or `--db=/path/to/jupyterhub.sqlite` on the command-line
+
+# use GitHub OAuthenticator for local users
+c.JupyterHub.authenticator_class = 'oauthenticator.LocalGitHubOAuthenticator'
+c.GitHubOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL']
+
+# create system users that don't exist yet
+c.LocalAuthenticator.create_system_users = True
+
+# specify users and admin
+c.Authenticator.whitelist = {'rgbkrk', 'minrk', 'jhamrick'}
+c.Authenticator.admin_users = {'jhamrick', 'rgbkrk'}
+
+# start single-user notebook servers in ~/assignments,
+# with ~/assignments/Welcome.ipynb as the default landing page
+# this config could also be put in
+# /etc/jupyter/jupyter_notebook_config.py
+c.Spawner.notebook_dir = '~/assignments'
+c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
+```
+
+Using the GitHub Authenticator requires a few additional
+environment variable to be set prior to launching JupyterHub:
+
+```bash
+export GITHUB_CLIENT_ID=github_id
+export GITHUB_CLIENT_SECRET=github_secret
+export OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback
+export CONFIGPROXY_AUTH_TOKEN=super-secret
+# append log output to log file /var/log/jupyterhub.log
+jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log
+```
+
+## Using a reverse proxy
+
+In the following example, we show configuration files for a JupyterHub server
+running locally on port `8000` but accessible from the outside on the standard
+SSL port `443`. This could be useful if the JupyterHub server machine is also
+hosting other domains or content on `443`. The goal in this example is to
+satisfy the following:
+
+* JupyterHub is running on a server, accessed *only* via `HUB.DOMAIN.TLD:443`
+* On the same machine, `NO_HUB.DOMAIN.TLD` strictly serves different content,
+  also on port `443`
+* `nginx` or `apache` is used as the public access point (which means that
+  only nginx/apache will bind  to `443`)
+* After testing, the server in question should be able to score at least an A on the
+  Qualys SSL Labs [SSL Server Test](https://www.ssllabs.com/ssltest/)
+
+Let's start out with needed JupyterHub configuration in `jupyterhub_config.py`:
+
+```python
+# Force the proxy to only listen to connections to 127.0.0.1
+c.JupyterHub.ip = '127.0.0.1'
+```
+
+For high-quality SSL configuration, we also generate Diffie-Helman parameters.
+This can take a few minutes:
+
+```bash
+openssl dhparam -out /etc/ssl/certs/dhparam.pem 4096
+```
+
+### nginx
+
+The **`nginx` server config file** is fairly standard fare except for the two
+`location` blocks within the `HUB.DOMAIN.TLD` config file:
+
+```bash
+# top-level http config for websocket headers
+# If Upgrade is defined, Connection = upgrade
+# If Upgrade is empty, Connection = close
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+# HTTP server to redirect all 80 traffic to SSL/HTTPS
+server {
+    listen 80;
+    server_name HUB.DOMAIN.TLD;
+
+    # Tell all requests to port 80 to be 302 redirected to HTTPS
+    return 302 https://$host$request_uri;
+}
+
+# HTTPS server to handle JupyterHub
+server {
+    listen 443;
+    ssl on;
+
+    server_name HUB.DOMAIN.TLD;
+
+    ssl_certificate /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem;
+
+    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
+    ssl_prefer_server_ciphers on;
+    ssl_dhparam /etc/ssl/certs/dhparam.pem;
+    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA';
+    ssl_session_timeout 1d;
+    ssl_session_cache shared:SSL:50m;
+    ssl_stapling on;
+    ssl_stapling_verify on;
+    add_header Strict-Transport-Security max-age=15768000;
+
+    # Managing literal requests to the JupyterHub front end
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+
+        # websocket headers
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+    }
+
+    # Managing requests to verify letsencrypt host
+    location ~ /.well-known {
+        allow all;
+    }
+}
+```
+
+If `nginx` is not running on port 443, substitute `$http_host` for `$host` on
+the lines setting the `Host` header.
+
+`nginx` will now be the front facing element of JupyterHub on `443` which means
+it is also free to bind other servers, like `NO_HUB.DOMAIN.TLD` to the same port
+on the same machine and network interface. In fact, one can simply use the same
+server blocks as above for `NO_HUB` and simply add line for the root directory
+of the site as well as the applicable location call:
+
+```bash
+server {
+    listen 80;
+    server_name NO_HUB.DOMAIN.TLD;
+
+    # Tell all requests to port 80 to be 302 redirected to HTTPS
+    return 302 https://$host$request_uri;
+}
+
+server {
+    listen 443;
+    ssl on;
+
+    # INSERT OTHER SSL PARAMETERS HERE AS ABOVE
+    # SSL cert may differ
+
+    # Set the appropriate root directory
+    root /var/www/html
+
+    # Set URI handling
+    location / {
+        try_files $uri $uri/ =404;
+    }
+
+    # Managing requests to verify letsencrypt host
+    location ~ /.well-known {
+        allow all;
+    }
+
+}
+```
+
+Now restart `nginx`, restart the JupyterHub, and enjoy accessing
+`https://HUB.DOMAIN.TLD` while serving other content securely on
+`https://NO_HUB.DOMAIN.TLD`.
+
+
+### Apache
+
+As with nginx above, you can use [Apache](https://httpd.apache.org) as the reverse proxy.
+First, we will need to enable the apache modules that we are going to need:
+
+```bash
+a2enmod ssl rewrite proxy proxy_http proxy_wstunnel
+```
+
+Our Apache configuration is equivalent to the nginx configuration above:
+
+- Redirect HTTP to HTTPS
+- Good SSL Configuration
+- Support for websockets on any proxied URL
+- JupyterHub is running locally at http://127.0.0.1:8000
+
+```bash
+# redirect HTTP to HTTPS
+Listen 80
+<VirtualHost HUB.DOMAIN.TLD:80>
+  ServerName HUB.DOMAIN.TLD
+  Redirect / https://HUB.DOMAIN.TLD/
+</VirtualHost>
+
+Listen 443
+<VirtualHost HUB.DOMAIN.TLD:443>
+
+  ServerName HUB.DOMAIN.TLD
+
+  # configure SSL
+  SSLEngine on
+  SSLCertificateFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/fullchain.pem
+  SSLCertificateKeyFile /etc/letsencrypt/live/HUB.DOMAIN.TLD/privkey.pem
+  SSLProtocol All -SSLv2 -SSLv3
+  SSLOpenSSLConfCmd DHParameters /etc/ssl/certs/dhparam.pem
+  SSLCipherSuite EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH
+
+  # Use RewriteEngine to handle websocket connection upgrades
+  RewriteEngine On
+  RewriteCond %{HTTP:Connection} Upgrade [NC]
+  RewriteCond %{HTTP:Upgrade} websocket [NC]
+  RewriteRule /(.*) ws://127.0.0.1:8000/$1 [P,L]
+
+  <Location "/">
+    # preserve Host header to avoid cross-origin problems
+    ProxyPreserveHost on
+    # proxy to JupyterHub
+    ProxyPass         http://127.0.0.1:8000/
+    ProxyPassReverse  http://127.0.0.1:8000/
+  </Location>
+</VirtualHost>
+```

docs/source/reference/index.rst

@@ -0,0 +1,15 @@
+Technical Reference
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   technical-overview
+   websecurity
+   authenticators
+   spawners
+   services
+   proxy
+   rest
+   upgrading
+   config-examples

docs/source/reference/proxy.md

@@ -0,0 +1,183 @@
+# Writing a custom Proxy implementation
+
+JupyterHub 0.8 introduced the ability to write a custom implementation of the proxy.
+This enables deployments with different needs than the default proxy,
+configurable-http-proxy (CHP).
+CHP is a single-process nodejs proxy that they Hub manages by default as a subprocess
+(it can be run externally, as well, and typically is in production deployments).
+
+The upside to CHP, and why we use it by default, is that it's easy to install and run (if you have nodejs, you are set!).
+The downsides are that it's a single process and does not support any persistence of the routing table.
+So if the proxy process dies, your whole JupyterHub instance is inaccessible until the Hub notices, restarts the proxy, and restores the routing table.
+For deployments that want to avoid such a single point of failure,
+or leverage existing proxy infrastructure in their chosen deployment (such as Kubernetes ingress objects),
+the Proxy API provides a way to do that.
+
+In general, for a proxy to be usable by JupyterHub, it must:
+
+1. support websockets without prior knowledge of the URL where websockets may occur
+2. support trie-based routing (i.e. allow different routes on `/foo` and `/foo/bar` and route based on specificity)
+3. adding or removing a route should not cause existing connections to drop
+
+Optionally, if the JupyterHub deployment is to use host-based routing,
+the Proxy must additionally support routing based on the Host of the request.
+
+## Subclassing Proxy
+
+To start, any Proxy implementation should subclass the base Proxy class,
+as is done with custom Spawners and Authenticators.
+
+```python
+from jupyterhub.proxy import Proxy
+
+class MyProxy(Proxy):
+    """My Proxy implementation"""
+    ...
+```
+
+
+## Starting and stopping the proxy
+
+If your proxy should be launched when the Hub starts, you must define how to start and stop your proxy:
+
+```python
+from tornado import gen
+class MyProxy(Proxy):
+    ...
+    @gen.coroutine
+    def start(self):
+        """Start the proxy"""
+
+    @gen.coroutine
+    def stop(self):
+        """Stop the proxy"""
+```
+
+These methods **may** be  coroutines.
+
+`c.Proxy.should_start` is a configurable flag that determines whether the Hub should call these methods when the Hub itself starts and stops.
+
+
+### Purely external proxies
+
+Probably most custom proxies will be externally managed,
+such as Kubernetes ingress-based implementations.
+In this case, you do not need to define `start` and `stop`.
+To disable the methods, you can define `should_start = False` at the class level:
+
+```python
+class MyProxy(Proxy):
+    should_start = False
+```
+
+
+## Adding and removing routes
+
+At its most basic, a Proxy implementation defines a mechanism to add, remove, and retrieve routes.
+A proxy that implements these three methods is complete.
+Each of these methods **may** be a coroutine.
+
+**Definition:** routespec
+
+A routespec, which will appear in these methods, is a string describing a route to be proxied,
+such as `/user/name/`. A routespec will:
+
+1. always end with `/`
+2. always start with `/` if it is a path-based route `/proxy/path/`
+3. precede the leading `/` with a host for host-based routing, e.g. `host.tld/proxy/path/`
+
+
+### Adding a route
+
+When adding a route, JupyterHub may pass a JSON-serializable dict as a `data` argument
+that should be attacked to the proxy route.
+When that route is retrieved, the `data` argument should be returned as well.
+If your  proxy implementation doesn't support storing data attached to routes,
+then your Python wrapper may have to handle storing the `data` piece itself,
+e.g in a simple file or database.
+
+```python
+@gen.coroutine
+def add_route(self, routespec, target, data):
+    """Proxy `routespec` to `target`.
+
+    Store `data` associated with the routespec
+    for retrieval later.
+    """
+```
+
+Adding a route for a user looks like this:
+
+```python
+proxy.add_route('/user/pgeorgiou/', 'http://127.0.0.1:1227',
+                {'user': 'pgeorgiou'})
+```
+
+
+### Removing routes
+
+`delete_route()` is given a routespec to delete.
+If there is no such route, `delete_route` should still succeed,
+but a warning may be issued.
+
+```python
+@gen.coroutine
+def delete_route(self, routespec):
+    """Delete the route"""
+```
+
+
+### Retrieving routes
+
+For retrieval, you only *need* to implement a single method that retrieves all routes.
+The return value for this function should be a dictionary, keyed by `routespect`,
+of dicts whose keys are the same three arguments passed to `add_route`
+(`routespec`, `target`, `data`)
+
+```python
+@gen.coroutine
+def get_all_routes(self):
+    """Return all routes, keyed by routespec""""
+```
+
+```python
+{
+  '/proxy/path/': {
+    'routespec': '/proxy/path/',
+    'target': 'http://...',
+    'data': {},
+  },
+}
+```
+
+
+
+#### Note on activity tracking
+
+JupyterHub can track activity of users, for use in services such as culling idle servers.
+As of JupyterHub 0.8, this activity tracking is the responsibility of the proxy.
+If your proxy implementation can track activity to endpoints,
+it may add a `last_activity` key to the `data` of routes retrieved in `.get_all_routes()`.
+If present, the value of `last_activity` should be an [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) UTC date string:
+
+```python
+{
+  '/user/pgeorgiou/': {
+    'routespec': '/user/pgeorgiou/',
+    'target': 'http://127.0.0.1:1227',
+    'data': {
+      'user': 'pgeourgiou',
+      'last_activity': '2017-10-03T10:33:49.570Z',
+    },
+  },
+}
+```
+
+
+If the proxy does not track activity, then only activity to the Hub itself is tracked,
+and services such as cull-idle will not work.
+
+Now that `notebook-5.0` tracks activity internally,
+we can retrieve activity information from the single-user servers instead,
+removing the need to track activity in the proxy.
+But this is not yet implemented in JupyterHub 0.8.0.

docs/source/reference/rest.md

@@ -0,0 +1,182 @@
+# Using JupyterHub's REST API
+
+This section will give you information on:
+
+- what you can do with the API
+- create an API token
+- add API tokens to the config files
+- make an API request programmatically using the requests library
+- learn more about JupyterHub's API
+
+## What you can do with the API
+
+Using the [JupyterHub REST API][], you can perform actions on the Hub,
+such as:
+
+- checking which users are active
+- adding or removing users
+- stopping or starting single user notebook servers
+- authenticating services
+
+A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
+API provides a standard way for users to get and send information to the
+Hub.
+
+## Create an API token
+
+To send requests using JupyterHub API, you must pass an API token with
+the request.
+
+As of [version 0.6.0](../changelog.html), the preferred way of
+generating an API token is:
+
+```bash
+openssl rand -hex 32
+```
+
+This `openssl` command generates a potential token that can then be
+added to JupyterHub using `.api_tokens` configuration setting in
+`jupyterhub_config.py`.
+
+Alternatively, use the `jupyterhub token` command to generate a token
+for a specific hub user by passing the 'username':
+
+```bash
+jupyterhub token <username>
+```
+
+This command generates a random string to use as a token and registers
+it for the given user with the Hub's database.
+
+In [version 0.8.0](../changelog.html), a TOKEN request page for
+generating an API token is available from the JupyterHub user interface:
+
+![Request API TOKEN page](../images/token-request.png)
+
+![API TOKEN success page](../images/token-request-success.png)
+
+## Add API tokens to the config file
+
+You may also add a dictionary of API tokens and usernames to the hub's
+configuration file, `jupyterhub_config.py` (note that
+the **key** is the 'secret-token' while the **value** is the 'username'):
+
+```python
+c.JupyterHub.api_tokens = {
+    'secret-token': 'username',
+}
+```
+
+## Make an API request
+
+To authenticate your requests, pass the API token in the request's
+Authorization header.
+
+### Use requests
+
+Using the popular Python [requests](http://docs.python-requests.org/en/master/)
+library, here's example code to make an API request for the users of a JupyterHub
+deployment. An API GET request is made, and the request sends an API token for
+authorization. The response contains information about the users:
+
+```python
+import requests
+
+api_url = 'http://127.0.0.1:8081/hub/api'
+
+r = requests.get(api_url + '/users',
+    headers={
+             'Authorization': 'token %s' % token,
+            }
+    )
+
+r.raise_for_status()
+users = r.json()
+```
+
+This example provides a slightly more complicated request, yet the
+process is very similar:
+
+```python
+import requests
+
+api_url = 'http://127.0.0.1:8081/hub/api'
+
+data = {'name': 'mygroup', 'users': ['user1', 'user2']}
+
+r = requests.post(api_url + '/groups/formgrade-data301/users',
+    headers={
+             'Authorization': 'token %s' % token,
+            },
+    json=data
+)
+r.raise_for_status()
+r.json()
+```
+
+The same API token can also authorize access to the [Jupyter Notebook REST API][]
+provided by notebook servers managed by JupyterHub if one of the following is true:
+
+1. The token is for the same user as the owner of the notebook
+2. The token is tied to an admin user or service **and** `c.JupyterHub.admin_access` is set to `True`
+
+## Enabling users to spawn multiple named-servers via the API
+
+With JupyterHub version 0.8, support for multiple servers per user has landed.
+Prior to that, each user could only launch a single default server via the API
+like this:
+
+```bash
+curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/server"
+```
+
+With the named-server functionality, it's now possible to launch more than one
+specifically named servers against a given user.  This could be used, for instance,
+to launch each server based on a different image.
+
+First you must enable named-servers by including the following setting in the `jupyterhub_config.py` file.
+
+`c.JupyterHub.allow_named_servers = True`
+
+If using the [zero-to-jupyterhub-k8s](https://github.com/jupyterhub/zero-to-jupyterhub-k8s) set-up to run JupyterHub, 
+then instead of editing the `jupyterhub_config.py` file directly, you could pass 
+the following as part of the `config.yaml` file, as per the [tutorial](https://zero-to-jupyterhub.readthedocs.io/en/latest/):
+
+```bash
+hub:
+  extraConfig: |
+    c.JupyterHub.allow_named_servers = True
+```
+
+With that setting in place, a new named-server is activated like this:
+```bash
+curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverA>"
+curl -X POST -H "Authorization: token <token>" "http://127.0.0.1:8081/hub/api/users/<user>/servers/<serverB>"
+```
+
+The same servers can be stopped by substituting `DELETE` for `POST` above.
+
+### Some caveats for using named-servers
+
+The named-server capabilities are not fully implemented for JupyterHub as yet.
+While it's possible to start/stop a server via the API, the UI on the 
+JupyterHub control-panel has not been implemented, and so it may not be obvious
+to those viewing the panel that a named-server may be running for a given user.
+
+For named-servers via the API to work, the spawner used to spawn these servers
+will need to be able to handle the case of multiple servers per user and ensure
+uniqueness of names, particularly if servers are spawned via docker containers
+or kubernetes pods.
+
+
+## Learn more about the API
+
+You can see the full [JupyterHub REST API][] for details. This REST API Spec can
+be viewed in a more [interactive style on swagger's petstore][].
+Both resources contain the same information and differ only in its display.
+Note: The Swagger specification is being renamed the [OpenAPI Initiative][].
+
+[interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
+[OpenAPI Initiative]: https://www.openapis.org/
+[JupyterHub REST API]: ../_static/rest-api/index.html
+[Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml

docs/source/reference/services.md

@@ -4,13 +4,13 @@ With version 0.7, JupyterHub adds support for **Services**.
 
 This section provides the following information about Services:
 
-- [Definition of a Service](services.html#definition-of-a-service)
-- [Properties of a Service](services.html#properties-of-a-service)
-- [Hub-Managed Services](services.html#hub-managed-services)
-- [Launching a Hub-Managed Service](services.html#launching-a-hub-managed-service)
-- [Externally-Managed Services](services.html#externally-managed-services)
-- [Writing your own Services](services.html#writing-your-own-services)
-- [Hub Authentication and Services](services.html#hub-authentication-and-services)
+- [Definition of a Service](#definition-of-a-service)
+- [Properties of a Service](#properties-of-a-service)
+- [Hub-Managed Services](#hub-managed-services)
+- [Launching a Hub-Managed Service](#launching-a-hub-managed-service)
+- [Externally-Managed Services](#externally-managed-services)
+- [Writing your own Services](#writing-your-own-services)
+- [Hub Authentication and Services](#hub-authentication-and-services)
 
 ## Definition of a Service
 
@@ -45,6 +45,8 @@ A Service may have the following properties:
 - `url: str (default - None)` - The URL where the service is/should be. If a
   url is specified for where the Service runs its own web server,
   the service will be added to the proxy at `/services/:name`
+- `api_token: str (default - None)` - For Externally-Managed Services you need to specify 
+  an API token to perform API requests to the Hub
 
 If a service is also to be managed by the Hub, it has a few extra options:
 
@@ -176,7 +178,13 @@ When you run a service that has a url, it will be accessible under a
 your service to route proxied requests properly, it must take
 `JUPYTERHUB_SERVICE_PREFIX` into account when routing requests. For example, a
 web service would normally service its root handler at `'/'`, but the proxied
-service would need to serve `JUPYTERHUB_SERVICE_PREFIX + '/'`.
+service would need to serve `JUPYTERHUB_SERVICE_PREFIX`.
+
+Note that `JUPYTERHUB_SERVICE_PREFIX` will contain a trailing slash. This must
+be taken into consideration when creating the service routes. If you include an
+extra slash you might get unexpected behavior. For example if your service has a
+`/foo` endpoint, the route would be `JUPYTERHUB_SERVICE_PREFIX + foo`, and
+`/foo/bar` would be `JUPYTERHUB_SERVICE_PREFIX + foo/bar`.
 
 ## Hub Authentication and Services
 
@@ -198,7 +206,9 @@ or via the `JUPYTERHUB_API_TOKEN` environment variable.
 
 Most of the logic for authentication implementation is found in the
 [`HubAuth.user_for_cookie`](services.auth.html#jupyterhub.services.auth.HubAuth.user_for_cookie)
-method, which makes a request of the Hub, and returns:
+and in the
+[`HubAuth.user_for_token`](services.auth.html#jupyterhub.services.auth.HubAuth.user_for_token)
+methods, which makes a request of the Hub, and returns:
 
 - None, if no user could be identified, or
 - a dict of the following form:
@@ -250,8 +260,11 @@ def authenticated(f):
     @wraps(f)
     def decorated(*args, **kwargs):
         cookie = request.cookies.get(auth.cookie_name)
+        token = request.headers.get(auth.auth_header_name)
         if cookie:
             user = auth.user_for_cookie(cookie)
+        elif token:
+            user = auth.user_for_token(token)
         else:
             user = None
         if user:
@@ -262,7 +275,7 @@ def authenticated(f):
     return decorated
 
 
-@app.route(prefix + '/')
+@app.route(prefix)
 @authenticated
 def whoami(user):
     return Response(
@@ -346,12 +359,14 @@ and taking note of the following process:
    ```
 
 An example of using an Externally-Managed Service and authentication is
-[nbviewer](https://github.com/jupyter/nbviewer#securing-the-notebook-viewer),
+in [nbviewer README]_ section on securing the notebook viewer,
 and an example of its configuration is found [here](https://github.com/jupyter/nbviewer/blob/master/nbviewer/providers/base.py#L94).
-nbviewer can also be run as a Hub-Managed Service as described [here](https://github.com/jupyter/nbviewer#securing-the-notebook-viewer).
+nbviewer can also be run as a Hub-Managed Service as described [nbviewer README]_
+section on securing the notebook viewer.
 
 
 [requests]: http://docs.python-requests.org/en/master/
-[services_auth]: api/services.auth.html
-[HubAuth]: api/services.auth.html#jupyterhub.services.auth.HubAuth
-[HubAuthenticated]: api/services.auth.html#jupyterhub.services.auth.HubAuthenticated
+[services_auth]: ../api/services.auth.html
+[HubAuth]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth
+[HubAuthenticated]: ../api/services.auth.html#jupyterhub.services.auth.HubAuthenticated
+[nbviewer example]: https://github.com/jupyter/nbviewer#securing-the-notebook-viewer

docs/source/reference/spawners.md

@@ -36,8 +36,7 @@ Some examples include:
 Information about the user can be retrieved from `self.user`,
 an object encapsulating the user's name, authentication, and server info.
 
-When `Spawner.start` returns, it should have stored the IP and port
-of the single-user server in `self.user.server`.
+The return value of `Spawner.start` should be the (ip, port) of the running server.
 
 **NOTE:** When writing coroutines, *never* `yield` in between a database change and a commit.
 
@@ -45,10 +44,10 @@ Most `Spawner.start` functions will look similar to this example:
 
 ```python
 def start(self):
-    self.user.server.ip = 'localhost' # or other host or IP address, as seen by the Hub
-    self.user.server.port = 1234 # port selected somehow
-    self.db.commit() # always commit before yield, if modifying db values
+    self.ip = '127.0.0.1'
+    self.port = random_port()
     yield self._actually_start_server_somehow()
+    return (self.ip, self.port)
 ```
 
 When `Spawner.start` returns, the single-user server process should actually be running,
@@ -114,7 +113,7 @@ This feature is enabled by setting `Spawner.options_form`, which is an HTML form
 inserted unmodified into the spawn form.
 If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
 
-![spawn-form](images/spawn-form.png)
+![spawn-form](../images/spawn-form.png)
 
 If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
 

docs/source/reference/technical-overview.md

@@ -0,0 +1,133 @@
+# Technical Overview
+
+The **Technical Overview** section gives you a high-level view of:
+
+- JupyterHub's Subsystems: Hub, Proxy, Single-User Notebook Server
+- how the subsystems interact
+- the process from JupyterHub access to user login
+- JupyterHub's default behavior
+- customizing JupyterHub
+
+The goal of this section is to share a deeper technical understanding of
+JupyterHub and how it works.
+
+## The Subsystems: Hub, Proxy, Single-User Notebook Server
+
+JupyterHub is a set of processes that together provide a single user Jupyter
+Notebook server for each person in a group. Three major subsystems are started
+by the `jupyterhub` command line program:
+
+- **Hub** (Python/Tornado): manages user accounts, authentication, and
+  coordinates Single User Notebook Servers using a Spawner.
+
+- **Proxy**: the public facing part of JupyterHub that uses a dynamic proxy
+  to route HTTP requests to the Hub and Single User Notebook Servers.
+  [configurable http proxy](https://github.com/jupyterhub/configurable-http-proxy)
+  (node-http-proxy) is the default proxy.
+
+- **Single-User Notebook Server** (Python/Tornado): a dedicated,
+  single-user, Jupyter Notebook server is started for each user on the system
+  when the user logs in. The object that starts the single-user notebook
+  servers is called a **Spawner**.    
+
+![JupyterHub subsystems](../images/jhub-parts.png)
+
+## How the Subsystems Interact
+
+Users access JupyterHub through a web browser, by going to the IP address or
+the domain name of the server.
+
+The basic principles of operation are:
+
+- The Hub spawns the proxy (in the default JupyterHub configuration)
+- The proxy forwards all requests to the Hub by default
+- The Hub handles login, and spawns single-user notebook servers on demand
+- The Hub configures the proxy to forward url prefixes to single-user notebook
+  servers
+
+The proxy is the only process that listens on a public interface. The Hub sits
+behind the proxy at `/hub`. Single-user servers sit behind the proxy at
+`/user/[username]`.
+
+Different **[authenticators](./authenticators.html)** control access
+to JupyterHub. The default one (PAM) uses the user accounts on the server where
+JupyterHub is running. If you use this, you will need to create a user account
+on the system for each user on your team. Using other authenticators, you can
+allow users to sign in with e.g. a GitHub account, or with any single-sign-on
+system your organization has.
+
+Next, **[spawners](./spawners.html)** control how JupyterHub starts
+the individual notebook server for each user. The default spawner will
+start a notebook server on the same machine running under their system username.
+The other main option is to start each server in a separate container, often
+using Docker.
+
+## The Process from JupyterHub Access to User Login
+
+When a user accesses JupyterHub, the following events take place:
+
+- Login data is handed to the [Authenticator](./authenticators.html) instance for
+  validation
+- The Authenticator returns the username if the login information is valid
+- A single-user notebook server instance is [spawned](./spawners.html) for the
+  logged-in user
+- When the single-user notebook server starts, the proxy is notified to forward
+  requests to `/user/[username]/*` to the single-user notebook server.
+- A cookie is set on `/hub/`, containing an encrypted token. (Prior to version
+  0.8, a cookie for `/user/[username]` was used too.)
+- The browser is redirected to `/user/[username]`, and the request is handled by
+  the single-user notebook server.
+
+The single-user server identifies the user with the Hub via OAuth:
+
+- on request, the single-user server checks a cookie
+- if no cookie is set, redirect to the Hub for verification via OAuth
+- after verification at the Hub, the browser is redirected back to the
+  single-user server
+- the token is verified and stored in a cookie
+- if no user is identified, the browser is redirected back to `/hub/login`
+
+## Default Behavior
+
+By default, the **Proxy** listens on all public interfaces on port 8000.
+Thus you can reach JupyterHub through either:
+
+- `http://localhost:8000`
+- or any other public IP or domain pointing to your system.
+
+In their default configuration, the other services, the **Hub** and
+**Single-User Notebook Servers**, all communicate with each other on localhost
+only.
+
+By default, starting JupyterHub will write two files to disk in the current
+working directory:
+
+- `jupyterhub.sqlite` is the SQLite database containing all of the state of the
+  **Hub**. This file allows the **Hub** to remember which users are running and
+  where, as well as storing other information enabling you to restart parts of
+  JupyterHub separately. It is important to note that this database contains
+  **no** sensitive information other than **Hub** usernames.
+- `jupyterhub_cookie_secret` is the encryption key used for securing cookies.
+  This file needs to persist so that a **Hub** server restart will avoid
+  invalidating cookies. Conversely, deleting this file and restarting the server
+  effectively invalidates all login cookies. The cookie secret file is discussed
+  in the [Cookie Secret section of the Security Settings document](../getting-started/security-basics.html).
+
+The location of these files can be specified via configuration settings. It is
+recommended that these files be stored in standard UNIX filesystem locations,
+such as `/etc/jupyterhub` for all configuration files and `/srv/jupyterhub` for
+all security and runtime files.
+
+## Customizing JupyterHub
+
+There are two basic extension points for JupyterHub:
+
+- How users are authenticated by [Authenticators](./authenticators.html)
+- How user's single-user notebook server processes are started by
+  [Spawners](./spawners.html)
+
+Each is governed by a customizable class, and JupyterHub ships with basic
+defaults for each.
+
+To enable custom authentication and/or spawning, subclass `Authenticator` or
+`Spawner`, and override the relevant methods.

docs/source/reference/upgrading.md

@@ -28,7 +28,7 @@ where traditional RDBMS may be a better choice](https://sqlite.org/whentouse.htm
 
 ## The upgrade process
 
-Four fundamental process steps are needed when upgrading JupyterHub and its
+Five fundamental process steps are needed when upgrading JupyterHub and its
 database:
 
 1. Backup JupyterHub database

docs/source/reference/websecurity.md

@@ -0,0 +1,112 @@
+# Security Overview
+
+The **Security Overview** section helps you learn about:
+
+- the design of JupyterHub with respect to web security
+- the semi-trusted user
+- the available mitigations to protect untrusted users from each other
+- the value of periodic security audits.
+
+This overview also helps you obtain a deeper understanding of how JupyterHub
+works.
+
+## Semi-trusted and untrusted users
+
+JupyterHub is designed to be a *simple multi-user server for modestly sized
+groups* of **semi-trusted** users. While the design reflects serving semi-trusted
+users, JupyterHub is not necessarily unsuitable for serving **untrusted** users.
+
+Using JupyterHub with **untrusted** users does mean more work by the
+administrator. Much care is required to secure a Hub, with extra caution on
+protecting users from each other as the Hub is serving untrusted users.
+
+One aspect of JupyterHub's *design simplicity* for **semi-trusted** users is that
+the Hub and single-user servers are placed in a *single domain*, behind a
+[*proxy*][configurable-http-proxy]. If the Hub is serving untrusted
+users, many of the web's cross-site protections are not applied between
+single-user servers and the Hub, or between single-user servers and each
+other, since browsers see the whole thing (proxy, Hub, and single user
+servers) as a single website (i.e. single domain).
+
+## Protect users from each other
+
+To protect users from each other, a user must **never** be able to write arbitrary
+HTML and serve it to another user on the Hub's domain. JupyterHub's
+authentication setup prevents a user writing arbitrary HTML and serving it to
+another user because only the owner of a given single-user notebook server is
+allowed to view user-authored pages served by the given single-user notebook
+server.
+
+To protect all users from each other, JupyterHub administrators must
+ensure that:
+
+* A user **does not have permission** to modify their single-user notebook server,
+  including:
+  - A user **may not** install new packages in the Python environment that runs
+    their single-user server.
+  - If the `PATH` is used to resolve the single-user executable (instead of
+    using an absolute path), a user **may not** create new files in any `PATH`
+    directory that precedes the directory containing `jupyterhub-singleuser`.
+  - A user may not modify environment variables (e.g. PATH, PYTHONPATH) for
+    their single-user server.
+* A user **may not** modify the configuration of the notebook server
+  (the `~/.jupyter` or `JUPYTER_CONFIG_DIR` directory).
+
+If any additional services are run on the same domain as the Hub, the services
+**must never** display user-authored HTML that is neither *sanitized* nor *sandboxed*
+(e.g. IFramed) to any user that lacks authentication as the author of a file.
+
+## Mitigate security issues
+
+Several approaches to mitigating these issues with configuration
+options provided by JupyterHub include:
+
+### Enable subdomains
+
+JupyterHub provides the ability to run single-user servers on their own
+subdomains. This means the cross-origin protections between servers has the
+desired effect, and user servers and the Hub are protected from each other. A
+user's single-user server will be at `username.jupyter.mydomain.com`. This also
+requires all user subdomains to point to the same address, which is most easily
+accomplished with wildcard DNS. Since this spreads the service across multiple
+domains, you will need wildcard SSL, as well. Unfortunately, for many
+institutional domains, wildcard DNS and SSL are not available. **If you do plan
+to serve untrusted users, enabling subdomains is highly encouraged**, as it
+resolves the cross-site issues.
+
+### Disable user config
+
+If subdomains are not available or not desirable, JupyterHub provides a a
+configuration option `Spawner.disable_user_config`, which can be set to prevent
+the user-owned configuration files from being loaded. After implementing this
+option, PATHs and package installation and PATHs are the other things that the
+admin must enforce.
+
+### Prevent spawners from evaluating shell configuration files
+
+For most Spawners, `PATH` is not something users can influence, but care should
+be taken to ensure that the Spawner does *not* evaluate shell configuration
+files prior to launching the server.
+
+### Isolate packages using virtualenv
+
+Package isolation is most easily handled by running the single-user server in
+a virtualenv with disabled system-site-packages. The user should not have
+permission to install packages into this environment.
+
+It is important to note that the control over the environment only affects the
+single-user server, and not the environment(s) in which the user's kernel(s)
+may run. Installing additional packages in the kernel environment does not
+pose additional risk to the web application's security.
+
+## Security audits
+
+We recommend that you do periodic reviews of your deployment's security. It's
+good practice to keep JupyterHub, configurable-http-proxy, and nodejs
+versions up to date.
+
+A handy website for testing your deployment is
+[Qualsys' SSL analyzer tool](https://www.ssllabs.com/ssltest/analyze.html).
+
+
+[configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy

docs/source/rest.md

@@ -1,70 +0,0 @@
-# Using JupyterHub's REST API
-
-Using the [JupyterHub REST API][], you can perform actions on the Hub,
-such as:
-
-- checking which users are active
-- adding or removing users
-- stopping or starting single user notebook servers
-- authenticating services
-
-A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
-API provides a standard way for users to get and send information to the
-Hub.
-
-
-## Creating an API token
-To send requests using JupyterHub API, you must pass an API token with the
-request. You can create a token for an individual user using the following
-command:
-
-    jupyterhub token USERNAME
-
-
-## Adding tokens to the config file
-You may also add a dictionary of API tokens and usernames to the hub's
-configuration file, `jupyterhub_config.py`:
-
-```python
-c.JupyterHub.api_tokens = {
-    'secret-token': 'username',
-}
-```
-
-
-## Making an API request
-
-To authenticate your requests, pass the API token in the request's
-Authorization header.
-
-**Example: List the hub's users**
-
-Using the popular Python requests library, the following code sends an API
-request and an API token for authorization:
-
-```python
-import requests
-
-api_url = 'http://127.0.0.1:8081/hub/api'
-
-r = requests.get(api_url + '/users',
-    headers={
-             'Authorization': 'token %s' % token,
-            }
-    )
-
-r.raise_for_status()
-users = r.json()
-```
-
-
-## Learning more about the API
-
-You can see the full [JupyterHub REST API][] for details.
-The same REST API Spec can be viewed in a more interactive style [on swagger's petstore][].
-Both resources contain the same information and differ only in its display.
-Note: The Swagger specification is being renamed the [OpenAPI Initiative][].
-
-[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
-[OpenAPI Initiative]: https://www.openapis.org/
-[JupyterHub REST API]: ./_static/rest-api/index.html

docs/source/troubleshooting.md

@@ -7,6 +7,8 @@ problem and how to resolve it.
 [*Behavior*](#behavior)
 - JupyterHub proxy fails to start
 - sudospawner fails to run
+- What is the default behavior when none of the lists (admin, whitelist,
+  group whitelist) are set?
 
 [*Errors*](#errors)
 - 500 error after spawning my single-user server
@@ -18,6 +20,9 @@ problem and how to resolve it.
 - How do I increase the number of pySpark executors on YARN?
 - How do I use JupyterLab's prerelease version with JupyterHub?
 - How do I set up JupyterHub for a workshop (when users are not known ahead of time)?
+- How do I set up rotating daily logs?
+- Toree integration with HDFS rack awareness script
+- Where do I find Docker images and Dockerfiles related to JupyterHub?
 
 [*Troubleshooting commands*](#troubleshooting-commands)
 
@@ -31,6 +36,10 @@ If you have tried to start the JupyterHub proxy and it fails to start:
   ``c.JupyterHub.ip = '*'``; if it is, try ``c.JupyterHub.ip = ''``
 - Try starting with ``jupyterhub --ip=0.0.0.0``
 
+**Note**: If this occurs on Ubuntu/Debian, check that the you are using a
+recent version of node. Some versions of Ubuntu/Debian come with a version
+of node that is very old, and it is necessary to update node.
+
 ### sudospawner fails to run
 
 If the sudospawner script is not found in the path, sudospawner will not run.
@@ -45,6 +54,16 @@ or add:
 
 to the config file, `jupyterhub_config.py`.
 
+### What is the default behavior when none of the lists (admin, whitelist, group whitelist) are set?
+
+When nothing is given for these lists, there will be no admins, and all users
+who can authenticate on the system (i.e. all the unix users on the server with
+a password) will be allowed to start a server. The whitelist lets you limit
+this to a particular set of users, and the admin_users lets you specify who
+among them may use the admin interface (not necessary, unless you need to do
+things like inspect other users' servers, or modify the userlist at runtime).
+
+
 ## Errors
 
 ### 500 error after spawning my single-user server
@@ -226,6 +245,31 @@ notebook servers to default to JupyterLab:
 
 Users will need a GitHub account to login and be authenticated by the Hub.
 
+### How do I set up rotating daily logs?
+
+You can do this with [logrotate](https://linux.die.net/man/8/logrotate),
+or pipe to `logger` to use syslog instead of directly to a file.
+
+For example, with this logrotate config file:
+
+```
+/var/log/jupyterhub.log {
+  copytruncate
+  daily
+}
+```
+
+and run this daily by putting a script in `/etc/cron.daily/`:
+
+```bash
+logrotate /path/to/above-config
+```
+
+Or use syslog:
+
+    jupyterhub | logger -t jupyterhub
+
+
 ## Troubleshooting commands
 
 The following commands provide additional detail about installed packages,
@@ -250,9 +294,9 @@ jupyter kernelspec list
 jupyterhub --debug
 ```
 
-## Toree integration with HDFS rack awareness script
+### Toree integration with HDFS rack awareness script
 
-The Apache Toree kernel will an issue, when running with JupyterHub, if the standard HDFS 
+The Apache Toree kernel will an issue, when running with JupyterHub, if the standard HDFS
 rack awareness script is used. This will materialize in the logs as a repeated WARN:
 
 ```bash
@@ -267,8 +311,17 @@ SyntaxError: Missing parentheses in call to 'print'
 
 In order to resolve this issue, there are two potential options.
 
-1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom 
+1. Update HDFS core-site.xml, so the parameter "net.topology.script.file.name" points to a custom
 script (e.g. /etc/hadoop/conf/custom_topology_script.py). Copy the original script and change the first line point
 to a python two installation (e.g. /usr/bin/python).
 2. In spark-env.sh add a Python 2 installation to your path (e.g. export PATH=/opt/anaconda2/bin:$PATH).
 
+### Where do I find Docker images and Dockerfiles related to JupyterHub?
+
+Docker images can be found at the [JupyterHub organization on DockerHub](https://hub.docker.com/u/jupyterhub/).
+The Docker image [jupyterhub/singleuser](https://hub.docker.com/r/jupyterhub/singleuser/)
+provides an example single user notebook server for use with DockerSpawner.
+
+Additional single user notebook server images can be found at the [Jupyter
+organization on DockerHub](https://hub.docker.com/r/jupyter/) and information
+about each image at the [jupyter/docker-stacks repo](https://github.com/jupyter/docker-stacks).

docs/source/tutorials/index.rst

@@ -0,0 +1,14 @@
+Tutorials
+=========
+
+This section provides links to documentation that helps a user do a specific
+task.
+
+* :doc:`upgrade-dot-eight`
+* `Zero to JupyterHub with Kubernetes <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   upgrade-dot-eight

docs/source/tutorials/upgrade-dot-eight.rst

@@ -0,0 +1,93 @@
+.. upgrade-dot-eight:
+
+Upgrading to JupyterHub version 0.8
+===================================
+
+This document will assist you in upgrading an existing JupyterHub deployment
+from version 0.7 to version 0.8.
+
+Upgrade checklist
+-----------------
+
+0. Review the release notes. Review any deprecated features and pay attention
+   to any backwards incompatible changes
+1. Backup JupyterHub database:
+    - ``jupyterhub.sqlite`` when using the default sqlite database
+    - Your JupyterHub database when using an RDBMS
+2. Backup the existing JupyterHub configuration file: ``jupyterhub_config.py``
+3. Shutdown the Hub
+4. Upgrade JupyterHub
+    - ``pip install -U jupyterhub`` when using ``pip``
+    - ``conda upgrade jupyterhub`` when using ``conda``
+5. Upgrade the database using run ```jupyterhub upgrade-db``
+6. Update the JupyterHub configuration file ``jupyterhub_config.py``
+
+Backup JupyterHub database
+--------------------------
+
+To prevent unintended loss of data or configuration information, you should
+back up the JupyterHub database (the default SQLite database or a RDBMS
+database using PostgreSQL, MySQL, or others supported by SQLAlchemy):
+
+- If using the default SQLite database, back up the ``jupyterhub.sqlite``
+  database.
+- If using an RDBMS database such as PostgreSQL, MySQL, or other supported by
+  SQLAlchemy, back up the JupyterHub database.
+
+.. note::
+
+    Losing the Hub database is often not a big deal. Information that resides only
+    in the Hub database includes:
+
+    - active login tokens (user cookies, service tokens)
+    - users added via GitHub UI, instead of config files
+    - info about running servers
+
+    If the following conditions are true, you should be fine clearing the Hub
+    database and starting over:
+
+    - users specified in config file
+    - user servers are stopped during upgrade
+    - don't mind causing users to login again after upgrade
+
+Backup JupyterHub configuration file
+------------------------------------
+
+Backup up your configuration file, ``jupyterhub_config.py``, to a secure
+location.
+
+Shutdown JupyterHub
+-------------------
+
+- Prior to shutting down JupyterHub, you should notify the Hub users of the
+  scheduled downtime.
+- Shutdown the JupyterHub service.
+
+Upgrade JupyterHub
+------------------
+
+Follow directions that correspond to your package manager, ``pip`` or ``conda``,
+for the new JupyterHub release:
+
+- ``pip install -U jupyterhub`` for ``pip``
+- ``conda upgrade jupyterhub`` for ``conda``
+
+Upgrade the proxy, authenticator, or spawner if needed.
+
+Upgrade JupyterHub database
+---------------------------
+
+To run the upgrade process for JupyterHub databases, enter::
+
+    jupyterhub upgrade-db
+
+Update the JupyterHub configuration file
+----------------------------------------
+
+Create a new JupyterHub configuration file or edit a copy of the existing
+file ``jupyterhub_config.py``.
+
+Start JupyterHub
+----------------
+
+Start JupyterHub with the same command that you used before the upgrade.

docs/source/websecurity.md

@@ -1,80 +0,0 @@
-# Web Security in JupyterHub
-
-JupyterHub is designed to be a simple multi-user server for modestly sized
-groups of semi-trusted users. While the design reflects serving semi-trusted
-users, JupyterHub is not necessarily unsuitable for serving untrusted users.
-Using JupyterHub with untrusted users does mean more work and much care is
-required to secure a Hub against untrusted users, with extra caution on
-protecting users from each other as the Hub is serving untrusted users.
-
-One aspect of JupyterHub's design simplicity for semi-trusted users is that
-the Hub and single-user servers are placed in a single domain, behind a
-[proxy][configurable-http-proxy]. As a result, if the Hub is serving untrusted
-users, many of the web's cross-site protections are not applied between
-single-user servers and the Hub, or between single-user servers and each
-other, since browsers see the whole thing (proxy, Hub, and single user
-servers) as a single website.
-
-To protect users from each other, a user must never be able to write arbitrary
-HTML and serve it to another user on the Hub's domain. JupyterHub's
-authentication setup prevents this because only the owner of a given
-single-user server is allowed to view user-authored pages served by their
-server. To protect all users from each other, JupyterHub administrators must
-ensure that:
-
-* A user does not have permission to modify their single-user server:
-  - A user may not install new packages in the Python environment that runs
-    their server.
-  - If the PATH is used to resolve the single-user executable (instead of an
-    absolute path), a user may not create new files in any PATH directory
-    that precedes the directory containing jupyterhub-singleuser.
-  - A user may not modify environment variables (e.g. PATH, PYTHONPATH) for
-    their single-user server.
-* A user may not modify the configuration of the notebook server
-  (the ~/.jupyter or JUPYTER_CONFIG_DIR directory).
-
-If any additional services are run on the same domain as the Hub, the services
-must never display user-authored HTML that is neither sanitized nor sandboxed
-(e.g. IFramed) to any user that lacks authentication as the author of a file.
-
-
-## Mitigations
-
-There are two main configuration options provided by JupyterHub to mitigate
-these issues:
-
-### Subdomains
-
-JupyterHub 0.5 adds the ability to run single-user servers on their own
-subdomains, which means the cross-origin protections between servers has the
-desired effect, and user servers and the Hub are protected from each other. A
-user's server will be at `username.jupyter.mydomain.com`, etc. This requires
-all user subdomains to point to the same address, which is most easily
-accomplished with wildcard DNS. Since this spreads the service across multiple
-domains, you will need wildcard SSL, as well. Unfortunately, for many
-institutional domains, wildcard DNS and SSL are not available, but if you do
-plan to serve untrusted users, enabling subdomains is highly encouraged, as it
-resolves all of the cross-site issues.
-
-### Disabling user config
-
-If subdomains are not available or not desirable, 0.5 also adds an option
-`Spawner.disable_user_config`, which you can set to prevent the user-owned
-configuration files from being loaded. This leaves only package installation
-and PATHs as things the admin must enforce.
-
-For most Spawners, PATH is not something users can influence, but care should
-be taken to ensure that the Spawn does *not* evaluate shell configuration
-files prior to launching the server.
-
-Package isolation is most easily handled by running the single-user server in
-a virtualenv with disabled system-site-packages.
-
-## Extra notes
-
-It is important to note that the control over the environment only affects the
-single-user server, and not the environment(s) in which the user's kernel(s)
-may run. Installing additional packages in the kernel environment does not
-pose additional risk to the web application's security.
-
-[configurable-http-proxy]: https://github.com/jupyterhub/configurable-http-proxy

docs/sphinxext/autodoc_traits.py

@@ -0,0 +1,54 @@
+"""autodoc extension for configurable traits"""
+
+from traitlets import TraitType, Undefined
+from sphinx.domains.python import PyClassmember
+from sphinx.ext.autodoc import ClassDocumenter, AttributeDocumenter
+
+
+class ConfigurableDocumenter(ClassDocumenter):
+    """Specialized Documenter subclass for traits with config=True"""
+    objtype = 'configurable'
+    directivetype = 'class'
+
+    def get_object_members(self, want_all):
+        """Add traits with .tag(config=True) to members list"""
+        check, members = super().get_object_members(want_all)
+        get_traits = self.object.class_own_traits if self.options.inherited_members \
+                     else self.object.class_traits
+        trait_members = []
+        for name, trait in sorted(get_traits(config=True).items()):
+            # put help in __doc__ where autodoc will look for it
+            trait.__doc__ = trait.help
+            trait_members.append((name, trait))
+        return check, trait_members + members
+
+
+class TraitDocumenter(AttributeDocumenter):
+    objtype = 'trait'
+    directivetype = 'attribute'
+    member_order = 1
+    priority = 100
+
+    @classmethod
+    def can_document_member(cls, member, membername, isattr, parent):
+        return isinstance(member, TraitType)
+
+    def format_name(self):
+        return 'config c.' + super().format_name()
+
+    def add_directive_header(self, sig):
+        default = self.object.get_default_value()
+        if default is Undefined:
+            default_s = ''
+        else:
+            default_s = repr(default)
+        sig = ' = {}({})'.format(
+            self.object.__class__.__name__,
+            default_s,
+        )
+        return super().add_directive_header(sig)
+
+
+def setup(app):
+    app.add_autodocumenter(ConfigurableDocumenter)
+    app.add_autodocumenter(TraitDocumenter)

examples/bootstrap-script/README.md

@@ -0,0 +1,130 @@
+# Bootstrapping your users
+
+Before spawning a notebook to the user, it could be useful to 
+do some preparation work in a bootstrapping process.
+
+Common use cases are:
+
+*Providing writeable storage for LDAP users*
+
+Your Jupyterhub is configured to use the LDAPAuthenticator and DockerSpawer.
+
+* The user has no file directory on the host since your are using LDAP.
+* When a user has no directory and DockerSpawner wants to mount a volume,
+the spawner will use docker to create a directory.
+Since the docker daemon is running as root, the generated directory for the volume 
+mount will not be writeable by the `jovyan` user inside of the container. 
+For the directory to be useful to the user, the permissions on the directory 
+need to be modified for the user to have write access.
+
+*Prepopulating Content*
+
+Another use would be to copy initial content, such as tutorial files or reference
+ material, into the user's space when a notebook server is newly spawned.
+
+You can define your own bootstrap process by implementing a `pre_spawn_hook` on any spawner.
+The Spawner itself is passed as parameter to your hook and you can easily get the contextual information out of the spawning process. 
+
+If you implement a hook, make sure that it is *idempotent*. It will be executed every time 
+a notebook server is spawned to the user. That means you should somehow 
+ensure that things which should run only once are not running again and again.
+For example, before you create a directory, check if it exists.
+
+Bootstrapping examples:
+
+### Example #1 - Create a user directory
+
+Create a directory for the user, if none exists
+
+```python
+
+# in jupyterhub_config.py  
+import os
+def create_dir_hook(spawner):
+    username = spawner.user.name # get the username
+    volume_path = os.path.join('/volumes/jupyterhub', username)
+    if not os.path.exists(volume_path):
+        # create a directory with umask 0755 
+        # hub and container user must have the same UID to be writeable
+        # still readable by other users on the system
+        os.mkdir(volume_path, 0o755)
+        # now do whatever you think your user needs
+        # ...
+        pass
+
+# attach the hook function to the spawner
+c.Spawner.pre_spawn_hook = create_dir_hook
+```
+
+### Example #2 - Run a shell script 
+
+You can specify a plain ole' shell script (or any other executable) to be run 
+by the bootstrap process.
+
+For example, you can execute a shell script and as first parameter pass the name 
+of the user:
+
+```python
+
+# in jupyterhub_config.py    
+from subprocess import check_call
+import os
+def my_script_hook(spawner):
+    username = spawner.user.name # get the username
+    script = os.path.join(os.path.dirname(__file__), 'bootstrap.sh')
+    check_call([script, username])
+
+# attach the hook function to the spawner
+c.Spawner.pre_spawn_hook = my_script_hook
+
+```
+
+Here's an example on what you could do in your shell script. See also 
+`/examples/bootstrap-script/`
+
+```bash
+#!/bin/bash
+
+# Bootstrap example script
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+# - The first parameter for the Bootstrap Script is the USER.
+USER=$1
+if ["$USER" == ""]; then
+    exit 1
+fi
+# ----------------------------------------------------------------------------
+
+
+# This example script will do the following:
+# - create one directory for the user $USER in a BASE_DIRECTORY (see below)
+# - create a "tutorials" directory within and download and unzip 
+#   the PythonDataScienceHandbook from GitHub
+
+# Start the Bootstrap Process
+echo "bootstrap process running for user $USER ..."
+
+# Base Directory: All Directories for the user will be below this point
+BASE_DIRECTORY=/volumes/jupyterhub/
+
+# User Directory: That's the private directory for the user to be created, if none exists
+USER_DIRECTORY=$BASE_DIRECTORY/$USER
+
+if [ -d "$USER_DIRECTORY" ]; then
+    echo "...directory for user already exists. skipped"
+    exit 0 # all good. nothing to do.
+else
+    echo "...creating a directory for the user: $USER_DIRECTORY"
+    mkdir $USER_DIRECTORY
+
+    echo "...initial content loading for user ..."
+    mkdir $USER_DIRECTORY/tutorials
+    cd $USER_DIRECTORY/tutorials
+    wget https://github.com/jakevdp/PythonDataScienceHandbook/archive/master.zip
+    unzip -o master.zip
+    rm master.zip
+fi
+
+exit 0
+```

examples/bootstrap-script/bootstrap.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Bootstrap example script
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+# - The first parameter for the Bootstrap Script is the USER.
+USER=$1
+if ["$USER" == ""]; then
+    exit 1
+fi
+# ----------------------------------------------------------------------------
+
+
+# This example script will do the following:
+# - create one directory for the user $USER in a BASE_DIRECTORY (see below)
+# - create a "tutorials" directory within and download and unzip the PythonDataScienceHandbook from GitHub
+
+# Start the Bootstrap Process
+echo "bootstrap process running for user $USER ..."
+
+# Base Directory: All Directories for the user will be below this point
+BASE_DIRECTORY=/volumes/jupyterhub
+
+# User Directory: That's the private directory for the user to be created, if none exists
+USER_DIRECTORY=$BASE_DIRECTORY/$USER
+
+if [ -d "$USER_DIRECTORY" ]; then
+    echo "...directory for user already exists. skipped"
+    exit 0 # all good. nothing to do.
+else
+    echo "...creating a directory for the user: $USER_DIRECTORY"
+    mkdir $USER_DIRECTORY
+
+    # mkdir did not succeed?
+    if [ $? -ne 0 ] ; then
+        exit 1
+    fi
+
+    echo "...initial content loading for user ..."
+    mkdir $USER_DIRECTORY/tutorials
+    cd $USER_DIRECTORY/tutorials
+    wget https://github.com/jakevdp/PythonDataScienceHandbook/archive/master.zip
+    unzip -o master.zip
+    rm master.zip
+fi
+
+exit 0

examples/bootstrap-script/jupyterhub_config.py

@@ -0,0 +1,26 @@
+# Example for a Spawner.pre_spawn_hook
+# create a directory for the user before the spawner starts
+
+import os
+def create_dir_hook(spawner):
+    username = spawner.user.name # get the username
+    volume_path = os.path.join('/volumes/jupyterhub', username)
+    if not os.path.exists(volume_path):
+        os.mkdir(volume_path, 0o755)
+        # now do whatever you think your user needs
+        # ...
+
+# attach the hook function to the spawner
+c.Spawner.pre_spawn_hook = create_dir_hook
+
+# Use the DockerSpawner to serve your users' notebooks
+c.JupyterHub.spawner_class = 'dockerspawner.DockerSpawner'
+from jupyter_client.localinterfaces import public_ips
+c.JupyterHub.hub_ip = public_ips()[0]
+c.DockerSpawner.hub_ip_connect = public_ips()[0]
+c.DockerSpawner.container_ip = "0.0.0.0"
+
+# You can now mount the volume to the docker container as we've
+# made sure the directory exists
+c.DockerSpawner.volumes = { '/volumes/jupyterhub/{username}/': '/home/jovyan/work' }
+

examples/cull-idle/cull_idle_servers.py

@@ -40,8 +40,11 @@ from tornado.options import define, options, parse_command_line
 
 
 @coroutine
-def cull_idle(url, api_token, timeout):
-    """cull idle single-user servers"""
+def cull_idle(url, api_token, timeout, cull_users=False):
+    """Shutdown idle single-user servers
+
+    If cull_users, inactive *users* will be deleted as well.
+    """
     auth_header = {
             'Authorization': 'token %s' % api_token
         }
@@ -54,26 +57,50 @@ def cull_idle(url, api_token, timeout):
     resp = yield client.fetch(req)
     users = json.loads(resp.body.decode('utf8', 'replace'))
     futures = []
-    for user in users:
-        last_activity = parse_date(user['last_activity'])
-        if user['server'] and last_activity < cull_limit:
-            app_log.info("Culling %s (inactive since %s)", user['name'], last_activity)
+
+    @coroutine
+    def cull_one(user, last_activity):
+        """cull one user"""
+
+        # shutdown server first. Hub doesn't allow deleting users with running servers.
+        if user['server']:
+            app_log.info("Culling server for %s (inactive since %s)", user['name'], last_activity)
             req = HTTPRequest(url=url + '/users/%s/server' % user['name'],
                 method='DELETE',
                 headers=auth_header,
             )
-            futures.append((user['name'], client.fetch(req)))
-        elif user['server'] and last_activity > cull_limit:
+            yield client.fetch(req)
+        if cull_users:
+            app_log.info("Culling user %s (inactive since %s)", user['name'], last_activity)
+            req = HTTPRequest(url=url + '/users/%s' % user['name'],
+                method='DELETE',
+                headers=auth_header,
+            )
+            yield client.fetch(req)
+
+    for user in users:
+        if not user['server'] and not cull_users:
+            # server not running and not culling users, nothing to do
+            continue
+        last_activity = parse_date(user['last_activity'])
+        if last_activity < cull_limit:
+            futures.append((user['name'], cull_one(user, last_activity)))
+        else:
             app_log.debug("Not culling %s (active since %s)", user['name'], last_activity)
     
     for (name, f) in futures:
         yield f
         app_log.debug("Finished culling %s", name)
 
+
 if __name__ == '__main__':
     define('url', default=os.environ.get('JUPYTERHUB_API_URL'), help="The JupyterHub API URL")
     define('timeout', default=600, help="The idle timeout (in seconds)")
     define('cull_every', default=0, help="The interval (in seconds) for checking for idle servers to cull")
+    define('cull_users', default=False,
+        help="""Cull users in addition to servers.
+                This is for use in temporary-user cases such as tmpnb.""",
+    )
     
     parse_command_line()
     if not options.cull_every:
@@ -82,7 +109,7 @@ if __name__ == '__main__':
     api_token = os.environ['JUPYTERHUB_API_TOKEN']
     
     loop = IOLoop.current()
-    cull = lambda : cull_idle(options.url, api_token, options.timeout)
+    cull = lambda : cull_idle(options.url, api_token, options.timeout, options.cull_users)
     # run once before scheduling periodic call
     loop.run_sync(cull)
     # schedule periodic cull

examples/service-notebook/README.md

@@ -0,0 +1,25 @@
+# Running a shared notebook as a service
+
+This directory contains two examples of running a shared notebook server as a service,
+one as a 'managed' service, and one as an external service with supervisor.
+
+These examples require jupyterhub >= 0.7.2.
+
+A single-user notebook server is run as a service,
+and uses groups to authenticate a collection of users with the Hub.
+
+In these examples, a JupyterHub group `'shared'` is created,
+and a notebook server is spawned at `/services/shared-notebook`.
+Any user in the `'shared'` group will be able to access the notebook server at `/services/shared-notebook/`.
+
+In both examples, you will want to select the name of the group,
+and the name of the shared-notebook service.
+
+In the external example, some extra steps are required to set up supervisor:
+
+1. select a system user to run the service. This is  a user on the system, and does not need to be a Hub user. Add this to the user field in `shared-notebook.conf`, replacing `someuser`.
+2. generate a secret token for authentication, and replace the `super-secret` fields in `shared-notebook-service` and `jupyterhub_config.py`
+3. install `shared-notebook-service` somewhere on your system, and update `/path/to/shared-notebook-service` to the absolute path of this destination
+3. copy `shared-notebook.conf` to `/etc/supervisor/conf.d/`
+4. `supervisorctl reload`
+

examples/service-notebook/external/jupyterhub_config.py

@@ -0,0 +1,24 @@
+# our user list
+c.Authenticator.whitelist = [
+    'minrk',
+    'ellisonbg',
+    'willingc',
+]
+
+# ellisonbg and willingc have access to a shared server:
+
+c.JupyterHub.load_groups = {
+    'shared': [
+        'ellisonbg',
+        'willingc',
+    ]
+}
+
+# start the notebook server as a service
+c.JupyterHub.services = [
+    {
+        'name': 'shared-notebook',
+        'url': 'http://127.0.0.1:9999',
+        'api_token': 'super-secret',
+    }
+]

examples/service-notebook/external/shared-notebook-service

@@ -0,0 +1,9 @@
+#!/bin/bash -l
+set -e
+
+export JUPYTERHUB_API_TOKEN=super-secret
+export JUPYTERHUB_SERVICE_URL=http://127.0.0.1:9999
+export JUPYTERHUB_SERVICE_NAME=shared-notebook
+
+jupyterhub-singleuser \
+    --group='shared'

examples/service-notebook/external/shared-notebook.conf

@@ -0,0 +1,14 @@
+[program:jupyterhub-shared-notebook]
+user=someuser
+command=bash -l /path/to/shared-notebook-service
+directory=/home/someuser
+autostart=true
+autorestart=true
+startretries=1
+exitcodes=0,2
+stopsignal=TERM
+redirect_stderr=true
+stdout_logfile=/var/log/jupyterhub-service-shared-notebook.log
+stdout_logfile_maxbytes=1MB
+stdout_logfile_backups=10
+stdout_capture_maxbytes=1MB

examples/service-notebook/managed/jupyterhub_config.py

@@ -0,0 +1,32 @@
+# our user list
+c.Authenticator.whitelist = [
+    'minrk',
+    'ellisonbg',
+    'willingc',
+]
+
+# ellisonbg and willingc have access to a shared server:
+
+c.JupyterHub.load_groups = {
+    'shared': [
+        'ellisonbg',
+        'willingc',
+    ]
+}
+
+service_name = 'shared-notebook'
+service_port = 9999
+group_name = 'shared'
+
+# start the notebook server as a service
+c.JupyterHub.services = [
+    {
+        'name': service_name,
+        'url': 'http://127.0.0.1:{}'.format(service_port),
+        'command': [
+            'jupyterhub-singleuser',
+            '--group=shared',
+            '--debug',
+        ],
+    }
+]

examples/service-whoami-flask/README.md

@@ -8,7 +8,7 @@ Uses `jupyterhub.services.HubAuth` to authenticate requests with the Hub in a [f
 
         jupyterhub --ip=127.0.0.1
 
-2. Visit http://127.0.0.1:8000/services/whoami
+2. Visit http://127.0.0.1:8000/services/whoami/ or http://127.0.0.1:8000/services/whoami-oauth/
 
 After logging in with your local-system credentials, you should see a JSON dump of your user info:
 

examples/service-whoami-flask/jupyterhub_config.py

@@ -9,5 +9,13 @@ c.JupyterHub.services = [
         'environment': {
             'FLASK_APP': 'whoami-flask.py',
         }
-    }
+    },
+    {
+        'name': 'whoami-oauth',
+        'url': 'http://127.0.0.1:10201',
+        'command': ['flask', 'run', '--port=10201'],
+        'environment': {
+            'FLASK_APP': 'whoami-oauth.py',
+        }
+    },
 ]

examples/service-whoami-flask/whoami-flask.py

@@ -17,7 +17,7 @@ prefix = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '/')
 
 auth = HubAuth(
     api_token=os.environ['JUPYTERHUB_API_TOKEN'],
-    cookie_cache_max_age=60,
+    cache_max_age=60,
 )
 
 app = Flask(__name__)
@@ -28,8 +28,11 @@ def authenticated(f):
     @wraps(f)
     def decorated(*args, **kwargs):
         cookie = request.cookies.get(auth.cookie_name)
+        token = request.headers.get(auth.auth_header_name)
         if cookie:
             user = auth.user_for_cookie(cookie)
+        elif token:
+            user = auth.user_for_token(token)
         else:
             user = None
         if user:
@@ -40,7 +43,7 @@ def authenticated(f):
     return decorated
 
 
-@app.route(prefix + '/')
+@app.route(prefix)
 @authenticated
 def whoami(user):
     return Response(

examples/service-whoami-flask/whoami-oauth.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""
+whoami service authentication with the Hub
+"""
+
+from functools import wraps
+import json
+import os
+
+from flask import Flask, redirect, request, Response, make_response
+
+from jupyterhub.services.auth import HubOAuth
+
+
+prefix = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '/')
+
+auth = HubOAuth(
+    api_token=os.environ['JUPYTERHUB_API_TOKEN'],
+    cache_max_age=60,
+)
+
+app = Flask(__name__)
+
+
+def authenticated(f):
+    """Decorator for authenticating with the Hub via OAuth"""
+    @wraps(f)
+    def decorated(*args, **kwargs):
+        token = request.cookies.get(auth.cookie_name)
+        if token:
+            user = auth.user_for_token(token)
+        else:
+            user = None
+        if user:
+            return f(user, *args, **kwargs)
+        else:
+            # redirect to login url on failed auth
+            state = auth.generate_state(next_url=request.path)
+            response = make_response(redirect(auth.login_url + '&state=%s' % state))
+            response.set_cookie(auth.state_cookie_name, state)
+            return response
+    return decorated
+
+
+@app.route(prefix)
+@authenticated
+def whoami(user):
+    return Response(
+        json.dumps(user, indent=1, sort_keys=True),
+        mimetype='application/json',
+        )
+
+@app.route(prefix + 'oauth_callback')
+def oauth_callback():
+    code = request.args.get('code', None)
+    if code is None:
+        return 403
+
+    # validate state field
+    arg_state = request.args.get('state', None)
+    cookie_state = request.cookies.get(auth.state_cookie_name)
+    if arg_state is None or arg_state != cookie_state:
+        # state doesn't match
+        return 403
+
+    token = auth.token_for_code(code)
+    next_url = auth.get_next_url(cookie_state) or prefix
+    response = make_response(redirect(next_url))
+    response.set_cookie(auth.cookie_name, token)
+    return response

examples/service-whoami/README.md

@@ -2,13 +2,15 @@
 
 Uses `jupyterhub.services.HubAuthenticated` to authenticate requests with the Hub.
 
+There is an implementation each of cookie-based `HubAuthenticated` and OAuth-based `HubOAuthenticated`.
+
 ## Run
 
 1. Launch JupyterHub and the `whoami service` with
 
         jupyterhub --ip=127.0.0.1
 
-2. Visit http://127.0.0.1:8000/services/whoami
+2. Visit http://127.0.0.1:8000/services/whoami or http://127.0.0.1:8000/services/whoami-oauth
 
 After logging in with your local-system credentials, you should see a JSON dump of your user info:
 

examples/service-whoami/jupyterhub_config.py

@@ -6,5 +6,10 @@ c.JupyterHub.services = [
         'name': 'whoami',
         'url': 'http://127.0.0.1:10101',
         'command': [sys.executable, './whoami.py'],
-    }
+    },
+    {
+        'name': 'whoami-oauth',
+        'url': 'http://127.0.0.1:10102',
+        'command': [sys.executable, './whoami-oauth.py'],
+    },
 ]

examples/service-whoami/whoami-oauth.py

@@ -13,10 +13,10 @@ from tornado.ioloop import IOLoop
 from tornado.httpserver import HTTPServer
 from tornado.web import RequestHandler, Application, authenticated
 
-from jupyterhub.services.auth import HubAuthenticated
+from jupyterhub.services.auth import HubOAuthenticated, HubOAuthCallbackHandler
+from jupyterhub.utils import url_path_join
 
-
-class WhoAmIHandler(HubAuthenticated, RequestHandler):
+class WhoAmIHandler(HubOAuthenticated, RequestHandler):
     hub_users = {getuser()} # the users allowed to access this service
 
     @authenticated
@@ -27,9 +27,10 @@ class WhoAmIHandler(HubAuthenticated, RequestHandler):
 
 def main():
     app = Application([
-        (os.environ['JUPYTERHUB_SERVICE_PREFIX'] + '/?', WhoAmIHandler),
+        (os.environ['JUPYTERHUB_SERVICE_PREFIX'], WhoAmIHandler),
+        (url_path_join(os.environ['JUPYTERHUB_SERVICE_PREFIX'], 'oauth_callback'), HubOAuthCallbackHandler),
         (r'.*', WhoAmIHandler),
-    ], login_url='/hub/login')
+    ], cookie_secret=os.urandom(32))
     
     http_server = HTTPServer(app)
     url = urlparse(os.environ['JUPYTERHUB_SERVICE_URL'])

examples/service-whoami/whoami.py

@@ -27,7 +27,7 @@ def main():
     app = Application([
         (os.environ['JUPYTERHUB_SERVICE_PREFIX'] + '/?', WhoAmIHandler),
         (r'.*', WhoAmIHandler),
-    ], login_url='/hub/login')
+    ])
     
     http_server = HTTPServer(app)
     url = urlparse(os.environ['JUPYTERHUB_SERVICE_URL'])

jupyterhub/__init__.py

@@ -1,2 +1 @@
-from .version import version_info, __version__
-
+from ._version import version_info, __version__

jupyterhub/_data.py

@@ -1,5 +1,6 @@
 """Get the data files for this package."""
 
+
 def get_data_files():
     """Walk up until we find share/jupyter/hub"""
     import sys
@@ -12,7 +13,8 @@ def get_data_files():
         # walk up, looking for prefix/share/jupyter
         while path != '/':
             share_jupyter = join(path, 'share', 'jupyter', 'hub')
-            if exists(join(share_jupyter, 'static', 'components')):
+            static = join(share_jupyter, 'static')
+            if all(exists(join(static, f)) for f in ['components', 'css']):
                 return share_jupyter
             path, _ = split(path)
     # didn't find it, give up
@@ -21,4 +23,3 @@ def get_data_files():
 
 # Package managers can just override this with the appropriate constant
 DATA_FILES_PATH = get_data_files()
-

jupyterhub/_version.py

@@ -0,0 +1,46 @@
+"""JupyterHub version info"""
+
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+version_info = (
+    0,
+    8,
+    1,
+    # 'dev',
+)
+
+__version__ = '.'.join(map(str, version_info))
+
+
+def _check_version(hub_version, singleuser_version, log):
+    """Compare Hub and single-user server versions"""
+    if not hub_version:
+        log.warning("Hub has no version header, which means it is likely < 0.8. Expected %s", __version__)
+        return
+
+    if not singleuser_version:
+        log.warning("Single-user server has no version header, which means it is likely < 0.8. Expected %s", __version__)
+        return
+
+    # compare minor X.Y versions
+    if hub_version != singleuser_version:
+        from distutils.version import LooseVersion as V
+        hub_major_minor = V(hub_version).version[:2]
+        singleuser_major_minor = V(singleuser_version).version[:2]
+        extra = ""
+        if singleuser_major_minor == hub_major_minor:
+            # patch-level mismatch or lower, log difference at debug-level
+            # because this should be fine
+            log_method = log.debug
+        else:
+            # log warning-level for more significant mismatch, such as 0.8 vs 0.9, etc.
+            log_method = log.warning
+            extra = " This could cause failure to authenticate and result in redirect loops!"
+        log_method(
+            "jupyterhub version %s != jupyterhub-singleuser version %s." + extra,
+            hub_version,
+            singleuser_version,
+        )
+    else:
+        log.debug("jupyterhub and jupyterhub-singleuser both on version %s" % hub_version)

jupyterhub/alembic.ini

@@ -62,5 +62,6 @@ level = NOTSET
 formatter = generic
 
 [formatter_generic]
-format = %(levelname)-5.5s [%(name)s] %(message)s
-datefmt = %H:%M:%S
+class = jupyterhub.log.CoroutineLogFormatter
+format = %(color)s[%(levelname)1.1s %(asctime)s.%(msecs).03d %(name)s %(module)s:%(lineno)d]%(end_color)s %(message)s
+datefmt = %Y-%m-%d %H:%M:%S

jupyterhub/alembic/env.py

@@ -1,6 +1,8 @@
-from __future__ import with_statement
+import sys
+
 from alembic import context
 from sqlalchemy import engine_from_config, pool
+import logging
 from logging.config import fileConfig
 
 # this is the Alembic Config object, which provides
@@ -9,7 +11,24 @@ config = context.config
 
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
-fileConfig(config.config_file_name)
+if 'jupyterhub' in sys.modules:
+    from traitlets.config import MultipleInstanceError
+    from jupyterhub.app import JupyterHub
+    app = None
+    if JupyterHub.initialized():
+        try:
+            app = JupyterHub.instance()
+        except MultipleInstanceError:
+            # could have been another Application
+            pass
+    if app is not None:
+        alembic_logger = logging.getLogger('alembic')
+        alembic_logger.propagate = True
+        alembic_logger.parent = app.log
+    else:
+        fileConfig(config.config_file_name)
+else:
+    fileConfig(config.config_file_name)
 
 # add your model's MetaData object here
 # for 'autogenerate' support

jupyterhub/alembic/versions/3ec6993fe20c_encrypted_auth_state.py

@@ -0,0 +1,68 @@
+"""0.8 changes
+
+- encrypted auth_state
+- remove proxy/hub data from db
+
+OAuth data was also added in this revision,
+but no migration to do because they are entirely new tables,
+which will be created on launch.
+
+Revision ID: 3ec6993fe20c
+Revises: af4cbdb2d13c
+Create Date: 2017-07-28 16:44:40.413648
+
+"""
+
+# revision identifiers, used by Alembic.
+revision = '3ec6993fe20c'
+down_revision = 'af4cbdb2d13c'
+branch_labels = None
+depends_on = None
+
+import logging
+
+logger = logging.getLogger('alembic')
+
+from alembic import op
+import sqlalchemy as sa
+from jupyterhub.orm import JSONDict
+
+
+def upgrade():
+    # proxy/table info is no longer in the database
+    op.drop_table('proxies')
+    op.drop_table('hubs')
+
+    # drop some columns no longer in use
+    try:
+        op.drop_column('users', 'auth_state')
+        # mysql cannot drop _server_id without also dropping
+        # implicitly created foreign key
+        if op.get_context().dialect.name == 'mysql':
+            op.drop_constraint('users_ibfk_1', 'users',  type_='foreignkey')
+        op.drop_column('users', '_server_id')
+    except sa.exc.OperationalError:
+        # this won't be a problem moving forward, but downgrade will fail
+        if op.get_context().dialect.name == 'sqlite':
+            logger.warning("sqlite cannot drop columns. Leaving unused old columns in place.")
+        else:
+            raise
+
+    op.add_column('users', sa.Column('encrypted_auth_state', sa.types.LargeBinary))
+
+
+def downgrade():
+    # drop all the new tables
+    engine = op.get_bind().engine
+    for table in ('oauth_clients',
+                  'oauth_codes',
+                  'oauth_access_tokens',
+                  'spawners'):
+        if engine.has_table(table):
+            op.drop_table(table)
+
+    op.drop_column('users', 'encrypted_auth_state')
+
+    op.add_column('users', sa.Column('auth_state', JSONDict))
+    op.add_column('users',  sa.Column('_server_id', sa.Integer, sa.ForeignKey('servers.id')))
+

jupyterhub/apihandlers/auth.py

@@ -6,32 +6,63 @@
 import json
 from urllib.parse import quote
 
+from oauth2.web.tornado import OAuth2Handler
 from tornado import web, gen
+
 from .. import orm
 from ..utils import token_authenticated
-from .base import APIHandler
+from .base import BaseHandler, APIHandler
 
 
 class TokenAPIHandler(APIHandler):
     @token_authenticated
     def get(self, token):
         orm_token = orm.APIToken.find(self.db, token)
+        if orm_token is None:
+            orm_token = orm.OAuthAccessToken.find(self.db, token)
         if orm_token is None:
             raise web.HTTPError(404)
-        self.write(json.dumps(self.user_model(self.users[orm_token.user])))
+        if orm_token.user:
+            model = self.user_model(self.users[orm_token.user])
+        elif orm_token.service:
+            model = self.service_model(orm_token.service)
+        else:
+            self.log.warning("%s has no user or service. Deleting..." % orm_token)
+            self.db.delete(orm_token)
+            self.db.commit()
+            raise web.HTTPError(404)
+        self.write(json.dumps(model))
 
     @gen.coroutine
     def post(self):
-        if self.authenticator is not None:
-          data = self.get_json_body()
-          username = yield self.authenticator.authenticate(self, data)
-          if username is None:
-            raise web.HTTPError(403)
-          user = self.find_user(username)
-          api_token = user.new_api_token()
-          self.write(json.dumps({"Authentication":api_token}))
+        user = self.get_current_user()
+        if user is None:
+            # allow requesting a token with username and password
+            # for authenticators where that's possible
+            data = self.get_json_body()
+            try:
+                user = yield self.login_user(data)
+            except Exception as e:
+                self.log.error("Failure trying to authenticate with form data: %s" % e)
+                user = None
+            if user is None:
+                raise web.HTTPError(403)
         else:
-          raise web.HTTPError(404)
+            data = self.get_json_body()
+            # admin users can request 
+            if data and data.get('username') != user.name:
+                if user.admin:
+                    user = self.find_user(data['username'])
+                    if user is None:
+                        raise web.HTTPError(400, "No such user '%s'" % data['username'])
+                else:
+                    raise web.HTTPError(403, "Only admins can request tokens for other users.")
+        api_token = user.new_api_token()
+        self.write(json.dumps({
+            'token': api_token,
+            'user': self.user_model(user),
+        }))
+
 
 class CookieAPIHandler(APIHandler):
     @token_authenticated
@@ -48,8 +79,24 @@ class CookieAPIHandler(APIHandler):
         self.write(json.dumps(self.user_model(user)))
 
 
+class OAuthHandler(BaseHandler, OAuth2Handler):
+    """Implement OAuth provider handlers
+    
+    OAuth2Handler sets `self.provider` in initialize,
+    but we are already passing the Provider object via settings.
+    """
+    @property
+    def provider(self):
+        return self.settings['oauth_provider']
+
+    def initialize(self):
+        pass
+
+
 default_handlers = [
     (r"/api/authorizations/cookie/([^/]+)(?:/([^/]+))?", CookieAPIHandler),
     (r"/api/authorizations/token/([^/]+)", TokenAPIHandler),
     (r"/api/authorizations/token", TokenAPIHandler),
+    (r"/api/oauth2/authorize", OAuthHandler),
+    (r"/api/oauth2/token", OAuthHandler),
 ]

jupyterhub/apihandlers/base.py

@@ -13,6 +13,14 @@ from ..utils import url_path_join
 
 class APIHandler(BaseHandler):
 
+    @property
+    def content_security_policy(self):
+        return '; '.join([super().content_security_policy, "default-src 'none'"])
+
+    def set_default_headers(self):
+        self.set_header('Content-Type', 'application/json')
+        super().set_default_headers()
+
     def check_referer(self):
         """Check Origin for cross-site API requests.
         
@@ -32,7 +40,7 @@ class APIHandler(BaseHandler):
             self.log.warning("Blocking API request with no referer")
             return False
         
-        host_path = url_path_join(host, self.hub.server.base_url)
+        host_path = url_path_join(host, self.hub.base_url)
         referer_path = referer.split('://', 1)[-1]
         if not (referer_path + '/').startswith(host_path):
             self.log.warning("Blocking Cross Origin API request.  Referer: %s, Host: %s",
@@ -80,7 +88,6 @@ class APIHandler(BaseHandler):
             reason = getattr(exception, 'reason', '')
             if reason:
                 status_message = reason
-        self.set_header('Content-Type', 'application/json')
         self.write(json.dumps({
             'status': status_code,
             'message': message or status_message,
@@ -89,6 +96,7 @@ class APIHandler(BaseHandler):
     def user_model(self, user):
         """Get the JSON model for a User object"""
         model = {
+            'kind': 'user',
             'name': user.name,
             'admin': user.admin,
             'groups': [ g.name for g in user.groups ],
@@ -96,17 +104,33 @@ class APIHandler(BaseHandler):
             'pending': None,
             'last_activity': user.last_activity.isoformat(),
         }
-        if user.spawn_pending:
-            model['pending'] = 'spawn'
-        elif user.stop_pending:
-            model['pending'] = 'stop'
+        model['pending'] = user.spawners[''].pending or None
+
+        if self.allow_named_servers:
+            servers = model['servers'] = {}
+            for name, spawner in user.spawners.items():
+                if spawner.ready:
+                    servers[name] = s = {'name': name}
+                    if spawner.pending:
+                        s['pending'] = spawner.pending
+                    if spawner.server:
+                        s['url'] = url_path_join(user.url, name, '/')
         return model
 
     def group_model(self, group):
         """Get the JSON model for a Group object"""
         return {
+            'kind': 'group',
             'name': group.name,
-            'users': [ u.name for u in group.users ]
+            'users': [ u.name for u in group.users ],
+        }
+
+    def service_model(self, service):
+        """Get the JSON model for a Service object"""
+        return {
+            'kind': 'service',
+            'name': service.name,
+            'admin': service.admin,
         }
 
     _user_model_types = {
@@ -152,6 +176,7 @@ class APIHandler(BaseHandler):
             if not isinstance(groupname, str):
                 raise web.HTTPError(400, ("group names must be str, not %r", type(groupname)))
 
+
     def options(self, *args, **kwargs):
         self.set_header('Access-Control-Allow-Headers', 'accept, content-type')
         self.finish()

jupyterhub/apihandlers/hub.py

@@ -11,7 +11,7 @@ from tornado.ioloop import IOLoop
 
 from ..utils import admin_only
 from .base import APIHandler
-from ..version import __version__
+from .._version import __version__
 
 
 class ShutdownAPIHandler(APIHandler):

jupyterhub/apihandlers/proxy.py

@@ -4,6 +4,7 @@
 # Distributed under the terms of the Modified BSD License.
 
 import json
+from urllib.parse import urlparse
 
 from tornado import gen, web
 
@@ -11,25 +12,29 @@ from .. import orm
 from ..utils import admin_only
 from .base import APIHandler
 
+
 class ProxyAPIHandler(APIHandler):
     
     @admin_only
     @gen.coroutine
     def get(self):
         """GET /api/proxy fetches the routing table
-        
+
         This is the same as fetching the routing table directly from the proxy,
         but without clients needing to maintain separate
         """
-        routes = yield self.proxy.get_routes()
+        routes = yield self.proxy.get_all_routes()
         self.write(json.dumps(routes))
-    
+
     @admin_only
     @gen.coroutine
     def post(self):
-        """POST checks the proxy to ensure"""
+        """POST checks the proxy to ensure that it's up to date.
+
+        Can be used to jumpstart a newly launched proxy
+        without waiting for the check_routes interval.
+        """
         yield self.proxy.check_routes(self.users, self.services)
-        
     
     @admin_only
     @gen.coroutine
@@ -48,17 +53,11 @@ class ProxyAPIHandler(APIHandler):
         if not isinstance(model, dict):
             raise web.HTTPError(400, "Request body must be JSON dict")
         
-        server = self.proxy.api_server
-        if 'ip' in model:
-            server.ip = model['ip']
-        if 'port' in model:
-            server.port = model['port']
-        if 'protocol' in model:
-            server.proto = model['protocol']
+        if 'api_url' in model:
+            self.proxy.api_url = model['api_url']
         if 'auth_token' in model:
             self.proxy.auth_token = model['auth_token']
-        self.db.commit()
-        self.log.info("Updated proxy at %s", server.bind_url)
+        self.log.info("Updated proxy at %s", self.proxy)
         yield self.proxy.check_routes(self.users, self.services)
         
 

jupyterhub/apihandlers/users.py

@@ -12,6 +12,22 @@ from ..utils import admin_only
 from .base import APIHandler
 
 
+class SelfAPIHandler(APIHandler):
+    """Return the authenticated user's model
+    
+    Based on the authentication info. Acts as a 'whoami' for auth tokens.
+    """
+    @web.authenticated
+    def get(self):
+        user = self.get_current_user()
+        if user is None:
+            # whoami can be accessed via oauth token
+            user = self.get_current_user_oauth_token()
+        if user is None:
+            raise web.HTTPError(403)
+        self.write(json.dumps(self.user_model(user)))
+
+
 class UserListAPIHandler(APIHandler):
     @admin_only
     def get(self):
@@ -76,7 +92,7 @@ class UserListAPIHandler(APIHandler):
 
 def admin_or_self(method):
     """Decorator for restricting access to either the target user or admin"""
-    def m(self, name):
+    def m(self, name, *args, **kwargs):
         current = self.get_current_user()
         if current is None:
             raise web.HTTPError(403)
@@ -86,7 +102,7 @@ def admin_or_self(method):
         # raise 404 if not found
         if not self.find_user(name):
             raise web.HTTPError(404)
-        return method(self, name)
+        return method(self, name, *args, **kwargs)
     return m
 
 class UserAPIHandler(APIHandler):
@@ -130,19 +146,19 @@ class UserAPIHandler(APIHandler):
             raise web.HTTPError(404)
         if user.name == self.get_current_user().name:
             raise web.HTTPError(400, "Cannot delete yourself!")
-        if user.stop_pending:
+        if user.spawner._stop_pending:
             raise web.HTTPError(400, "%s's server is in the process of stopping, please wait." % name)
         if user.running:
             yield self.stop_single_user(user)
-            if user.stop_pending:
+            if user.spawner._stop_pending:
                 raise web.HTTPError(400, "%s's server is in the process of stopping, please wait." % name)
         
         yield gen.maybe_future(self.authenticator.delete_user(user))
         # remove from registry
         del self.users[user]
-        
+
         self.set_status(204)
-    
+
     @admin_only
     def patch(self, name):
         user = self.find_user(name)
@@ -150,6 +166,10 @@ class UserAPIHandler(APIHandler):
             raise web.HTTPError(404)
         data = self.get_json_body()
         self._check_user_model(data)
+        if 'name' in data and data['name'] != name:
+            # check if the new name is already taken inside db
+            if self.find_user(data['name']):
+                raise web.HTTPError(400, "User %s already exists, username must be unique" % data['name'])
         for key, value in data.items():
             setattr(user, key, value)
         self.db.commit()
@@ -157,38 +177,72 @@ class UserAPIHandler(APIHandler):
 
 
 class UserServerAPIHandler(APIHandler):
-    @gen.coroutine
-    @admin_or_self
-    def post(self, name):
-        user = self.find_user(name)
-        if user.running:
-            # include notify, so that a server that died is noticed immediately
-            state = yield user.spawner.poll_and_notify()
-            if state is None:
-                raise web.HTTPError(400, "%s's server is already running" % name)
-
-        options = self.get_json_body()
-        yield self.spawn_single_user(user, options=options)
-        status = 202 if user.spawn_pending else 201
-        self.set_status(status)
+    """Start and stop single-user servers"""
 
     @gen.coroutine
     @admin_or_self
-    def delete(self, name):
+    def post(self, name, server_name=''):
         user = self.find_user(name)
-        if user.stop_pending:
+        if server_name and not self.allow_named_servers:
+            raise web.HTTPError(400, "Named servers are not enabled.")
+        spawner = user.spawners[server_name]
+        pending = spawner.pending
+        if pending == 'spawn':
+            self.set_header('Content-Type', 'text/plain')
             self.set_status(202)
             return
-        if not user.running:
-            raise web.HTTPError(400, "%s's server is not running" % name)
-        # include notify, so that a server that died is noticed immediately
-        status = yield user.spawner.poll_and_notify()
-        if status is not None:
-            raise web.HTTPError(400, "%s's server is not running" % name)
-        yield self.stop_single_user(user)
-        status = 202 if user.stop_pending else 204
+        elif pending:
+            raise web.HTTPError(400, "%s is pending %s" % (spawner._log_name, pending))
+
+        if spawner.ready:
+            # include notify, so that a server that died is noticed immediately
+            # set _spawn_pending flag to prevent races while we wait
+            spawner._spawn_pending = True
+            try:
+                state = yield spawner.poll_and_notify()
+            finally:
+                spawner._spawn_pending = False
+            if state is None:
+                raise web.HTTPError(400, "%s is already running" % spawner._log_name)
+
+        options = self.get_json_body()
+        yield self.spawn_single_user(user, server_name, options=options)
+        status = 202 if spawner.pending == 'spawn' else 201
+        self.set_header('Content-Type', 'text/plain')
         self.set_status(status)
 
+    @gen.coroutine
+    @admin_or_self
+    def delete(self, name, server_name=''):
+        user = self.find_user(name)
+        if server_name:
+            if not self.allow_named_servers:
+                raise web.HTTPError(400, "Named servers are not enabled.")
+            if server_name not in user.spawners:
+                raise web.HTTPError(404, "%s has no server named '%s'" % (name, server_name))
+
+        spawner = user.spawners[server_name]
+        if spawner.pending == 'stop':
+            self.log.debug("%s already stopping", spawner._log_name)
+            self.set_header('Content-Type', 'text/plain')
+            self.set_status(202)
+            return
+
+        if not spawner.ready:
+            raise web.HTTPError(
+                400, "%s is not running %s" %
+                (spawner._log_name, '(pending: %s)' % spawner.pending if spawner.pending else '')
+            )
+        # include notify, so that a server that died is noticed immediately
+        status = yield spawner.poll_and_notify()
+        if status is not None:
+            raise web.HTTPError(400, "%s is not running" % spawner._log_name)
+        yield self.stop_single_user(user, server_name)
+        status = 202 if spawner._stop_pending else 204
+        self.set_header('Content-Type', 'text/plain')
+        self.set_status(status)
+
+
 class UserAdminAccessAPIHandler(APIHandler):
     """Grant admins access to single-user servers
     
@@ -196,6 +250,8 @@ class UserAdminAccessAPIHandler(APIHandler):
     """
     @admin_only
     def post(self, name):
+        self.log.warning("Deprecated in JupyterHub 0.8."
+            " Admin access API is not needed now that we use OAuth.")
         current = self.get_current_user()
         self.log.warning("Admin user %s has requested access to %s's server",
             current.name, name,
@@ -205,15 +261,13 @@ class UserAdminAccessAPIHandler(APIHandler):
         user = self.find_user(name)
         if user is None:
             raise web.HTTPError(404)
-        if not user.running:
-            raise web.HTTPError(400, "%s's server is not running" % name)
-        self.set_server_cookie(user)
-        current.other_user_cookies.add(name)
 
 
 default_handlers = [
+    (r"/api/user", SelfAPIHandler),
     (r"/api/users", UserListAPIHandler),
     (r"/api/users/([^/]+)", UserAPIHandler),
     (r"/api/users/([^/]+)/server", UserServerAPIHandler),
+    (r"/api/users/([^/]+)/servers/([^/]*)", UserServerAPIHandler),
     (r"/api/users/([^/]+)/admin-access", UserAdminAccessAPIHandler),
 ]

jupyterhub/auth.py

@@ -3,16 +3,18 @@
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from grp import getgrnam
 import pipes
-import pwd
 import re
 from shutil import which
 import sys
 from subprocess import Popen, PIPE, STDOUT
 
 from tornado import gen
-import pamela
+try:
+    import pamela
+except Exception as e:
+    pamela = None
+    _pamela_error = e
 
 from traitlets.config import LoggingConfigurable
 from traitlets import Bool, Set, Unicode, Dict, Any, default, observe
@@ -22,16 +24,44 @@ from .utils import url_path_join
 from .traitlets import Command
 
 
+
+def getgrnam(name):
+    """Wrapper function to protect against `grp` not being available 
+    on Windows
+    """
+    import grp
+    return grp.getgrnam(name)
+
+
 class Authenticator(LoggingConfigurable):
     """Base class for implementing an authentication provider for JupyterHub"""
 
     db = Any()
+    
+    enable_auth_state = Bool(False, config=True,
+        help="""Enable persisting auth_state (if available).
+
+        auth_state will be encrypted and stored in the Hub's database.
+        This can include things like authentication tokens, etc.
+        to be passed to Spawners as environment variables.
+
+        Encrypting auth_state requires the cryptography package.
+
+        Additionally, the JUPYTERHUB_CRYPTO_KEY envirionment variable must
+        contain one (or more, separated by ;) 32B encryption keys.
+        These can be either base64 or hex-encoded.
+
+        If encryption is unavailable, auth_state cannot be persisted.
+
+        New in JupyterHub 0.8
+        """,
+    )
 
     admin_users = Set(
         help="""
         Set of users that will have admin rights on this JupyterHub.
 
-        Admin users have extra privilages:
+        Admin users have extra privileges:
          - Use the admin panel to see list of users logged in
          - Add / remove users in some authenticators
          - Restart / halt the hub
@@ -114,6 +144,12 @@ class Authenticator(LoggingConfigurable):
 
         Return True if username is valid, False otherwise.
         """
+        if '/' in username:
+            # / is not allowed in usernames
+            return False
+        if not username:
+            # empty usernames are not allowed
+            return False
         if not self.username_regex:
             return True
         return bool(self.username_regex.match(username))
@@ -125,6 +161,23 @@ class Authenticator(LoggingConfigurable):
         """
     ).tag(config=True)
 
+    delete_invalid_users = Bool(False,
+        help="""Delete any users from the database that do not pass validation
+
+        When JupyterHub starts, `.add_user` will be called
+        on each user in the database to verify that all users are still valid.
+
+        If `delete_invalid_users` is True,
+        any users that do not pass validation will be deleted from the database.
+        Use this if users might be deleted from an external system,
+        such as local user accounts.
+
+        If False (default), invalid users remain in the Hub's database
+        and a warning will be issued.
+        This is the default to avoid data loss due to config changes.
+        """
+    )
+
     def normalize_username(self, username):
         """Normalize the given username and return it
 
@@ -149,36 +202,49 @@ class Authenticator(LoggingConfigurable):
             # No whitelist means any name is allowed
             return True
         return username in self.whitelist
-    
+
     @gen.coroutine
     def get_authenticated_user(self, handler, data):
         """Authenticate the user who is attempting to log in
 
-        Returns normalized username if successful, None otherwise.
+        Returns user dict if successful, None otherwise.
 
         This calls `authenticate`, which should be overridden in subclasses,
         normalizes the username if any normalization should be done,
         and then validates the name in the whitelist.
 
         This is the outer API for authenticating a user.
-        Subclasses should not need to override this method.
+        Subclasses should not override this method.
 
         The various stages can be overridden separately:
          - `authenticate` turns formdata into a username
          - `normalize_username` normalizes the username
          - `check_whitelist` checks against the user whitelist
+        
+        .. versionchanged:: 0.8
+            return dict instead of username
         """
-        username = yield self.authenticate(handler, data)
-        if username is None:
+        authenticated = yield self.authenticate(handler, data)
+        if authenticated is None:
             return
-        username = self.normalize_username(username)
+        if isinstance(authenticated, dict):
+            if 'name' not in authenticated:
+                raise ValueError("user missing a name: %r" % authenticated)
+        else:
+            authenticated = {
+                'name': authenticated,
+            }
+        authenticated.setdefault('auth_state', None)
+
+        # normalize the username
+        authenticated['name'] = username = self.normalize_username(authenticated['name'])
         if not self.validate_username(username):
             self.log.warning("Disallowing invalid username %r.", username)
             return
 
         whitelist_pass = yield gen.maybe_future(self.check_whitelist(username))
         if whitelist_pass:
-            return username
+            return authenticated
         else:
             self.log.warning("User %r not in whitelist.", username)
             return
@@ -193,13 +259,20 @@ class Authenticator(LoggingConfigurable):
 
         Checking the whitelist is handled separately by the caller.
 
+        .. versionchanged:: 0.8
+            Allow `authenticate` to return a dict containing auth_state.
+
         Args:
             handler (tornado.web.RequestHandler): the current request handler
             data (dict): The formdata of the login form.
                          The default form has 'username' and 'password' fields.
         Returns:
-            username (str or None): The username of the authenticated user,
-            or None if Authentication failed
+            user (str or dict or None): The username of the authenticated user,
+                or None if Authentication failed.
+                If the Authenticator has state associated with the user,
+                it can return a dict with the keys 'name' and 'auth_state',
+                where 'name' is the username and 'auth_state' is a dictionary
+                of auth state that will be persisted.
         """
 
     def pre_spawn_start(self, user, spawner):
@@ -250,10 +323,23 @@ class Authenticator(LoggingConfigurable):
         """
         self.whitelist.discard(user.name)
 
+    auto_login = Bool(False, config=True,
+        help="""Automatically begin the login process
+
+        rather than starting with a "Login with..." link at `/hub/login`
+
+        To work, `.login_url()` must give a URL other than the default `/hub/login`,
+        such as an oauth handler or another automatic login handler,
+        registered with `.get_handlers()`.
+
+        .. versionadded:: 0.8
+        """
+    )
+
     def login_url(self, base_url):
         """Override this when registering a custom login handler
 
-        Generally used by authenticators that do not use simple form based authentication.
+        Generally used by authenticators that do not use simple form-based authentication.
 
         The subclass overriding this is responsible for making sure there is a handler
         available to handle the URL returned from this method, using the `get_handlers`
@@ -407,6 +493,7 @@ class LocalAuthenticator(Authenticator):
     @staticmethod
     def system_user_exists(user):
         """Check if the user exists on the system"""
+        import pwd
         try:
             pwd.getpwnam(user.name)
         except KeyError:
@@ -456,6 +543,11 @@ class PAMAuthenticator(LocalAuthenticator):
         this is automatically set to False.
         """
     ).tag(config=True)
+    
+    def __init__(self, **kwargs):
+        if pamela is None:
+            raise _pamela_error from None
+        super().__init__(**kwargs)
 
     @gen.coroutine
     def authenticate(self, handler, data):

jupyterhub/crypto.py

@@ -0,0 +1,161 @@
+
+import base64
+from binascii import a2b_hex
+from concurrent.futures import ThreadPoolExecutor
+import json
+import os
+
+from traitlets.config import SingletonConfigurable, Config
+from traitlets import (
+    Any, Dict, Integer, List,
+    default, observe, validate,
+)
+
+try:
+    import cryptography
+    from cryptography.fernet import Fernet, MultiFernet, InvalidToken
+except ImportError:
+    cryptography = None
+    class InvalidToken(Exception):
+        pass
+
+
+KEY_ENV = 'JUPYTERHUB_CRYPT_KEY'
+
+class EncryptionUnavailable(Exception):
+    pass
+
+class CryptographyUnavailable(EncryptionUnavailable):
+    def __str__(self):
+        return "cryptography library is required for encryption"
+
+class NoEncryptionKeys(EncryptionUnavailable):
+    def __str__(self):
+        return "Encryption keys must be specified in %s env" % KEY_ENV
+
+
+def _validate_key(key):
+    """Validate and return a 32B key
+
+    Args:
+    key (bytes): The key to be validated.
+        Can be:
+        - base64-encoded (44 bytes)
+        - hex-encoded (64 bytes)
+        - raw 32 byte key
+
+    Returns:
+    key (bytes): raw 32B key
+    """
+    if isinstance(key, str):
+        key = key.encode('ascii')
+
+    if len(key) == 44:
+        try:
+            key = base64.urlsafe_b64decode(key)
+        except ValueError:
+            pass
+
+    elif len(key) == 64:
+        try:
+            # 64B could be 32B, hex-encoded
+            return a2b_hex(key)
+        except ValueError:
+            # not 32B hex
+            pass
+
+    if len(key) != 32:
+        raise ValueError("Encryption keys must be 32 bytes, hex or base64-encoded.")
+
+    return key
+
+class CryptKeeper(SingletonConfigurable):
+    """Encapsulate encryption configuration
+
+    Use via the encryption_config singleton below.
+    """
+
+    n_threads = Integer(max(os.cpu_count(), 1), config=True,
+        help="The number of threads to allocate for encryption",
+    )
+
+    @default('config')
+    def _config_default(self):
+        # load application config by default
+        from .app import JupyterHub
+        if JupyterHub.initialized():
+            return JupyterHub.instance().config
+        else:
+            return Config()
+
+    executor = Any()
+    def _executor_default(self):
+        return ThreadPoolExecutor(self.n_threads)
+
+    keys = List(config=True)
+    def _keys_default(self):
+        if KEY_ENV not in os.environ:
+            return []
+        # key can be a ;-separated sequence for key rotation.
+        # First item in the list is used for encryption.
+        return [ _validate_key(key) for key in os.environ[KEY_ENV].split(';') if key.strip() ]
+
+    @validate('keys')
+    def _ensure_bytes(self, proposal):
+        # cast str to bytes
+        return [ _validate_key(key) for key in proposal.value ]
+    
+    fernet = Any()
+    def _fernet_default(self):
+        if cryptography is None or not self.keys:
+            return None
+        return MultiFernet([Fernet(base64.urlsafe_b64encode(key)) for key in self.keys])
+
+    @observe('keys')
+    def _update_fernet(self, change):
+        self.fernet = self._fernet_default()
+
+    def check_available(self):
+        if cryptography is None:
+            raise CryptographyUnavailable()
+        if not self.keys:
+            raise NoEncryptionKeys()
+
+    def _encrypt(self, data):
+        """Actually do the encryption. Runs in a background thread.
+        
+        data is serialized to bytes with pickle.
+        bytes are returned.
+        """
+        return self.fernet.encrypt(json.dumps(data).encode('utf8'))
+
+    def encrypt(self, data):
+        """Encrypt an object with cryptography"""
+        self.check_available()
+        return self.executor.submit(self._encrypt, data)
+
+    def _decrypt(self, encrypted):
+        decrypted = self.fernet.decrypt(encrypted)
+        return json.loads(decrypted.decode('utf8'))
+
+    def decrypt(self, encrypted):
+        """Decrypt an object with cryptography"""
+        self.check_available()
+        return self.executor.submit(self._decrypt, encrypted)
+
+
+def encrypt(data):
+    """encrypt some data with the crypt keeper.
+    
+    data will be serialized with pickle.
+    Returns a Future whose result will be bytes.
+    """
+    return CryptKeeper.instance().encrypt(data)
+
+def decrypt(data):
+    """decrypt some data with the crypt keeper
+
+    Returns a Future whose result will be the decrypted, deserialized data.
+    """
+    return CryptKeeper.instance().decrypt(data)
+    

jupyterhub/dbutil.py

@@ -5,11 +5,17 @@
 # Based on pgcontents.utils.migrate, used under the Apache license.
 
 from contextlib import contextmanager
+from datetime import datetime
 import os
+import shutil
 from subprocess import check_call
 import sys
 from tempfile import TemporaryDirectory
 
+from sqlalchemy import create_engine
+
+from . import orm
+
 _here = os.path.abspath(os.path.dirname(__file__))
 
 ALEMBIC_INI_TEMPLATE_PATH = os.path.join(_here, 'alembic.ini')
@@ -18,10 +24,10 @@ ALEMBIC_DIR = os.path.join(_here, 'alembic')
 
 def write_alembic_ini(alembic_ini='alembic.ini', db_url='sqlite:///jupyterhub.sqlite'):
     """Write a complete alembic.ini from our template.
-    
+
     Parameters
     ----------
-    
+
     alembic_ini: str
         path to the alembic.ini file that should be written.
     db_url: str
@@ -29,34 +35,37 @@ def write_alembic_ini(alembic_ini='alembic.ini', db_url='sqlite:///jupyterhub.sq
     """
     with open(ALEMBIC_INI_TEMPLATE_PATH) as f:
         alembic_ini_tpl = f.read()
-    
+
     with open(alembic_ini, 'w') as f:
         f.write(
             alembic_ini_tpl.format(
                 alembic_dir=ALEMBIC_DIR,
-                db_url=db_url,
+                # If there are any %s in the URL, they should be replaced with %%, since ConfigParser
+                # by default uses %() for substitution. You'll get %s in your URL when you have usernames
+                # with special chars (such as '@') that need to be URL encoded. URL Encoding is done with %s.
+                # YAY for nested templates?
+                db_url=str(db_url).replace('%', '%%'),
             )
         )
-    
 
 
 @contextmanager
 def _temp_alembic_ini(db_url):
     """Context manager for temporary JupyterHub alembic directory
-    
+
     Temporarily write an alembic.ini file for use with alembic migration scripts.
-    
+
     Context manager yields alembic.ini path.
-    
+
     Parameters
     ----------
-    
+
     db_url: str
         The SQLAlchemy database url, e.g. `sqlite:///jupyterhub.sqlite`.
-    
+
     Returns
     -------
-    
+
     alembic_ini: str
         The path to the temporary alembic.ini that we have created.
         This file will be cleaned up on exit from the context manager.
@@ -69,7 +78,7 @@ def _temp_alembic_ini(db_url):
 
 def upgrade(db_url, revision='head'):
     """Upgrade the given database to revision.
-    
+
     db_url: str
         The SQLAlchemy database url, e.g. `sqlite:///jupyterhub.sqlite`.
     revision: str [default: head]
@@ -80,6 +89,47 @@ def upgrade(db_url, revision='head'):
             ['alembic', '-c', alembic_ini, 'upgrade', revision]
         )
 
+
+def backup_db_file(db_file, log=None):
+    """Backup a database file if it exists"""
+    timestamp = datetime.now().strftime('.%Y-%m-%d-%H%M%S')
+    backup_db_file = db_file + timestamp
+    for i in range(1, 10):
+        if not os.path.exists(backup_db_file):
+            break
+        backup_db_file = '{}.{}.{}'.format(db_file, timestamp, i)
+    #
+    if os.path.exists(backup_db_file):
+        raise OSError("backup db file already exists: %s" % backup_db_file)
+    if log:
+        log.info("Backing up %s => %s", db_file, backup_db_file)
+    shutil.copy(db_file, backup_db_file)
+
+
+def upgrade_if_needed(db_url, backup=True, log=None):
+    """Upgrade a database if needed
+
+    If the database is sqlite, a backup file will be created with a timestamp.
+    Other database systems should perform their own backups prior to calling this.
+    """
+    # run check-db-revision first
+    engine = create_engine(db_url)
+    try:
+        orm.check_db_revision(engine)
+    except orm.DatabaseSchemaMismatch:
+        # ignore mismatch error because that's what we are here for!
+        pass
+    else:
+        # nothing to do
+        return
+    log.info("Upgrading %s", db_url)
+    # we need to upgrade, backup the database
+    if backup and db_url.startswith('sqlite:///'):
+        db_file = db_url.split(':///', 1)[1]
+        backup_db_file(db_file, log=log)
+    upgrade(db_url)
+
+
 def _alembic(*args):
     """Run an alembic command with a temporary alembic.ini"""
     with _temp_alembic_ini('sqlite:///jupyterhub.sqlite') as alembic_ini:
@@ -89,5 +139,4 @@ def _alembic(*args):
 
 
 if __name__ == '__main__':
-    import sys
     _alembic(*sys.argv[1:])

jupyterhub/emptyclass.py

@@ -5,6 +5,8 @@ instance of itself that'll allow any method to be called on it.
 
 Primarily used to mock out the statsd client when statsd is not being used
 """
+
+
 class EmptyClass:
     def empty_function(self, *args, **kwargs):
         return self