Merge pull request #2080 from minrk/rel-0.9.2

prepare to release 0.9.2

.bowerrc

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

.circleci/config.yml

@@ -0,0 +1,21 @@
+# Python CircleCI 2.0 configuration file
+# Updating CircleCI configuration from v1 to v2
+# Check https://circleci.com/docs/2.0/language-python/ for more details
+#
+version: 2
+jobs:
+  build:
+    machine: true
+    steps:
+      - checkout
+      - run:
+          name: build images
+          command: |
+            docker build -t jupyterhub/jupyterhub .
+            docker build -t jupyterhub/jupyterhub-onbuild onbuild
+            docker build -t jupyterhub/jupyterhub:alpine -f dockerfiles/Dockerfile.alpine .
+            docker build -t jupyterhub/singleuser singleuser
+      - run:
+          name: smoke test jupyterhub
+          command: |
+            docker run --rm -it jupyterhub/jupyterhub jupyterhub --help

.coveragerc

@@ -1,4 +1,17 @@
 [run]
+branch = False
 omit =
     jupyterhub/tests/*
-    jupyterhub/singleuser.py
+    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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+Hi! Thanks for using JupyterHub.
+
+If you are reporting an issue with JupyterHub, please use the [GitHub issue](https://github.com/jupyterhub/jupyterhub/issues) search feature to check if your issue has been asked already. If it has, please add your comments to the existing issue.
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.
+
+- Running `jupyter troubleshoot` from the command line, if possible, and posting
+its output would also be helpful.
+- Running in `--debug` mode can also be helpful for troubleshooting.

.github/ISSUE_TEMPLATE/installation-and-configuration-issues.md

@@ -0,0 +1,7 @@
+---
+name: Installation and configuration issues
+about: Installation and configuration assistance
+
+---
+
+If you are having issues with installation or configuration, you may ask for help on the JupyterHub gitter channel or file an issue here.

.gitignore

@@ -1,21 +1,26 @@
 node_modules
 *.py[co]
 *~
+.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
 # but not sub-dirs
 /jupyterhub_config.py
 jupyterhub_cookie_secret
 jupyterhub.sqlite
-share/jupyter/hub/static/components
-share/jupyter/hub/static/css/style.min.css
-share/jupyter/hub/static/css/style.min.css.map
+package-lock.json
+share/jupyterhub/static/components
+share/jupyterhub/static/css/style.min.css
+share/jupyterhub/static/css/style.min.css.map
 *.egg-info
 MANIFEST
 .coverage
 htmlcov
-
+.idea/
+.pytest_cache

.travis.yml

@@ -1,17 +1,68 @@
-# http://travis-ci.org/#!/jupyter/jupyterhub
 language: python
 sudo: false
+cache:
+  - pip
 python:
-    - 3.5
-    - 3.4
-    - 3.3
+  - 3.6
+  - 3.5
+  - nightly
+env:
+  global:
+    - ASYNC_TEST_TIMEOUT=15
+    - MYSQL_HOST=127.0.0.1
+    - MYSQL_TCP_PORT=13306
+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
+  - |
+    # setup database
+    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-binary
+    fi
 install:
-    - pip install -f travis-wheels/wheelhouse -r dev-requirements.txt .
+  - pip install --upgrade pip
+  - pip install --pre -r dev-requirements.txt .
+  - pip freeze
+
+# running tests
 script:
-    - py.test --cov jupyterhub jupyterhub/tests -v
+  - |
+    # run tests
+    set -e
+    pytest -v --maxfail=2 --cov=jupyterhub jupyterhub/tests
+  - |
+    # build docs
+    pushd docs
+    pip install -r requirements.txt
+    make html
+    popd
 after_success:
-    - codecov
+  - codecov
+
+matrix:
+  fast_finish: true
+  include:
+    - python: 3.6
+      env: JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://localhost.jovyan.org:8000
+    - python: 3.6
+      env:
+        - 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
+    - python: 3.7
+      dist: xenial
+  allow_failures:
+    - python: nightly

CHECKLIST-Release.md

@@ -0,0 +1,26 @@
+# Release checklist
+
+- [ ] Upgrade Docs prior to Release
+
+    - [ ] Change log
+    - [ ] New features documented
+    - [ ] Update the contributor list - thank you page
+
+- [ ] Upgrade and test Reference Deployments
+
+- [ ] Release software
+
+    - [ ] Make sure 0 issues in milestone
+    - [ ] Follow release process steps
+    - [ ] Send builds to PyPI (Warehouse) and Conda Forge
+
+- [ ] Blog post and/or release note
+
+- [ ] Notify users of release
+
+    - [ ] Email Jupyter and Jupyter In Education mailing lists
+    - [ ] Tweet (optional)
+
+- [ ] Increment the version number for the next release
+
+- [ ] Update roadmap

CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+Please refer to [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md).

CONTRIBUTING.md

@@ -1,3 +1,98 @@
 # 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).
+
+
+## Set up your development system
+
+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
+cd jupyterhub
+npm install -g configurable-http-proxy
+pip3 install -r dev-requirements.txt -e .
+```
+
+### Troubleshooting a development install
+
+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:
+
+```bash
+python3 setup.py js    # fetch updated client-side js
+python3 setup.py css   # recompile CSS from LESS sources
+```
+
+## Running the test suite
+
+We use [pytest](http://doc.pytest.org/en/latest/) for running tests. 
+
+1. Set up a development install as described above. 
+
+2. Set environment variable for `ASYNC_TEST_TIMEOUT` to 15 seconds:
+
+```bash
+export ASYNC_TEST_TIMEOUT=15
+```
+
+3. Run tests.
+
+To run all the tests:
+
+```bash
+pytest -v jupyterhub/tests
+```
+
+To run an individual test file (i.e. `test_api.py`):
+
+```bash
+pytest -v jupyterhub/tests/test_api.py
+```
+
+### Troubleshooting tests
+
+If you see test failures because of timeouts, you may wish to increase the
+`ASYNC_TEST_TIMEOUT` used by the
+[pytest-tornado-plugin](https://github.com/eugeniy/pytest-tornado/blob/c79f68de2222eb7cf84edcfe28650ebf309a4d0c/README.rst#markers)
+from the default of 5 seconds:
+
+```bash
+export ASYNC_TEST_TIMEOUT=15
+```
+
+If you see many test errors and failures, double check that you have installed
+`configurable-http-proxy`.
+
+## Building the Docs locally
+
+1. Install the development system as described above.
+
+2. Install the dependencies for documentation:
+
+```bash
+python3 -m pip install -r docs/requirements.txt
+```
+
+3. Build the docs:
+
+```bash
+cd docs
+make clean
+make html
+```
+
+4. View the docs:
+
+```bash
+open build/html/index.html
+```

Dockerfile

@@ -1,50 +1,60 @@
-# A base docker image that includes juptyerhub and IPython master
+# An incomplete base Docker image for running JupyterHub
 #
-# Build your own derivative images starting with
+# Add your configuration to create a complete derivative Docker image.
 #
-# FROM jupyter/jupyterhub:latest
+# Include your configuration settings by starting with one of two options:
 #
+# Option 1:
+#
+# FROM jupyterhub/jupyterhub:latest
+#
+# And put your configuration file jupyterhub_config.py in /srv/jupyterhub/jupyterhub_config.py.
+#
+# Option 2:
+#
+# Or you can create your jupyterhub config and database on the host machine, and mount it with:
+#
+# docker run -v $PWD:/srv/jupyterhub -t jupyterhub/jupyterhub
+#
+# NOTE
+# If you base on jupyterhub/jupyterhub-onbuild
+# your jupyterhub_config.py will be added automatically
+# from your docker directory.
 
-FROM debian:jessie
+FROM ubuntu:18.04
+LABEL maintainer="Jupyter Project <jupyter@googlegroups.com>"
 
-MAINTAINER Jupyter Project <jupyter@googlegroups.com>
-
-# install nodejs, utf8 locale
+# install nodejs, utf8 locale, set CDN because default httpredir is unreliable
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get -y update && \
     apt-get -y upgrade && \
-    apt-get -y install npm nodejs nodejs-legacy wget locales git &&\
-    /usr/sbin/update-locale LANG=C.UTF-8 && \
-    locale-gen C.UTF-8 && \
-    apt-get remove -y locales && \
+    apt-get -y install wget git bzip2 && \
+    apt-get purge && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
 ENV LANG C.UTF-8
 
-# install Python with conda
-RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-3.9.1-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
+# install Python + NodeJS with conda
+RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-4.5.1-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
+    echo '0c28787e3126238df24c5d4858bd0744 */tmp/miniconda.sh' | md5sum -c - && \
     bash /tmp/miniconda.sh -f -b -p /opt/conda && \
-    /opt/conda/bin/conda install --yes python=3.5 sqlalchemy tornado jinja2 traitlets requests pip && \
+    /opt/conda/bin/conda install --yes -c conda-forge \
+      python=3.6 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
 
-# install js dependencies
-RUN npm install -g configurable-http-proxy && rm -rf ~/.npm
+ADD . /src/jupyterhub
+WORKDIR /src/jupyterhub
 
-WORKDIR /srv/
-ADD . /srv/jupyterhub
+RUN pip install . && \
+    rm -rf $PWD ~/.cache ~/.npm
+
+RUN mkdir -p /srv/jupyterhub/
 WORKDIR /srv/jupyterhub/
-
-RUN python setup.py js && pip install . && \
-    rm -rf node_modules ~/.cache ~/.npm
-
-WORKDIR /srv/jupyterhub/
-
-# Derivative containers should add jupyterhub config,
-# which will be used when starting the application.
-
 EXPOSE 8000
 
-ONBUILD ADD jupyterhub_config.py /srv/jupyterhub/jupyterhub_config.py
-CMD ["jupyterhub", "-f", "/srv/jupyterhub/jupyterhub_config.py"]
+LABEL org.jupyter.service="jupyterhub"
+
+CMD ["jupyterhub"]

MANIFEST.in

@@ -1,26 +1,33 @@
 include README.md
 include COPYING.md
 include setupegg.py
-include bower.json
+include bower-lite
 include package.json
+include package-lock.json
 include *requirements.txt
+include Dockerfile
 
+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
-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/moment/lang
-prune share/jupyter/hub/static/components/moment/min
+prune share/jupyterhub/static/components/bootstrap/dist/css
+exclude share/jupyterhub/static/components/bootstrap/dist/fonts/*.svg
+prune share/jupyterhub/static/components/font-awesome/css
+prune share/jupyterhub/static/components/font-awesome/scss
+exclude share/jupyterhub/static/components/font-awesome/fonts/*.svg
+prune share/jupyterhub/static/components/jquery/external
+prune share/jupyterhub/static/components/jquery/src
+prune share/jupyterhub/static/components/moment/lang
+prune share/jupyterhub/static/components/moment/min
 
 # Patterns to exclude from any directory
 global-exclude *~

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1 @@
+

README.md

@@ -1,134 +1,249 @@
-# JupyterHub: A multi-user server for Jupyter notebooks
-
-Questions, comments? Visit our Google Group:
-
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
-[![Build Status](https://travis-ci.org/jupyter/jupyterhub.svg?branch=master)](https://travis-ci.org/jupyter/jupyterhub)
-[![Circle CI](https://circleci.com/gh/jupyter/jupyterhub.svg?style=shield&circle-token=b5b65862eb2617b9a8d39e79340b0a6b816da8cc)](https://circleci.com/gh/jupyter/jupyterhub)
-[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
-
-JupyterHub, a multi-user server, manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
-
-Three actors:
-
-- multi-user Hub (tornado process)
-- configurable http proxy (node-http-proxy)
-- multiple single-user IPython notebook servers (Python/IPython/tornado)
-
-Basic principles:
-
-- 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
+**[Technical Overview](#technical-overview)** |
+**[Installation](#installation)** |
+**[Configuration](#configuration)** |
+**[Docker](#docker)** |
+**[Contributing](#contributing)** |
+**[License](#license)** |
+**[Help and Resources](#help-and-resources)**
 
 
-## Dependencies
+# [JupyterHub](https://github.com/jupyterhub/jupyterhub)
 
-JupyterHub requires [IPython](https://ipython.org/install.html) >= 3.0 (current master) and [Python](https://www.python.org/downloads/) >= 3.3.
 
-Install [nodejs/npm](https://www.npmjs.com/), which is available from your
-package manager. For example, install on Linux (Debian/Ubuntu) using:
+[![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)](https://jupyterhub.readthedocs.org/en/latest/?badge=latest)
+[![Documentation Status](http://readthedocs.org/projects/jupyterhub/badge/?version=0.7.2)](https://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)
+[![Google Group](https://img.shields.io/badge/google-group-blue.svg)](https://groups.google.com/forum/#!forum/jupyter)
 
-    sudo apt-get install npm nodejs-legacy
+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](https://jupyter-notebook.readthedocs.io)
+server.
 
-(The `nodejs-legacy` package installs the `node` executable and is currently
-required for npm to work on Debian/Ubuntu.)
+[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.
 
-Next, install JavaScript dependencies:
+## Technical overview
 
-    sudo npm install -g configurable-http-proxy
+Three main actors make up JupyterHub:
 
-### (Optional) Installation Prerequisite (pip)
+- multi-user **Hub** (tornado process)
+- configurable http **proxy** (node-http-proxy)
+- multiple **single-user Jupyter notebook servers** (Python/Jupyter/tornado)
 
-Notes on the `pip` command used in the installation directions below:
-- `sudo` may be needed for `pip install`, depending on the user's filesystem permissions.
-- JupyterHub requires Python >= 3.3, so `pip3` may be required on some machines for package installation instead of `pip` (especially when both Python 2 and Python 3 are installed on a machine). If `pip3` is not found, install it using (on Linux Debian/Ubuntu):
+Basic principles for operation are:
 
-        sudo apt-get install python3-pip
+- Hub launches 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 its users.
 
 ## Installation
 
-JupyterHub can be installed with pip:
 
-    pip3 install jupyterhub
+### Check prerequisites
 
-If you plan to run notebook servers locally, you may also need to install the
-Jupyter ~~IPython~~ notebook:
+- A Linux/Unix based system
+- [Python](https://www.python.org/downloads/) 3.5 or greater
+- [nodejs/npm](https://www.npmjs.com/)
 
-    pip3 install notebook
+  * If you are using **`conda`**, the nodejs and npm dependencies will be installed for
+    you by conda.
 
+  * If you are using **`pip`**, install a recent version of
+    [nodejs/npm](https://docs.npmjs.com/getting-started/installing-node).
+    For example, install it on Linux (Debian/Ubuntu) using:
 
-### Development install
+    ```
+    sudo apt-get install npm nodejs-legacy
+    ```
 
-For a development install, clone the repository and then install from source:
+    The `nodejs-legacy` package installs the `node` executable and is currently
+    required for npm to work on Debian/Ubuntu.
 
-    git clone https://github.com/jupyter/jupyterhub
-    cd jupyterhub
-    pip3 install -r dev-requirements.txt -e .
+- TLS certificate and key for HTTPS communication
+- Domain name
 
-If the `pip3 install` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional JavaScript dependencies:
+### Install packages
 
-    npm install
+#### Using `conda`
 
-This will fetch client-side JavaScript dependencies necessary to compile CSS.
+To install JupyterHub along with its dependencies including nodejs/npm:
 
-You may also need to manually update JavaScript and CSS after some development updates, with:
+```bash
+conda install -c conda-forge jupyterhub
+```
 
-    python3 setup.py js    # fetch updated client-side js (changes rarely)
-    python3 setup.py css   # recompile CSS from LESS sources
+If you plan to run notebook servers locally, install the Jupyter notebook
+or JupyterLab:
 
+```bash
+conda install notebook
+conda install jupyterlab
+```
 
-## Running the server
+#### Using `pip`
 
-To start the server, run the command:
+JupyterHub can be installed with `pip`, and the proxy with `npm`:
+
+```bash
+npm install -g configurable-http-proxy
+python3 -m pip install jupyterhub    
+```
+
+If you plan to run notebook servers locally, you will need to install the
+[Jupyter notebook](https://jupyter.readthedocs.io/en/latest/install.html)
+package:
+
+    python3 -m pip install --upgrade notebook
+
+### Run the Hub server
+
+To start the Hub server, run the command:
 
     jupyterhub
 
-and then visit `http://localhost:8000`, 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/jupyter/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.
+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.
 
-## Getting started
+## Configuration
 
-See the [getting started document](docs/source/getting-started.md) for the
-basics of configuring your JupyterHub deployment.
+The [Getting Started](https://jupyterhub.readthedocs.io/en/latest/getting-started/index.html) section of the
+documentation explains the common steps in setting up JupyterHub.
 
-### Some examples
+The [**JupyterHub tutorial**](https://github.com/jupyterhub/jupyterhub-tutorial)
+provides an in-depth video and sample configurations of JupyterHub.
 
-Generate a default config file:
+### Create a configuration file
+
+To generate a default config file with settings and descriptions:
 
     jupyterhub --generate-config
 
-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/jupyter/oauthenticator)
-- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyter/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      |
 
-# Getting help
+### Spawners
 
-We encourage you to ask questions on the mailing list:
+| 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 |
 
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+## Docker
 
-and you may participate in development discussions or get live help on Gitter:
+A starter [**docker image for JupyterHub**](https://hub.docker.com/r/jupyterhub/jupyterhub/)
+gives a baseline deployment of JupyterHub using Docker.
 
-[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter/jupyterhub?utm_source=badge&utm_medium=badge)
+**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.
 
-## Resources
+The JupyterHub docker image can be started with the following command:
+
+    docker run -p 8000:8000 -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 by using a ssl enabled proxy.
+
+[Mounting volumes](https://docs.docker.com/engine/admin/volumes/volumes/) 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.
+
+## 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). The `CONTRIBUTING.md` file
+explains how to set up a development installation, how to run the test suite,
+and how to contribute to documentation.
+
+### 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.
+
+## 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.
+
+- [Reporting Issues](https://github.com/jupyterhub/jupyterhub/issues)
+- [JupyterHub tutorial](https://github.com/jupyterhub/jupyterhub-tutorial)
+- [Documentation for JupyterHub](https://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)
-- [Documentation for JupyterHub](http://jupyterhub.readthedocs.org/en/latest/) [[PDF](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf)]
-- [Documentation for Project Jupyter](http://jupyter.readthedocs.org/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
-- [Issues](https://github.com/jupyter/jupyterhub/issues)
-- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter)
+
+---
+
+**[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", "jupyterhub", "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 -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
+
+for SUFFIX in '' _upgrade_072 _upgrade_081; do
+    $SQL "DROP DATABASE jupyterhub${SUFFIX};" 2>/dev/null || true
+    $SQL "CREATE DATABASE jupyterhub${SUFFIX} ${EXTRA_CREATE};"
+done

circle.yml

@@ -1,11 +0,0 @@
-machine:
-  services:
-    - docker
-
-dependencies:
-  override:
-    - ls
-
-test:
-  override:
-    - docker build -t jupyter/jupyterhub .

dev-requirements.txt

@@ -1,5 +1,13 @@
 -r requirements.txt
+mock
 codecov
+cryptography
 pytest-cov
-pytest>=2.8
+pytest-tornado
+pytest>=3.3
 notebook
+requests-mock
+virtualenv
+# temporary pin of attrs for jsonschema 0.3.0a1
+# seems to be a pip bug
+attrs>=17.4.0

dockerfiles/Dockerfile.alpine

@@ -0,0 +1,11 @@
+FROM python:3.6.3-alpine3.6
+
+ARG JUPYTERHUB_VERSION=0.8.1
+
+RUN pip3 install --no-cache jupyterhub==${JUPYTERHUB_VERSION}
+ENV LANG=en_US.UTF-8
+
+USER nobody
+CMD ["jupyterhub"]
+
+

dockerfiles/README.md

@@ -0,0 +1,21 @@
+## What is Dockerfile.alpine
+Dockerfile.alpine  contains base image for jupyterhub. It does not work independently, but only as part of a full jupyterhub cluster
+
+## How to use it?
+
+1. A running configurable-http-proxy, whose API is accessible. 
+2. A jupyterhub_config file.
+3. Authentication and other libraries required by the specific jupyterhub_config file.
+
+
+## Steps to test it outside a cluster
+
+* start configurable-http-proxy in another container
+* specify CONFIGPROXY_AUTH_TOKEN env in both containers
+* put both containers on the same network (e.g. docker create network jupyterhub; docker run ... --net jupyterhub)
+* tell jupyterhub where CHP is (e.g. c.ConfigurableHTTPProxy.api_url = 'http://chp:8001')
+* tell jupyterhub not to start the proxy itself (c.ConfigurableHTTPProxy.should_start = False)
+* Use dummy authenticator for ease of testing. Update following in jupyterhub_config file
+    - c.JupyterHub.authenticator_class = 'dummyauthenticator.DummyAuthenticator'
+    - c.DummyAuthenticator.password = "your strong password"
+

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = "-W"
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
@@ -47,11 +47,20 @@ help:
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  spelling   to run spell check on documentation"
 
 clean:
 	rm -rf $(BUILDDIR)/*
 
-html:
+node_modules: package.json
+	npm install && touch node_modules
+
+rest-api: source/_static/rest-api/index.html
+
+source/_static/rest-api/index.html: rest-api.yml node_modules
+	npm run rest-api
+
+html: rest-api
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
@@ -171,6 +180,11 @@ linkcheck:
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
+spelling:
+	$(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
+	@echo
+	@echo "Spell check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/spelling/output.txt."
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \

docs/environment.yml

@@ -0,0 +1,22 @@
+# ReadTheDocs uses the `environment.yaml` so make sure to update that as well
+# if you change the dependencies of JupyterHub in the various `requirements.txt`
+name: jhub_docs
+channels:
+  - conda-forge
+dependencies:
+- nodejs
+- python=3.6
+- alembic
+- jinja2
+- pamela
+- requests
+- sqlalchemy>=1
+- tornado>=5.0
+- traitlets>=4.1
+- sphinx>=1.7
+- pip:
+  - python-oauth2
+  - recommonmark==0.4.0
+  - async_generator
+  - prometheus_client
+  - attrs>=17.4.0

docs/package.json

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

docs/requirements.txt

@@ -1,3 +1,5 @@
+# ReadTheDocs uses the `environment.yaml` so make sure to update that as well
+# if you change this file
 -r ../requirements.txt
-sphinx
-recommonmark==0.4.0
+sphinx>=1.7
+recommonmark==0.4.0

docs/rest-api.yml

@@ -3,9 +3,11 @@ swagger: '2.0'
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 0.4.0
+  version: 0.9.0dev
+  license:
+    name: BSD-3-Clause
 schemes:
-  - http
+  - [http, https]
 securityDefinitions:
   token:
     type: apiKey
@@ -13,18 +15,73 @@ securityDefinitions:
     in: header
 security:
   - token: []
-basePath: /hub/api/
+basePath: /hub/api
 produces:
   - application/json
 consumes:
   - application/json
 paths:
+  /:
+    get:
+      summary: Get JupyterHub version
+      description: |
+        This endpoint is not authenticated for the purpose of clients and user
+        to identify the JupyterHub version before setting up authentication.
+      responses:
+        '200':
+          description: The JupyterHub version
+          schema:
+            type: object
+            properties:
+              version:
+                type: string
+                description: The version of JupyterHub itself
+  /info:
+    get:
+      summary: Get detailed info about JupyterHub
+      description: |
+        Detailed JupyterHub information, including Python version,
+        JupyterHub's version and executable path,
+        and which Authenticator and Spawner are active.
+      responses:
+        '200':
+          description: Detailed JupyterHub info
+          schema:
+            type: object
+            properties:
+              version:
+                type: string
+                description: The version of JupyterHub itself
+              python:
+                type: string
+                description: The Python version, as returned by sys.version
+              sys_executable:
+                type: string
+                description: The path to sys.executable running JupyterHub
+              authenticator:
+                type: object
+                properties:
+                  class:
+                    type: string
+                    description: The Python class currently active for JupyterHub Authentication
+                  version:
+                    type: string
+                    description: The version of the currently active Authenticator
+              spawner:
+                type: object
+                properties:
+                  class:
+                    type: string
+                    description: The Python class currently active for spawning single-user notebook servers
+                  version:
+                    type: string
+                    description: The version of the currently active Spawner
   /users:
     get:
       summary: List users
       responses:
         '200':
-          description: The user list
+          description: The Hub's user list
           schema:
             type: array
             items:
@@ -40,7 +97,7 @@ paths:
             properties:
               usernames:
                 type: array
-                description: list of usernames to create
+                description: list of usernames to create on the Hub
                 items:
                   type: string
               admin:
@@ -81,17 +138,6 @@ paths:
           description: The user has been created
           schema:
             $ref: '#/definitions/User'
-    delete:
-      summary: Delete a user
-      parameters:
-        - name: name
-          description: username
-          in: path
-          required: true
-          type: string
-      responses:
-        '204':
-          description: The user has been deleted
     patch:
       summary: Modify a user
       description: Change a user's name or admin status
@@ -104,24 +150,35 @@ paths:
         - name: data
           in: body
           required: true
-          description: Updated user info. At least one of name and admin is required.
+          description: Updated user info. At least one key to be updated (name or admin) is required.
           schema:
             type: object
             properties:
               name:
                 type: string
-                description: the new name (optional)
+                description: the new name (optional, if another key is updated i.e. admin)
               admin:
                 type: boolean
-                description: update admin (optional)
+                description: update admin (optional, if another key is updated i.e. name)
       responses:
         '200':
           description: The updated user info
           schema:
             $ref: '#/definitions/User'
+    delete:
+      summary: Delete a user
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The user has been deleted
   /users/{name}/server:
     post:
-      summary: Start a user's server
+      summary: Start a user's single-user notebook server
       parameters:
         - name: name
           description: username
@@ -130,9 +187,9 @@ paths:
           type: string
       responses:
         '201':
-          description: The server has started
+          description: The user's notebook server has started
         '202':
-          description: The server has been requested, but has not yet started
+          description: The user's notebook server has not yet started, but has been requested
     delete:
       summary: Stop a user's server
       parameters:
@@ -143,39 +200,233 @@ paths:
           type: string
       responses:
         '204':
-          description: The server has stopped
+          description: The user's notebook server has stopped
         '202':
-          description: The server has been asked to stop, but is taking a while
-  /users/{name}/admin-access:
+          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: Grant an admin access to this user's server
+      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}/tokens:
+    get:
+      summary: List tokens for the user
       responses:
         '200':
-          description: Sets a cookie granting the requesting admin access to the user's server
+          description: The list of tokens
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Token'
+    post:
+      summary: Create a new token for the user
+      parameters:
+        - name: expires_in
+          type: number
+          required: false
+          in: body
+          description: lifetime (in seconds) after which the requested token will expire.
+        - name: note
+          type: string
+          required: false
+          in: body
+          description: A note attached to the token for future bookkeeping
+      responses:
+        '201':
+          description: The newly created token
+          schema:
+            $ref: '#/definitions/Token'
+  /users/{name}/tokens/{token_id}:
+    get:
+      summary: Get the model for a token by id
+      responses:
+        '200':
+          description: The info for the new token
+          schema:
+            $ref: '#/definitions/Token'
+    delete:
+      summary: Delete (revoke) a token by id
+      responses:
+        '204':
+          description: The token has been deleted
+  /user:
+    summary: Return authenticated user's model
+    description:
+    parameters:
+    responses:
+      '200':
+        description: The authenticated user's model is returned.
+  /groups:
+    get:
+      summary: List groups
+      responses:
+        '200':
+          description: The list of groups
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Group'
+  /groups/{name}:
+    get:
+      summary: Get a group by name
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: The group model
+          schema:
+            $ref: '#/definitions/Group'
+    post:
+      summary: Create a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '201':
+          description: The group has been created
+          schema:
+            $ref: '#/definitions/Group'
+    delete:
+      summary: Delete a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The group has been deleted
+  /groups/{name}/users:
+    post:
+      summary: Add users to a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+        - name: data
+          in: body
+          required: true
+          description: The users to add to the group
+          schema:
+            type: object
+            properties:
+              users:
+                type: array
+                description: List of usernames to add to the group
+                items:
+                  type: string
+      responses:
+        '200':
+          description: The users have been added to the group
+          schema:
+            $ref: '#/definitions/Group'
+    delete:
+      summary: Remove users from a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+        - name: data
+          in: body
+          required: true
+          description: The users to remove from the group
+          schema:
+            type: object
+            properties:
+              users:
+                type: array
+                description: List of usernames to remove from the group
+                items:
+                  type: string
+      responses:
+        '200':
+          description: The users have been removed from the group
+  /services:
+    get:
+      summary: List services
+      responses:
+        '200':
+          description: The service list
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Service'
+  /services/{name}:
+    get:
+      summary: Get a service by name
+      parameters:
+        - name: name
+          description: service name
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: The Service model
+          schema:
+            $ref: '#/definitions/Service'
   /proxy:
     get:
       summary: Get the proxy's routing table
-      description: A convenience alias for getting the info directly from the proxy
+      description: A convenience alias for getting the routing table directly from the proxy
       responses:
         '200':
           description: Routing table
           schema:
             type: object
-            description: configurable-http-proxy routing table (see CHP docs for details)
+            description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
     post:
       summary: Force the Hub to sync with the proxy
       responses:
         '200':
           description: Success
     patch:
-      summary: Tell the Hub about a new proxy
-      description: If you have started a new proxy and would like the Hub to switch over to it, this allows you to notify the Hub of the new proxy.
+      summary: Notify the Hub about a new proxy
+      description: Notifies the Hub of a new proxy to use.
       parameters:
         - name: data
           in: body
@@ -199,9 +450,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
@@ -209,13 +489,13 @@ 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
-      description: Used by single-user servers to hand off cookie authentication to the Hub
+      description: Used by single-user notebook servers to hand off cookie authentication to the Hub
       parameters:
       - name: cookie_name
         in: path
@@ -229,13 +509,94 @@ paths:
         '200':
           description: The user identified by the cookie
           schema:
-            $ref: '#!/definitions/User'
+            $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
-      responses:
-        '200':
-          description: Hub has shutdown
+      parameters:
+        - name: proxy
+          in: body
+          type: boolean
+          description: Whether the proxy should be shutdown as well (default from Hub config)
+        - name: servers
+          in: body
+          type: boolean
+          description: Whether users' notebook servers should be shutdown as well (default from Hub config)
 definitions:
   User:
     type: object
@@ -246,14 +607,133 @@ definitions:
       admin:
         type: boolean
         description: Whether the user is an admin
+      groups:
+        type: array
+        description: The names of groups where this user is a member
+        items:
+          type: string
       server:
         type: string
-        description: The user's server's base URL, if running; null if not.
+        description: The user's notebook server's base URL, if running; null if not.
       pending:
         type: string
-        enum: ["spawn", "stop"]
+        enum: ["spawn", "stop", null]
         description: The currently pending action, if any
       last_activity:
         type: string
-        format: ISO8601 Timestamp
+        format: date-time
         description: Timestamp of last-seen activity from the user
+      servers:
+        type: object
+        description: The active servers for this user.
+        items:
+          schema:
+            $ref: '#/definitions/Server'
+  Server:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The server's name. The user's default server has an empty name ('')
+      ready:
+        type: boolean
+        description: |
+          Whether the server is ready for traffic.
+          Will always be false when any transition is pending.
+      pending:
+        type: string
+        enum: ["spawn", "stop", null]
+        description: |
+          The currently pending action, if any.
+          A server is not ready if an action is pending.
+      url:
+        type: string
+        description: |
+          The URL where the server can be accessed
+          (typically /user/:name/:server.name/).
+      progress_url:
+        type: string
+        description: |
+          The URL for an event-stream to retrieve events during a spawn.
+      started:
+        type: string
+        format: date-time
+        description: UTC timestamp when the server was last started.
+      last_activity:
+        type: string
+        format: date-time
+        description: UTC timestamp last-seen activity on this server.
+      state:
+        type: object
+        description: Arbitrary internal state from this server's spawner.  Only available on the hub's users list or get-user-by-name method, and only if a hub admin.  None otherwise.
+  Group:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The group's name
+      users:
+        type: array
+        description: The names of users who are members of this group
+        items:
+          type: string
+  Service:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The service's name
+      admin:
+        type: boolean
+        description: Whether the service is an admin
+      url:
+        type: string
+        description: The internal url where the service is running
+      prefix:
+        type: string
+        description: The proxied URL prefix to the service's url
+      pid:
+        type: number
+        description: The PID of the service process (if managed)
+      command:
+        type: array
+        description: The command used to start the service (if managed)
+        items:
+          type: string
+      info:
+        type: object
+        description: |
+          Additional information a deployment can attach to a service.
+          JupyterHub does not use this field.
+  Token:
+    type: object
+    properties:
+      token:
+        type: string
+        description: The token itself. Only present in responses to requests for a new token.
+      id:
+        type: string
+        description: The id of the API token. Used for modifying or deleting the token.
+      user:
+        type: string
+        description: The user that owns a token (undefined if owned by a service)
+      service:
+        type: string
+        description: The service that owns the token (undefined of owned by a user)
+      note:
+        type: string
+        description: A note about the token, typically describing what it was created for.
+      created:
+        type: string
+        format: date-time
+        description: Timestamp when this token was created
+      expires_at:
+        type: string
+        format: date-time
+        description: Timestamp when this token expires. Null if there is no expiry.
+      last_activity:
+        type: string
+        format: date-time
+        description: |
+          Timestamp of last-seen activity using this token.
+          Can be null if token has never been used.

docs/source/_static/custom.css

@@ -0,0 +1,106 @@
+div#helm-chart-schema h2,
+div#helm-chart-schema h3,
+div#helm-chart-schema h4,
+div#helm-chart-schema h5,
+div#helm-chart-schema h6 {
+    font-family: courier new;
+}
+
+h3, h3 ~ * {
+  margin-left: 3% !important;
+}
+
+h4, h4 ~ * {
+  margin-left: 6% !important;
+}
+
+h5, h5 ~ * {
+  margin-left: 9% !important;
+}
+
+h6, h6 ~ * {
+  margin-left: 12% !important;
+}
+
+h7, h7 ~ * {
+  margin-left: 15% !important;
+}
+
+img.logo {
+  width:100%
+}
+
+.right-next {
+    float: right;
+    max-width: 45%;
+    overflow: auto;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.right-next::after{
+    content: ' »';
+}
+
+.left-prev {
+    float: left;
+    max-width: 45%;
+    overflow: auto;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+.left-prev::before{
+    content: '« ';
+}
+
+.prev-next-bottom {
+  margin-top: 3em;
+}
+
+.prev-next-top {
+  margin-bottom: 1em;
+}
+
+/* Sidebar TOC and headers */
+
+div.sphinxsidebarwrapper div {
+    margin-bottom: .8em;
+}
+div.sphinxsidebar h3 {
+    font-size: 1.3em;
+    padding-top: 0px;
+    font-weight: 800;
+    margin-left: 0px !important;
+}
+
+div.sphinxsidebar p.caption {
+    font-size: 1.2em;
+    margin-bottom: 0px;
+    margin-left: 0px !important;
+    font-weight: 900;
+    color: #767676;
+}
+
+div.sphinxsidebar ul {
+    font-size: .8em;
+    margin-top: 0px;
+    padding-left: 3%;
+    margin-left: 0px !important;
+}
+
+div.relations ul {
+    font-size: 1em;
+    margin-left: 0px !important;
+}
+
+div#searchbox form {
+    margin-left: 0px !important;
+}
+
+/* body elements */
+.toctree-wrapper span.caption-text {
+    color: #767676;
+    font-style: italic;
+    font-weight: 300;
+}

docs/source/_templates/navigation.html

@@ -0,0 +1,16 @@
+{# Custom template for navigation.html
+
+   alabaster theme does not provide blocks for titles to
+   be overridden so this custom theme handles title and
+   toctree for sidebar
+#}
+<h3>{{ _('Table of Contents') }}</h3>
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}

docs/source/_templates/page.html

@@ -0,0 +1,30 @@
+{% extends '!page.html' %}
+
+{# Custom template for page.html
+
+   Alabaster theme does not provide blocks for prev/next at bottom of each page.
+   This is _in addition_ to the prev/next in the  sidebar. The "Prev/Next" text
+   or symbols are handled by CSS classes in _static/custom.css
+#}
+
+{% macro prev_next(prev, next, prev_title='', next_title='') %}
+  {%- if prev %}
+     <a class='left-prev' href="{{ prev.link|e }}" title="{{ _('previous chapter')}}">{{ prev_title or prev.title }}</a>
+  {%- endif %}
+  {%- if next %}
+     <a class='right-next' href="{{ next.link|e }}" title="{{ _('next chapter')}}">{{ next_title or next.title }}</a>
+  {%- endif %}
+  <div style='clear:both;'></div>
+{% endmacro %}
+
+
+{% block body %}
+  <div class='prev-next-top'>
+    {{ prev_next(prev, next, 'Previous', 'Next') }}
+  </div>
+
+  {{super()}}
+  <div class='prev-next-bottom'>
+    {{ prev_next(prev, next) }}
+  </div>
+{% endblock %}

docs/source/_templates/relations.html

@@ -0,0 +1,17 @@
+{# Custom template for relations.html
+
+   alabaster theme does not provide previous/next page by default
+#}
+<div class="relations">
+<h3>Navigation</h3>
+<ul>
+  <li><a href="{{ pathto(master_doc) }}">Documentation Home</a><ul>
+  {%- if prev %}
+  <li><a href="{{ prev.link|e }}" title="Previous">Previous topic</a></li>
+  {%- endif %}
+  {%- if next %}
+  <li><a href="{{ next.link|e }}" title="Next">Next topic</a></li>
+  {%- endif %}
+  </ul>
+</ul>
+</div>

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,14 +1,38 @@
 .. _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 <../reference/rest.html>`_ provides
+information on:
+
+- 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>`__.
+The `OpenAPI Initiative`_ (fka Swagger™) is a project used to describe
+and document RESTful APIs.
+
+JupyterHub API Reference:
+
 .. toctree::
 
+    app
     auth
     spawner
+    proxy
     user
+    service
+    services.auth
+
+
+.. _OpenAPI Initiative: https://www.openapis.org/

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

@@ -0,0 +1,41 @@
+=======================
+Services Authentication
+=======================
+
+Module: :mod:`jupyterhub.services.auth`
+=======================================
+
+.. automodule:: jupyterhub.services.auth
+
+.. currentmodule:: jupyterhub.services.auth
+
+
+: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
-    :members: options_from_form, poll, start, stop, get_args, get_env, get_state
+.. autoconfigurable:: Spawner
+    :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string
+
+:class:`LocalProcessSpawner`
+----------------------------
+
+.. autoconfigurable:: LocalProcessSpawner
 
-.. autoclass:: 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,110 +0,0 @@
-# Writing a custom Authenticator
-
-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/jupyter/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':
-
-    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][].
-
-
-[Authenticator]: https://github.com/jupyter/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/jupyter/oauthenticator
-

docs/source/changelog.md

@@ -1,14 +1,378 @@
-# Summary of changes in JupyterHub
+# Changelog
 
-See `git log` for a more detailed summary.
+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.9
+
+### [0.9.2] 2018-08-10
+
+JupyterHub 0.9.2 contains small bugfixes and improvements.
+
+- Documentation and example improvements
+- Add `Spawner.consecutive_failure_limit` config for aborting the Hub if too many spawns fail in a row.
+- Fix for handling SIGTERM when run with asyncio (tornado 5)
+- Windows compatibility fixes
+
+
+### [0.9.1] 2018-07-04
+
+JupyterHub 0.9.1 contains a number of small bugfixes on top of 0.9.
+
+- Use a PID file for the proxy to decrease the likelihood that a leftover proxy process will prevent JupyterHub from restarting
+- `c.LocalProcessSpawner.shell_cmd` is now configurable
+- API requests to stopped servers (requests to the hub for `/user/:name/api/...`) fail with 404 rather than triggering a restart of the server
+- Compatibility fix for notebook 5.6.0 which will introduce further
+  security checks for local connections
+- Managed services always use localhost to talk to the Hub if the Hub listening on all interfaces
+- When using a URL prefix, the Hub route will be `JupyterHub.base_url` instead of unconditionally `/`
+- additional fixes and improvements
+
+### [0.9.0] 2018-06-15
+
+JupyterHub 0.9 is a major upgrade of JupyterHub.
+There are several changes to the database schema,
+so make sure to backup your database and run:
+
+    jupyterhub upgrade-db
+
+after upgrading jupyterhub.
+
+The biggest change for 0.9 is the switch to asyncio coroutines everywhere
+instead of tornado coroutines. Custom Spawners and Authenticators are still
+free to use tornado coroutines for async methods, as they will continue to
+work. As part of this upgrade, JupyterHub 0.9 drops support for Python < 3.5
+and tornado < 5.0.
+
+
+#### Changed
+
+- Require Python >= 3.5
+- Require tornado >= 5.0
+- Use asyncio coroutines throughout
+- Set status 409 for conflicting actions instead of 400,
+  e.g. creating users or groups that already exist.
+- timestamps in REST API continue to be UTC, but now include 'Z' suffix
+  to identify them as such.
+- REST API User model always includes `servers` dict,
+  not just when named servers are enabled.
+- `server` info is no longer available to oauth identification endpoints,
+  only user info and group membership.
+- `User.last_activity` may be None if a user has not been seen,
+  rather than starting with the user creation time
+  which is now separately stored as `User.created`.
+- static resources are now found in `$PREFIX/share/jupyterhub` instead of `share/jupyter/hub` for improved consistency.
+- Deprecate `.extra_log_file` config. Use pipe redirection instead:
+
+      jupyterhub &>> /var/log/jupyterhub.log
+
+- Add `JupyterHub.bind_url` config for setting the full bind URL of the proxy.
+  Sets ip, port, base_url all at once.
+- Add `JupyterHub.hub_bind_url` for setting the full host+port of the Hub.
+  `hub_bind_url` supports unix domain sockets, e.g.
+  `unix+http://%2Fsrv%2Fjupyterhub.sock`
+- Deprecate `JupyterHub.hub_connect_port` config in favor of `JupyterHub.hub_connect_url`. `hub_connect_ip` is not deprecated
+  and can still be used in the common case where only the ip address of the hub differs from the bind ip.
+
+#### Added
+
+- Spawners can define a `.progress` method which should be an async generator.
+  The generator should yield events of the form:
+  ```python
+  {
+    "message": "some-state-message",
+    "progress": 50,
+  }
+  ```
+  These messages will be shown with a progress bar on the spawn-pending page.
+  The `async_generator` package can be used to make async generators
+  compatible with Python 3.5.
+- track activity of individual API tokens
+- new REST API for managing API tokens at `/hub/api/user/tokens[/token-id]`
+- allow viewing/revoking tokens via token page
+- User creation time is available in the REST API as `User.created`
+- Server start time is stored as `Server.started`
+- `Spawner.start` may return a URL for connecting to a notebook instead of `(ip, port)`. This enables Spawners to launch servers that setup their own HTTPS.
+- Optimize database performance by disabling sqlalchemy expire_on_commit by default.
+- Add `python -m jupyterhub.dbutil shell` entrypoint for quickly
+  launching an IPython session connected to your JupyterHub database.
+- Include `User.auth_state` in user model on single-user REST endpoints for admins only.
+- Include `Server.state` in server model on REST endpoints for admins only.
+- Add `Authenticator.blacklist` for blacklisting users instead of whitelisting.
+- Pass `c.JupyterHub.tornado_settings['cookie_options']` down to Spawners
+  so that cookie options (e.g. `expires_days`) can be set globally for the whole application.
+- SIGINFO (`ctrl-t`) handler showing the current status of all running threads,
+  coroutines, and CPU/memory/FD consumption.
+- Add async `Spawner.get_options_form` alternative to `.options_form`, so it can be a coroutine.
+- Add `JupyterHub.redirect_to_server` config to govern whether
+  users should be sent to their server on login or the JuptyerHub home page.
+- html page templates can be more easily customized and extended.
+- Allow registering external OAuth clients for using the Hub as an OAuth provider.
+- Add basic prometheus metrics at `/hub/metrics` endpoint.
+- Add session-id cookie, enabling immediate revocation of login tokens.
+- Authenticators may specify that users are admins by specifying the `admin` key when return the user model as a dict.
+- Added "Start All" button to admin page for launching all user servers at once.
+- Services have an `info` field which is a dictionary.
+  This is accessible via the REST API.
+- `JupyterHub.extra_handlers` allows defining additonal tornado RequestHandlers attached to the Hub.
+- API tokens may now expire.
+  Expiry is available in the REST model as `expires_at`,
+  and settable when creating API tokens by specifying `expires_in`.
+
+
+#### Fixed
+
+- Remove green from theme to improve accessibility
+- Fix error when proxy deletion fails due to route already being deleted
+- clear `?redirects` from URL on successful launch
+- disable send2trash by default, which is rarely desirable for jupyterhub
+- Put PAM calls in a thread so they don't block the main application
+  in cases where PAM is slow (e.g. LDAP).
+- Remove implicit spawn from login handler,
+  instead relying on subsequent request for `/user/:name` to trigger spawn.
+- Fixed several inconsistencies for initial redirects,
+  depending on whether server is running or not and whether the user is logged in or not.
+- Admin requests for  `/user/:name` (when admin-access is enabled) launch the right server if it's not running instead of redirecting to their own.
+- Major performance improvement starting up JupyterHub with many users,
+  especially when most are inactive.
+- Various fixes in race conditions and performance improvements with the default proxy.
+- Fixes for CORS headers
+- Stop setting `.form-control` on spawner form inputs unconditionally.
+- Better recovery from database errors and database connection issues
+  without having to restart the Hub.
+- Fix handling of `~` character in usernames.
+- Fix jupyterhub startup when `getpass.getuser()` would fail,
+  e.g. due to missing entry in passwd file in containers.
+
+
+## 0.8
+
+### [0.8.1] 2017-11-07
+
+JupyterHub 0.8.1 is a collection of bugfixes and small improvements on 0.8.
+
+#### Added
+
+- 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,
+   caused by common `set('string')` typo in config.
+
+#### Fixed
+
+- Removed spurious warning about empty `next_url`, which is AOK.
+
+### [0.7.0] - 2016-12-2
+
+#### Added
+
+- Implement Services API [\#705](https://github.com/jupyterhub/jupyterhub/pull/705)
+- Add `/api/` and `/api/info` endpoints [\#675](https://github.com/jupyterhub/jupyterhub/pull/675)
+- Add documentation for JupyterLab, pySpark configuration, troubleshooting,
+  and more.
+- Add logging of error if adding users already in database.  [\#689](https://github.com/jupyterhub/jupyterhub/pull/689)
+- Add HubAuth class for authenticating with JupyterHub. This class can
+  be used by any application, even outside tornado.
+- Add user groups.
+- Add `/hub/user-redirect/...` URL for redirecting users to a file on their own server.
+
+
+#### Changed
+
+- Always install with setuptools but not eggs (effectively require
+  `pip install .`) [\#722](https://github.com/jupyterhub/jupyterhub/pull/722)
+- Updated formatting of changelog. [\#711](https://github.com/jupyterhub/jupyterhub/pull/711)
+- Single-user server is provided by JupyterHub package, so single-user servers depend on JupyterHub now.
+
+#### Fixed
+
+- Fix docker repository location [\#719](https://github.com/jupyterhub/jupyterhub/pull/719)
+- Fix swagger spec conformance and timestamp type in API spec
+- Various redirect-loop-causing bugs have been fixed.
+
+
+#### Removed
+
+- Deprecate `--no-ssl` command line option. It has no meaning and warns if
+  used. [\#789](https://github.com/jupyterhub/jupyterhub/pull/789)
+- Deprecate `%U` username substitution in favor of `{username}`. [\#748](https://github.com/jupyterhub/jupyterhub/pull/748)
+- Removed deprecated SwarmSpawner link.  [\#699](https://github.com/jupyterhub/jupyterhub/pull/699)
+
+## 0.6
+
+### [0.6.1] - 2016-05-04
+
+Bugfixes on 0.6:
+
+- statsd is an optional dependency, only needed if in use
+- Notice more quickly when servers have crashed
+- Better error pages for proxy errors
+- Add Stop All button to admin panel for stopping all servers at once
+
+### [0.6.0] - 2016-04-25
+
+- JupyterHub has moved to a new `jupyterhub` namespace on GitHub and Docker. What was `juptyer/jupyterhub` is now `jupyterhub/jupyterhub`, etc.
+- `jupyterhub/jupyterhub` image on DockerHub no longer loads the jupyterhub_config.py in an ONBUILD step. A new `jupyterhub/jupyterhub-onbuild` image does this
+- Add statsd support, via `c.JupyterHub.statsd_{host,port,prefix}`
+- Update to traitlets 4.1 `@default`, `@observe` APIs for traits
+- Allow disabling PAM sessions via `c.PAMAuthenticator.open_sessions = False`. This may be needed on SELinux-enabled systems, where our PAM session logic often does not work properly
+- Add `Spawner.environment` configurable, for defining extra environment variables to load for single-user servers
+- JupyterHub API tokens can be pregenerated and loaded via `JupyterHub.api_tokens`, a dict of `token: username`.
+- JupyterHub API tokens can be requested via the REST API, with a POST request to `/api/authorizations/token`.
+  This can only be used if the Authenticator has a username and password.
+- Various fixes for user URLs and redirects
+
+
+## [0.5] - 2016-03-07
+
+
+- Single-user server must be run with Jupyter Notebook ≥ 4.0
+- Require `--no-ssl` confirmation to allow the Hub to be run without SSL (e.g. behind SSL termination in nginx)
+- Add lengths to text fields for MySQL support
+- Add `Spawner.disable_user_config` for preventing user-owned configuration from modifying single-user servers.
+- Fixes for MySQL support.
+- Add ability to run each user's server on its own subdomain. Requires wildcard DNS and wildcard SSL to be feasible. Enable subdomains by setting `JupyterHub.subdomain_host = 'https://jupyterhub.domain.tld[:port]'`.
+- Use `127.0.0.1` for local communication instead of `localhost`, avoiding issues with DNS on some systems.
+- Fix race that could add users to proxy prematurely if spawning is slow.
 
 ## 0.4
 
-### 0.4.1
+### [0.4.1] - 2016-02-03
 
 Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 
-### 0.4.0
+### [0.4.0] - 2016-02-01
 
 - Add `Spawner.user_options_form` for specifying an HTML form to present to users,
   allowing users to influence the spawning of their own servers.
@@ -19,7 +383,7 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 - 0.4 will be the last JupyterHub release where single-user servers running IPython 3 is supported instead of Notebook ≥ 4.0.
 
 
-## 0.3
+## [0.3] - 2015-11-04
 
 - No longer make the user starting the Hub an admin
 - start PAM sessions on login
@@ -27,13 +391,30 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
   allowing deeper interaction between Spawner/Authenticator pairs.
 - login redirect fixes
 
-## 0.2
+## [0.2] - 2015-07-12
 
 - Based on standalone traitlets instead of IPython.utils.traitlets
 - multiple users in admin panel
 - Fixes for usernames that require escaping
 
-## 0.1
+## 0.1 - 2015-03-07
 
 First preview release
 
+
+[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/0.9.2...HEAD
+[0.9.2]: https://github.com/jupyterhub/jupyterhub/compare/0.9.1...0.9.2
+[0.9.1]: https://github.com/jupyterhub/jupyterhub/compare/0.9.0...0.9.1
+[0.9.0]: https://github.com/jupyterhub/jupyterhub/compare/0.8.1...0.9.0
+[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
+[0.6.0]: https://github.com/jupyterhub/jupyterhub/compare/0.5.0...0.6.0
+[0.5]: https://github.com/jupyterhub/jupyterhub/compare/0.4.1...0.5.0
+[0.4.1]: https://github.com/jupyterhub/jupyterhub/compare/0.4.0...0.4.1
+[0.4.0]: https://github.com/jupyterhub/jupyterhub/compare/0.3.0...0.4.0
+[0.3]: https://github.com/jupyterhub/jupyterhub/compare/0.2.0...0.3.0
+[0.2]: https://github.com/jupyterhub/jupyterhub/compare/0.1.0...0.2.0

docs/source/conf.py

@@ -1,59 +1,30 @@
 # -*- coding: utf-8 -*-
 #
-# JupyterHub documentation build configuration file, created by
-# sphinx-quickstart on Mon Jan  4 16:31:09 2016.
-#
-# This file is execfile()d with the current directory set to its
-# containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
-
 import sys
 import os
 import shlex
 
-# Needed for conversion from markdown to html
+# For conversion from markdown to html
 import recommonmark.parser
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+# Set paths
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.3'
+# Minimal Sphinx version
+needs_sphinx = '1.4'
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
+# Sphinx extension modules
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'autodoc_traits',
 ]
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
-# Jupyter uses recommonmark's parser to convert markdown
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
-
-# The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst', '.md']
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
 # The master toctree document.
 master_doc = 'index'
 
@@ -62,246 +33,137 @@ project = u'JupyterHub'
 copyright = u'2016, Project Jupyter team'
 author = u'Project Jupyter team'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-# Project Jupyter uses the following to autopopulate version
+# Autopopulate version
 from os.path import dirname
-root = dirname(dirname(dirname(__file__)))
+
+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.
 version = '%i.%i' % jupyterhub.version_info[:2]
 # The full version, including alpha/beta/rc tags.
 release = jupyterhub.__version__
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
 language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
 exclude_patterns = []
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
-# The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
-
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# Set the default role so we can use `foo` instead of ``foo``
+default_role = 'literal'
+
+# -- Source -------------------------------------------------------------
+
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+
+source_suffix = ['.rst', '.md']
+# source_encoding = 'utf-8-sig'
 
 # -- Options for HTML output ----------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+# The theme to use for HTML and HTML Help pages.
+html_theme = 'alabaster'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
+html_logo = '_static/images/logo/logo.png'
+html_favicon = '_static/images/logo/favicon.ico'
 
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
+# Paths that contain custom static files (such as style sheets)
 html_static_path = ['_static']
 
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
+html_theme_options = {
+    'show_related': True,
+    'description': 'Documentation for JupyterHub',
+    'github_user': 'jupyterhub',
+    'github_repo': 'jupyterhub',
+    'github_banner': False,
+    'github_button': True,
+    'github_type': 'star',
+    'show_powered_by': False,
+    'extra_nav_links': {
+        'GitHub Repo': 'http://github.com/jupyterhub/jupyterhub',
+        'Issue Tracker': 'http://github.com/jupyterhub/jupyterhub/issues',
+    },
+}
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
+html_sidebars = {
+    '**': [
+        'about.html',
+        'searchbox.html',
+        'navigation.html',
+        'relations.html',
+        'sourcelink.html',
+    ]
+}
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-#html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
-
-# Output file base name for HTML help builder.
 htmlhelp_basename = 'JupyterHubdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-
-# Latex figure (float) alignment
-#'figure_align': 'htbp',
+    # 'papersize': 'letterpaper',
+    # 'pointsize': '10pt',
+    # 'preamble': '',
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, 'JupyterHub.tex', u'JupyterHub Documentation',
-   u'Project Jupyter team', 'manual'),
+    (
+        master_doc,
+        'JupyterHub.tex',
+        u'JupyterHub Documentation',
+        u'Project Jupyter team',
+        'manual',
+    )
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
+# latex_logo = None
+# latex_use_parts = False
+# latex_show_pagerefs = False
+# latex_show_urls = False
+# latex_appendices = []
+# latex_domain_indices = True
 
 
-# -- Options for manual page output ---------------------------------------
+# -- manual page output -------------------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
-    (master_doc, 'jupyterhub', u'JupyterHub Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, 'jupyterhub', u'JupyterHub Documentation', [author], 1)]
 
-# If true, show URL addresses after external links.
-#man_show_urls = False
+# man_show_urls = False
 
 
-# -- Options for Texinfo output -------------------------------------------
+# -- Texinfo output -----------------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, 'JupyterHub', u'JupyterHub Documentation',
-   author, 'JupyterHub', 'One line description of project.',
-   'Miscellaneous'),
+    (
+        master_doc,
+        'JupyterHub',
+        u'JupyterHub Documentation',
+        author,
+        'JupyterHub',
+        'One line description of project.',
+        'Miscellaneous',
+    )
 ]
 
-# Documents to append as an appendix to all manuals.
-#texinfo_appendices = []
-
-# If false, no module index is generated.
-#texinfo_domain_indices = True
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = 'footnote'
-
-# If true, do not generate a @detailmenu in the "Top" node's menu.
-#texinfo_no_detailmenu = False
+# texinfo_appendices = []
+# texinfo_domain_indices = True
+# texinfo_show_urls = 'footnote'
+# texinfo_no_detailmenu = False
 
 
-# -- Options for Epub output ----------------------------------------------
+# -- Epub output --------------------------------------------------------
 
 # Bibliographic Dublin Core info.
 epub_title = project
@@ -309,78 +171,32 @@ epub_author = author
 epub_publisher = author
 epub_copyright = copyright
 
-# The basename for the epub file. It defaults to the project name.
-#epub_basename = project
-
-# The HTML theme for the epub output. Since the default themes are not optimized
-# for small screen space, using the same theme for HTML and epub output is
-# usually not wise. This defaults to 'epub', a theme designed to save visual
-# space.
-#epub_theme = 'epub'
-
-# The language of the text. It defaults to the language option
-# or 'en' if the language is not set.
-#epub_language = ''
-
-# The scheme of the identifier. Typical schemes are ISBN or URL.
-#epub_scheme = ''
-
-# The unique identifier of the text. This can be a ISBN number
-# or the project homepage.
-#epub_identifier = ''
-
-# A unique identification for the text.
-#epub_uid = ''
-
-# A tuple containing the cover image and cover page html template filenames.
-#epub_cover = ()
-
-# A sequence of (type, uri, title) tuples for the guide element of content.opf.
-#epub_guide = ()
-
-# HTML files that should be inserted before the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_pre_files = []
-
-# HTML files shat should be inserted after the pages created by sphinx.
-# The format is a list of tuples containing the path and title.
-#epub_post_files = []
-
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
 
-# The depth of the table of contents in toc.ncx.
-#epub_tocdepth = 3
+# -- Intersphinx ----------------------------------------------------------
 
-# Allow duplicate toc entries.
-#epub_tocdup = True
+intersphinx_mapping = {'https://docs.python.org/3/': None}
 
-# Choose between 'default' and 'includehidden'.
-#epub_tocscope = 'default'
+# -- Read The Docs --------------------------------------------------------
 
-# Fix unsupported image types using the Pillow.
-#epub_fix_images = False
-
-# Scale large images.
-#epub_max_image_width = 0
-
-# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#epub_show_urls = 'inline'
-
-# If false, no index is generated.
-#epub_use_index = True
-
-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
-
-# Read The Docs
-# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+if not on_rtd:
+    html_theme = 'alabaster'
+else:
+    # readthedocs.org uses their theme by default, so no need to specify it
+    # build rest-api, since RTD doesn't run make
+    from subprocess import check_call as sh
 
-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()]
+    sh(['make', 'rest-api'], cwd=docs)
 
-# otherwise, readthedocs.org uses their theme by default, so no need to specify it
+# -- Spell checking -------------------------------------------------------
+
+try:
+    import sphinxcontrib.spelling
+except ImportError:
+    pass
+else:
+    extensions.append("sphinxcontrib.spelling")
+
+spelling_word_list_filename = 'spelling_wordlist.txt'

docs/source/contributor-list.md

@@ -0,0 +1,122 @@
+# Contributors
+
+Project Jupyter thanks the following people for their help and
+contribution on JupyterHub:
+
+- adelcast
+- Analect
+- anderbubble
+- anikitml
+- ankitksharma
+- apetresc
+- athornton
+- barrachri
+- BerserkerTroll
+- betatim
+- Carreau
+- cfournie
+- charnpreetsingh
+- chicovenancio
+- cikao
+- ckald
+- cmoscardi
+- consideRatio
+- cqzlxl
+- CRegenschein
+- cwaldbieser
+- danielballen
+- danoventa
+- daradib
+- darky2004
+- datapolitan
+- dblockow-d2dcrc
+- DeepHorizons
+- DerekHeldtWerle
+- dhirschfeld
+- dietmarw
+- dingc3
+- dmartzol
+- DominicFollettSmith
+- dsblank
+- dtaniwaki
+- echarles
+- ellisonbg
+- emmanuel
+- evanlinde
+- Fokko
+- fperez
+- franga2000
+- GladysNalvarte
+- glenak1911
+- gweis
+- iamed18
+- jamescurtin
+- JamiesHQ
+- JasonJWilliamsNY
+- jbweston
+- jdavidheiser
+- jencabral
+- jhamrick
+- jkinkead
+- johnkpark
+- josephtate
+- jzf2101
+- karfai
+- kinuax
+- KrishnaPG
+- kroq-gar78
+- ksolan
+- mbmilligan
+- mgeplf
+- minrk
+- mistercrunch
+- Mistobaan
+- mpacer
+- mwmarkland
+- ndly
+- nthiery
+- nxg
+- ObiWahn
+- ozancaglayan
+- paccorsi
+- parente
+- PeterDaveHello
+- peterruppel
+- phill84
+- pjamason
+- prasadkatti
+- rafael-ladislau
+- rcthomas
+- rgbkrk
+- rkdarst
+- robnagler
+- rschroll
+- ryanlovett
+- sangramga
+- Scrypy
+- schon
+- shreddd
+- Siecje
+- smiller5678
+- spoorthyv
+- ssanderson
+- summerswallow
+- syutbai
+- takluyver
+- temogen
+- ThomasMChen
+- Thoralf Gutierrez
+- timfreund
+- TimShawver
+- tklever
+- 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/#/
+
+### jcloud.io
+- Open to public JupyterHub server
+    - https://jcloud.io
+## 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,414 +0,0 @@
-# Getting started with JupyterHub
-
-This document describes some of the basics of configuring JupyterHub to do what you want.
-JupyterHub is highly customizable, so there's a lot to cover.
-
-
-## Installation
-
-See [the readme](https://github.com/jupyter/jupyterhub/blob/master/README.md) for help installing JupyterHub.
-
-
-## Overview
-
-JupyterHub is a set of processes that together provide a multiuser Jupyter Notebook server.
-There are three main categories of processes run by the `jupyterhub` command line program:
-
-- **Single User Server**: a dedicated, single-user, Jupyter Notebook is started for each user on the system
-  when they log in. The object that starts these processes is called a Spawner.
-- **Proxy**: the public facing part of the server that uses a dynamic proxy to route HTTP requests
-  to the Hub and Single User Servers.
-- **Hub**: manages user accounts and authentication and coordinates Single Users Servers using a Spawner.
-
-## JupyterHub's default behavior
-
-
-To start JupyterHub in its default configuration, type the following at the command line:
-
-    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.
-
-**NOTE:** In its default configuration, JupyterHub runs without SSL encryption (HTTPS).
-You should not run JupyterHub without SSL encryption on a public network.
-See [Security documentation](#Security) for how to configure JupyterHub to use SSL.
-
-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.
-- `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.
-
-
-## How to configure JupyterHub
-
-JupyterHub is configured in two ways:
-
-1. Command-line arguments
-2. Configuration files
-
-Type the following for brief information about the command line arguments:
-
-    jupyterhub -h
-
-or:
-
-    jupyterhub --help-all
-
-for the full command line help.
-
-By default, JupyterHub will look for a configuration file (can be missing)
-named `jupyterhub_config.py` in the current working directory.
-You can create an empty configuration file with
-
-
-    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:
-
-    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.
-
-
-## 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:
-
-    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
-
-Security is the most important aspect of configuring Jupyter. There are three 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)
-
-## 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 `your.domain.com` by your fully qualified domain name):
-
-```python
-c.JupyterHub.ssl_key = '/etc/letsencrypt/live/your.domain.com/privkey.pem'
-c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/your.domain.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.
-
-## 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. An example would be to generate this
-file as:
-
-```bash
-openssl rand -hex 1024 > /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 recommended
-permissions for the cookie secret file should be 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:
-
-```bash
-export JPY_COOKIE_SECRET=`openssl rand -hex 1024`
-```
-
-For security reasons, this environment variable should only be visible to the Hub.
-
-## 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:
-
-```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.
-
-## Configuring authentication
-
-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.
-You can restrict which users are allowed to login with `Authenticator.whitelist`:
-
-
-```python
-c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
-```
-
-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.**
-
-### Adding and removing users
-
-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.
-
-## Configuring single-user 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 to run external services.
-More detail on this API will be added in the future.
-
-## 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
-
-## Example
-
-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][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.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
-```
-
-# Further reading
-
-- [Custom Authenticators](./authenticators.html)
-- [Custom Spawners](./spawners.html)
-- [Troubleshooting](./troubleshooting.html)
-
-
-[oauth-setup]: https://github.com/jupyter/oauthenticator#setup
-[oauthenticator]: https://github.com/jupyter/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,101 @@
+# 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.
+
+Note that `c.JupyterHub.ip` and `c.JupyterHub.port` are single values,
+not tuples or lists – JupyterHub listens to only a single IP address and
+port.
+
+## 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.
+```
+
+## Adjusting the hub's URL
+
+The hub will most commonly be running on a hostname of its own.  If it
+is not – for example, if the hub is being reverse-proxied and being
+exposed at a URL such as `https://proxy.example.org/jupyter/` – then
+you will need to tell JupyterHub the base URL of the service.  In such
+a case, it is both necessary and sufficient to set
+`c.JupyterHub.base_url = '/jupyter/'` in the configuration.

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

@@ -0,0 +1,186 @@
+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, for example if the hub is running behind a reverse proxy, and
+`SSL termination is being provided by NGINX <https://www.nginx.com/resources/admin-guide/nginx-ssl-termination/>`_,
+it is reasonable to run the hub without SSL.
+
+To achieve this, simply omit the configuration settings
+``c.JupyterHub.ssl_key`` and ``c.JupyterHub.ssl_cert``
+(setting them to ``None`` does not have the same effect, and is an error).
+
+.. _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': 'python3 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'
+    python3 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 <del>IPython</del> Jupyter notebook server.
-
-There are three basic processes involved:
-
-- multi-user Hub (Python/Tornado)
-- [configurable http proxy](https://github.com/jupyter/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.md).
-
-See a list of custom Authenticators [on the wiki](https://github.com/jupyter/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.md).
-
-See a list of custom Spawners [on the wiki](https://github.com/jupyter/jupyterhub/wiki/Spawners).

docs/source/index.rst

@@ -1,81 +1,125 @@
-.. JupyterHub documentation master file, created by
-   sphinx-quickstart on Mon Jan  4 16:31:09 2016.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 JupyterHub
 ==========
 
-.. note:: This is the official documentation for JupyterHub. This project is
-          under active development.
+`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.
 
-JupyterHub is a multi-user server that manages and proxies multiple instances
-of the single-user Jupyter notebook server.
+.. image:: images/jhub-parts.png
+   :alt: JupyterHub subsystems
+   :width: 40%
+   :align: right
 
-Three actors:
+Three subsystems make up JupyterHub:
 
-* multi-user Hub (tornado process)
-* `configurable http proxy <https://github.com/jupyter/configurable-http-proxy>`_ (node-http-proxy)
-* multiple single-user IPython notebook servers (Python/IPython/tornado)
+* a multi-user **Hub** (tornado process)
+* a **configurable http proxy** (node-http-proxy)
+* multiple **single-user Jupyter notebook servers** (Python/IPython/tornado)
 
-Basic principles:
+JupyterHub performs the following functions:
 
-* 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
+- The Hub launches 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
 
+For convenient administration of the Hub, its users, and services,
+JupyterHub also provides a `REST API`_.
 
-Contents:
+Contents
+--------
 
-.. toctree::
-   :maxdepth: 2
-   :caption: User Documentation
+**Installation Guide**
 
-   getting-started
-   howitworks
+* :doc:`installation-guide`
+* :doc:`quickstart`
+* :doc:`quickstart-docker`
+* :doc:`installation-basics`
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Configuration
+**Getting Started**
 
-   authenticators
-   spawners
-   troubleshooting
+* :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`
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Developer Documentation
-   
-   api/index
+**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/templates`
+* :doc:`reference/config-user-env`
+* :doc:`reference/config-examples`
+* :doc:`reference/config-ghoauth`
+* :doc:`reference/config-proxy`
+* :doc:`reference/config-sudo`
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Community documentation
+**API Reference**
 
+* :doc:`api/index`
 
+**Tutorials**
 
-.. toctree::
-   :maxdepth: 2
-   :caption: About JupyterHub
+* :doc:`tutorials/index`
+* :doc:`tutorials/upgrade-dot-eight`
+* `Zero to JupyterHub with Kubernetes <https://zero-to-jupyterhub.readthedocs.io/en/latest/>`_
 
-   changelog
+**Troubleshooting**
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Questions? Suggestions?
+* :doc:`troubleshooting`
 
-   Jupyter mailing list <https://groups.google.com/forum/#!forum/jupyter>
-   Jupyter website <https://jupyter.org>
-   Stack Overflow - Jupyter <https://stackoverflow.com/questions/tagged/jupyter>
-   Stack Overflow - Jupyter-notebook <https://stackoverflow.com/questions/tagged/jupyter-notebook>
+**About JupyterHub**
 
+* :doc:`contributor-list`
+* :doc:`gallery-jhub-deployments`
+
+**Changelog**
+
+* :doc:`changelog`
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
 
+
+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/admin/volumes/volumes/>`_
+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

@@ -0,0 +1,85 @@
+# Quickstart
+
+## Prerequisites
+
+Before installing JupyterHub, you will need:
+
+- a Linux/Unix based system
+- [Python](https://www.python.org/downloads/) 3.5 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),
+  using your operating system's package manager.
+
+  * If you are using **`conda`**, the nodejs and npm dependencies will be installed for
+    you by conda.
+
+  * If you are using **`pip`**, 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.
+
+- 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), you will need:
+
+- [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`) 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  # installs jupyterhub and proxy
+conda install notebook  # needed if running the notebook servers locally
+```
+
+Test your installation. If installed, these commands should return the packages'
+help contents:
+
+```bash
+jupyterhub -h
+configurable-http-proxy -h
+```
+
+## Start the Hub server
+
+To start the Hub server, run the command:
+
+```bash
+jupyterhub
+```
+
+Visit `https://localhost:8000` in your browser, and sign in with your unix
+credentials.
+
+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*. This requires
+additional configuration of the system.

docs/source/reference/authenticators.md

@@ -0,0 +1,230 @@
+# 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
+- For Shibboleth, [jhub_shibboleth_auth](https://github.com/gesiscss/jhub_shibboleth_auth)
+  and [jhub_remote_user_authenticator](https://github.com/cwaldbieser/jhub_remote_user_authenticator)
+
+## 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
+{
+  'name': username,
+  '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']
+```
+
+## pre_spawn_start and post_spawn_stop hooks
+
+Authenticators uses two hooks, [pre_spawn_start(user, spawner)][] and
+[post_spawn_stop(user, spawner)][] to add pass additional state information
+between the authenticator and a spawner. These hooks are typically used auth-related
+startup, i.e. opening a PAM session, and auth-related cleanup, i.e. closing a
+PAM session.
+
+## 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)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.pre_spawn_start
+[post_spawn_stop(user, spawner)]: https://jupyterhub.readthedocs.io/en/latest/api/auth.html#jupyterhub.auth.Authenticator.post_spawn_stop

docs/source/reference/config-examples.md

@@ -0,0 +1,8 @@
+# Configuration examples
+
+The following sections provide examples, including configuration files and tips, for the
+following:
+
+- Configuring GitHub OAuth
+- Using reverse proxy (nginx and Apache)
+- Run JupyterHub without root privileges using `sudo`

docs/source/reference/config-ghoauth.md

@@ -0,0 +1,82 @@
+# Configure 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
+* Using the default spawner (to configure other spawners, uncomment and edit
+  `spawner_class` as well as follow the instructions for your desired spawner)
+* 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'}
+
+# uses the default spawner
+# To use a different spawner, uncomment `spawner_class` and set to desired
+# spawner (e.g. SudoSpawner). Follow instructions for desired spawner
+# configuration.
+# c.JupyterHub.spawner_class = 'sudospawner.SudoSpawner'
+
+# 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
+```

docs/source/reference/config-proxy.md

@@ -0,0 +1,192 @@
+# 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
+
+This **`nginx` config file** is fairly standard fare except for the two
+`location` blocks within the main section for HUB.DOMAIN.tld.
+To create a new site for jupyterhub in your nginx config, make a new file
+in `sites.enabled`, e.g. `/etc/nginx/sites.enabled/jupyterhub.conf`:
+
+```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/config-sudo.md

@@ -0,0 +1,254 @@
+# Run JupyterHub without root privileges using `sudo`
+
+**Note:** Setting up `sudo` permissions involves many pieces of system
+configuration. It is quite easy to get wrong and very difficult to debug.
+Only do this if you are very sure you must.
+
+## Overview
+
+There are many Authenticators and Spawners available for JupyterHub. Some, such
+as DockerSpawner or OAuthenticator, do not need any elevated permissions. This
+document describes how to get the full default behavior of JupyterHub while
+running notebook servers as real system users on a shared system without 
+running the Hub itself as root.
+
+Since JupyterHub needs to spawn processes as other users, the simplest way
+is to run it as root, spawning user servers with [setuid](http://linux.die.net/man/2/setuid).
+But this isn't especially safe, because you have a process running on the
+public web as root.
+
+A **more prudent way** to run the server while preserving functionality is to
+create a dedicated user with `sudo` access restricted to launching and
+monitoring single-user servers.
+
+## Create a user
+
+To do this, first create a user that will run the Hub:
+
+```bash
+sudo useradd rhea
+```
+
+This user shouldn't have a login shell or password (possible with -r).
+
+## Set up sudospawner
+
+Next, you will need [sudospawner](https://github.com/jupyter/sudospawner)
+to enable monitoring the single-user servers with sudo:
+
+```bash
+sudo pip install sudospawner
+```
+
+Now we have to configure sudo to allow the Hub user (`rhea`) to launch
+the sudospawner script on behalf of our hub users (here `zoe` and `wash`).
+We want to confine these permissions to only what we really need.
+
+## Edit `/etc/sudoers`
+
+To do this we add to `/etc/sudoers` (use `visudo` for safe editing of sudoers):
+
+- specify the list of users `JUPYTER_USERS` for whom `rhea` can spawn servers
+- set the command `JUPYTER_CMD` that `rhea` can execute on behalf of users
+- give `rhea` permission to run `JUPYTER_CMD` on behalf of `JUPYTER_USERS` 
+  without entering a password
+
+
+For example:
+
+```bash
+# comma-separated whitelist of users that can spawn single-user servers
+# this should include all of your Hub users
+Runas_Alias JUPYTER_USERS = rhea, zoe, wash
+
+# the command(s) the Hub can run on behalf of the above users without needing a password
+# the exact path may differ, depending on how sudospawner was installed
+Cmnd_Alias JUPYTER_CMD = /usr/local/bin/sudospawner
+
+# actually give the Hub user permission to run the above command on behalf
+# of the above users without prompting for a password
+rhea ALL=(JUPYTER_USERS) NOPASSWD:JUPYTER_CMD
+```
+
+It might be useful to modifiy `secure_path` to add commands in path.
+
+As an alternative to adding every user to the `/etc/sudoers` file, you can
+use a group in the last line above, instead of `JUPYTER_USERS`:
+
+```bash
+rhea ALL=(%jupyterhub) NOPASSWD:JUPYTER_CMD
+```
+
+If the `jupyterhub` group exists, there will be no need to edit `/etc/sudoers`
+again. A new user will gain access to the application when added to the group:
+
+```bash
+$ adduser -G jupyterhub newuser
+```
+
+## Test `sudo` setup
+
+Test that the new user doesn't need to enter a password to run the sudospawner
+command.
+
+This should prompt for your password to switch to rhea, but *not* prompt for
+any password for the second switch. It should show some help output about
+logging options:
+
+```bash
+$ sudo -u rhea sudo -n -u $USER /usr/local/bin/sudospawner --help
+Usage: /usr/local/bin/sudospawner [OPTIONS]
+    
+Options:
+    
+--help          show this help information
+...
+```
+
+And this should fail:
+
+```bash
+$ sudo -u rhea sudo -n -u $USER echo 'fail'
+sudo: a password is required
+```
+
+## Enable PAM for non-root
+
+By default, [PAM authentication](http://en.wikipedia.org/wiki/Pluggable_authentication_module)
+is used by JupyterHub. To use PAM, the process may need to be able to read
+the shadow password database.
+
+### Shadow group (Linux)
+
+```bash
+$ ls -l /etc/shadow
+-rw-r-----  1 root shadow   2197 Jul 21 13:41 shadow
+```
+
+If there's already a shadow group, you are set. If its permissions are more like:
+
+```bash
+    $ ls -l /etc/shadow
+    -rw-------  1 root wheel   2197 Jul 21 13:41 shadow
+```
+
+Then you may want to add a shadow group, and make the shadow file group-readable:
+
+```bash
+$ sudo groupadd shadow
+$ sudo chgrp shadow /etc/shadow
+$ sudo chmod g+r /etc/shadow
+```
+
+We want our new user to be able to read the shadow passwords, so add it to the shadow group:
+
+```bash
+    $ sudo usermod -a -G shadow rhea
+```
+
+If you want jupyterhub to serve pages on a restricted port (such as port 80 for http), 
+then you will need to give `node` permission to do so:
+
+```bash
+sudo setcap 'cap_net_bind_service=+ep' /usr/bin/node
+```
+However, you may want to further understand the consequences of this.
+
+You may also be interested in limiting the amount of CPU any process can use
+on your server. `cpulimit` is a useful tool that is available for many Linux
+distributions' packaging system. This can be used to keep any user's process
+from using too much CPU cycles. You can configure it accoring to [these
+instructions](http://ubuntuforums.org/showthread.php?t=992706).
+
+
+### Shadow group (FreeBSD)
+
+**NOTE:** This has not been tested and may not work as expected.
+
+```bash
+$ ls -l /etc/spwd.db /etc/master.passwd
+-rw-------  1 root  wheel   2516 Aug 22 13:35 /etc/master.passwd
+-rw-------  1 root  wheel  40960 Aug 22 13:35 /etc/spwd.db
+```
+
+Add a shadow group if there isn't one, and make the shadow file group-readable:
+
+```bash
+$ sudo pw group add shadow
+$ sudo chgrp shadow /etc/spwd.db
+$ sudo chmod g+r /etc/spwd.db
+$ sudo chgrp shadow /etc/master.passwd
+$ sudo chmod g+r /etc/master.passwd
+```
+
+We want our new user to be able to read the shadow passwords, so add it to the 
+shadow group:
+
+```bash
+$ sudo pw user mod rhea -G shadow
+```
+
+## Test that PAM works
+
+We can verify that PAM is working, with:
+
+```bash
+$ sudo -u rhea python3 -c "import pamela, getpass; print(pamela.authenticate('$USER', getpass.getpass()))"
+Password: [enter your unix password]
+```
+
+## Make a directory for JupyterHub
+
+JupyterHub stores its state in a database, so it needs write access to a directory.
+The simplest way to deal with this is to make a directory owned by your Hub user,
+and use that as the CWD when launching the server.
+
+```bash
+    $ sudo mkdir /etc/jupyterhub
+    $ sudo chown rhea /etc/jupyterhub
+```
+
+## Start jupyterhub
+
+Finally, start the server as our newly configured user, `rhea`:
+
+```bash
+    $ cd /etc/jupyterhub
+    $ sudo -u rhea jupyterhub --JupyterHub.spawner_class=sudospawner.SudoSpawner
+```
+
+And try logging in.
+
+### Troubleshooting: SELinux
+
+If you still get a generic `Permission denied` `PermissionError`, it's possible SELinux is blocking you.  
+Here's how you can make a module to allow this.
+First, put this in a file sudo_exec_selinux.te:
+
+```bash
+module sudo_exec 1.1;
+
+require {
+        type unconfined_t;
+        type sudo_exec_t;
+        class file { read entrypoint };
+}
+
+#============= unconfined_t ==============
+allow unconfined_t sudo_exec_t:file entrypoint;
+```
+
+Then run all of these commands as root:
+
+```bash
+$ checkmodule -M -m -o sudo_exec_selinux.mod sudo_exec_selinux.te
+$ semodule_package -o sudo_exec_selinux.pp -m sudo_exec_selinux.mod
+$ semodule -i sudo_exec_selinux.pp
+```
+
+### Troubleshooting: PAM session errors
+
+If the PAM authentication doesn't work and you see errors for
+`login:session-auth`, or similar, considering updating to `master` 
+and/or incorporating this commit https://github.com/jupyter/jupyterhub/commit/40368b8f555f04ffdd662ffe99d32392a088b1d2
+and configuration option, `c.PAMAuthenticator.open_sessions = False`.

docs/source/reference/config-user-env.md

@@ -0,0 +1,147 @@
+# Configuring user environments
+
+Deploying JupyterHub means you are providing Jupyter notebook environments for
+multiple users. Often, this includes a desire to configure the user
+environment in some way.
+
+Since the `jupyterhub-singleuser` server extends the standard Jupyter notebook
+server, most configuration and documentation that applies to Jupyter Notebook
+applies to the single-user environments. Configuration of user environments
+typically does not occur through JupyterHub itself, but rather through system-
+wide configuration of Jupyter, which is inherited by `jupyterhub-singleuser`.
+
+**Tip:** When searching for configuration tips for JupyterHub user
+environments, try removing JupyterHub from your search because there are a lot
+more people out there configuring Jupyter than JupyterHub and the
+configuration is the same.
+
+This section will focus on user environments, including:
+
+- Installing packages
+- Configuring Jupyter and IPython
+- Installing kernelspecs
+- Using containers vs. multi-user hosts
+
+
+## Installing packages
+
+To make packages available to users, you generally will install packages
+system-wide or in a shared environment.
+
+This installation location should always be in the same environment that
+`jupyterhub-singleuser` itself is installed in, and must be *readable and
+executable* by your users. If you want users to be able to install additional
+packages, it must also be *writable* by your users.
+
+If you are using a standard system Python install, you would use:
+
+
+```bash
+sudo python3 -m pip install numpy
+```
+
+to install the numpy package in the default system Python 3 environment
+(typically `/usr/local`).
+
+You may also use conda to install packages. If you do, you should make sure
+that the conda environment has appropriate permissions for users to be able to
+run Python code in the env.
+
+
+## Configuring Jupyter and IPython
+
+[Jupyter](https://jupyter-notebook.readthedocs.io/en/stable/config_overview.html)
+and [IPython](https://ipython.readthedocs.io/en/stable/development/config.html)
+have their own configuration systems.
+
+As a JupyterHub administrator, you will typically want to install and configure
+environments for all JupyterHub users. For example, you wish for each student in
+a class to have the same user environment configuration.
+
+Jupyter and IPython support **"system-wide"** locations for configuration, which
+is the logical place to put global configuration that you want to affect all
+users. It's generally more efficient to configure user environments "system-wide",
+and it's a good idea to avoid creating files in users' home directories.
+
+The typical locations for these config files are:
+- **system-wide** in `/etc/{jupyter|ipython}`
+- **env-wide** (environment wide) in `{sys.prefix}/etc/{jupyter|ipython}`.
+
+### Example: Enable an extension system-wide
+
+For example, to enable the `cython` IPython extension for all of your users,
+create the file `/etc/ipython/ipython_config.py`:
+
+```python
+c.InteractiveShellApp.extensions.append("cython")
+```
+
+### Example: Enable a Jupyter notebook configuration setting for all users
+
+To enable Jupyter notebook's internal idle-shutdown behavior (requires
+notebook ≥ 5.4), set the following in the `/etc/jupyter/jupyter_notebook_config.py`
+file:
+
+```python
+# shutdown the server after no activity for an hour
+c.NotebookApp.shutdown_no_activity_timeout = 60 * 60
+# shutdown kernels after no activity for 20 minutes
+c.MappingKernelManager.cull_idle_timeout = 20 * 60
+# check for idle kernels every two minutes
+c.MappingKernelManager.cull_interval = 2 * 60
+```
+
+
+## Installing kernelspecs
+
+You may have multiple Jupyter kernels installed and want to make sure that
+they are available to all of your users. This means installing kernelspecs
+either system-wide (e.g. in /usr/local/) or in the `sys.prefix` of JupyterHub
+itself.
+
+Jupyter kernelspec installation is system wide by default, but some kernels
+may default to installing kernelspecs in your home directory. These will need
+to be moved system-wide to ensure that they are accessible.
+
+You can see where your kernelspecs are with:
+
+```bash
+jupyter kernelspec list
+```
+
+### Example: Installing kernels system-wide
+
+Assuming I have a Python 2 and Python 3 environment that I want to make
+sure are available, I can install their specs system-wide (in /usr/local) with:
+
+```bash
+/path/to/python3 -m IPython kernel install --prefix=/usr/local
+/path/to/python2 -m IPython kernel install --prefix=/usr/local
+```
+
+
+## Multi-user hosts vs. Containers 
+
+There are two broad categories of user environments that depend on what
+Spawner you choose:
+
+- Multi-user hosts (shared sytem)
+- Container-based
+
+How you configure user environments for each category can differ a bit
+depending on what Spawner you are using.
+
+The first category is a **shared system (multi-user host)** where
+each user has a JupyterHub account and a home directory as well as being
+a real system user. In this example, shared configuration and installation
+must be in a 'system-wide' location, such as `/etc/` or `/usr/local`
+or a custom prefix such as `/opt/conda`.
+
+When JupyterHub uses **container-based** Spawners (e.g. KubeSpawner or
+DockerSpawner), the 'system-wide' environment is really the container image
+which you are using for users.
+
+In both cases, you want to *avoid putting configuration in user home
+directories* because users can change those configuration settings. Also,
+home directories typically persist once they are created, so they are
+difficult for admins to update later.

docs/source/reference/database.md

@@ -0,0 +1,62 @@
+# The Hub's Database
+
+JupyterHub uses a database to store information about users, services, and other
+data needed for operating the Hub.
+
+## Default SQLite database
+
+The default database for JupyterHub is a [SQLite](https://sqlite.org) database.
+We have chosen SQLite as JupyterHub's default for its lightweight simplicity
+in certain uses such as testing, small deployments and workshops.
+
+For production systems, SQLite has some disadvantages when used with JupyterHub:
+
+- `upgrade-db` may not work, and you may need to start with a fresh database
+- `downgrade-db` **will not** work if you want to rollback to an earlier
+  version, so backup the `jupyterhub.sqlite` file before upgrading
+
+The sqlite documentation provides a helpful page about [when to use SQLite and
+where traditional RDBMS may be a better choice](https://sqlite.org/whentouse.html).
+
+## Using an RDBMS (PostgreSQL, MySQL)
+
+When running a long term deployment or a production system, we recommend using
+a traditional RDBMS database, such as [PostgreSQL](https://www.postgresql.org)
+or [MySQL](https://www.mysql.com), that supports the SQL `ALTER TABLE`
+statement.
+
+## Notes and Tips
+
+### SQLite
+
+The SQLite database should not be used on NFS. SQLite uses reader/writer locks
+to control access to the database. This locking mechanism might not work
+correctly if the database file is kept on an NFS filesystem. This is because
+`fcntl()` file locking is broken on many NFS implementations. Therefore, you
+should avoid putting SQLite database files on NFS since it will not handle well
+multiple processes which might try to access the file at the same time.
+
+### PostgreSQL
+
+We recommend using PostgreSQL for production if you are unsure whether to use
+MySQL or PostgreSQL or if you do not have a strong preference. There is
+additional configuration required for MySQL that is not needed for PostgreSQL.
+
+### MySQL / MariaDB
+
+- You should use the `pymysql` sqlalchemy provider (the other one, MySQLdb,
+  isn't available for py3).
+- You also need to set `pool_recycle` to some value (typically 60 - 300) 
+  which depends on your  MySQL setup. This is necessary since MySQL kills
+  connections serverside if they've been idle for a while, and the connection
+  from the hub will be idle for longer than most connections. This behavior
+  will lead to frustrating 'the connection has gone away' errors from
+  sqlalchemy if `pool_recycle` is not set.
+- If you use `utf8mb4` collation with MySQL earlier than 5.7.7 or MariaDB
+  earlier than 10.2.1 you may get an `1709, Index column size too large` error.
+  To fix this you need to set `innodb_large_prefix` to enabled and
+  `innodb_file_format` to `Barracuda` to allow for the index sizes jupyterhub
+  uses. `row_format` will be set to `DYNAMIC` as long as those options are set
+  correctly. Later versions of MariaDB and MySQL should set these values by
+  default, as well as have a default `DYNAMIC` `row_format` and pose no trouble
+  to users.

docs/source/reference/index.rst

@@ -0,0 +1,21 @@
+Technical Reference
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   technical-overview
+   websecurity
+   authenticators
+   spawners
+   services
+   proxy
+   rest
+   database
+   upgrading
+   templates
+   config-user-env
+   config-examples
+   config-ghoauth
+   config-proxy
+   config-sudo

docs/source/reference/proxy.md

@@ -0,0 +1,181 @@
+# 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 the
+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
+```
+
+## 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

@@ -0,0 +1,374 @@
+# Services
+
+With version 0.7, JupyterHub adds support for **Services**.
+
+This section provides the following information about 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
+
+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
+action or task. For example, the following tasks can each be a unique Service:
+
+- shutting down individuals' single user notebook servers that have been idle
+  for some time
+- registering additional web servers which should use the Hub's authentication
+  and be served behind the Hub's proxy.
+
+Two key features help define a Service:
+
+- Is the Service **managed** by JupyterHub?
+- Does the Service have a web server that should be added to the proxy's
+  table?
+
+Currently, these characteristics distinguish two types of Services:
+
+- A **Hub-Managed Service** which is managed by JupyterHub
+- An **Externally-Managed Service** which runs its own web server and
+  communicates operation instructions via the Hub's API.
+
+## Properties of a Service
+
+A Service may have the following properties:
+
+- `name: str` - the name of the service
+- `admin: bool (default - false)` - whether the service should have
+  administrative privileges
+- `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:
+
+- `command: (str/Popen list`) - Command for JupyterHub to spawn the service.
+      - Only use this if the service should be a subprocess.
+      - If command is not specified, the Service is assumed to be managed
+        externally.
+      - If a command is specified for launching the Service, the Service will
+        be started and managed by the Hub.
+- `environment: dict` - additional environment variables for the Service.
+- `user: str` - the name of a system user to manage the Service. If
+  unspecified, run as the same user as the Hub.
+
+## Hub-Managed Services
+
+A **Hub-Managed Service** is started by the Hub, and the Hub is responsible
+for the Service's actions. A Hub-Managed Service can only be a local
+subprocess of the Hub. The Hub will take care of starting the process and
+restarts it if it stops.
+
+While Hub-Managed Services share some similarities with notebook Spawners,
+there are no plans for Hub-Managed Services to support the same spawning
+abstractions as a notebook Spawner.
+
+If you wish to run a Service in a Docker container or other deployment
+environments, the Service can be registered as an
+**Externally-Managed Service**, as described below.
+
+## Launching a Hub-Managed Service
+
+A Hub-Managed Service is characterized by its specified `command` for launching
+the Service. For example, a 'cull idle' notebook server task configured as a
+Hub-Managed Service would include:
+
+- the Service name,
+- admin permissions, and
+- the `command` to launch the Service which will cull idle servers after a
+  timeout interval
+
+This example would be configured as follows in `jupyterhub_config.py`:
+
+```python
+c.JupyterHub.services = [
+    {
+        'name': 'cull-idle',
+        'admin': True,
+        'command': ['python', '/path/to/cull-idle.py', '--timeout']
+    }
+]
+```
+
+A Hub-Managed Service may also be configured with additional optional
+parameters, which describe the environment needed to start the Service process:
+
+- `environment: dict` - additional environment variables for the Service.
+- `user: str` - name of the user to run the server if different from the Hub.
+   Requires Hub to be root.
+- `cwd: path` directory in which to run the Service, if different from the
+   Hub directory.
+
+The Hub will pass the following environment variables to launch the Service:
+
+```bash
+JUPYTERHUB_SERVICE_NAME:   The name of the service
+JUPYTERHUB_API_TOKEN:      API token assigned to the service
+JUPYTERHUB_API_URL:        URL for the JupyterHub API (default, http://127.0.0.1:8080/hub/api)
+JUPYTERHUB_BASE_URL:       Base URL of the Hub (https://mydomain[:port]/)
+JUPYTERHUB_SERVICE_PREFIX: URL path prefix of this service (/services/:service-name/)
+JUPYTERHUB_SERVICE_URL:    Local URL where the service is expected to be listening.
+                           Only for proxied web services.
+```
+
+For the previous 'cull idle' Service example, these environment variables
+would be passed to the Service when the Hub starts the 'cull idle' Service:
+
+```bash
+JUPYTERHUB_SERVICE_NAME: 'cull-idle'
+JUPYTERHUB_API_TOKEN: API token assigned to the service
+JUPYTERHUB_API_URL: http://127.0.0.1:8080/hub/api
+JUPYTERHUB_BASE_URL: https://mydomain[:port]
+JUPYTERHUB_SERVICE_PREFIX: /services/cull-idle/
+```
+
+See the JupyterHub GitHub repo for additional information about the
+[`cull-idle` example](https://github.com/jupyterhub/jupyterhub/tree/master/examples/cull-idle).
+
+## Externally-Managed Services
+
+You may prefer to use your own service management tools, such as Docker or
+systemd, to manage a JupyterHub Service. These **Externally-Managed
+Services**, unlike Hub-Managed Services, are not subprocesses of the Hub. You
+must tell JupyterHub which API token the Externally-Managed Service is using
+to perform its API requests. Each Externally-Managed Service will need a
+unique API token, because the Hub authenticates each API request and the API
+token is used to identify the originating Service or user.
+
+A configuration example of an Externally-Managed Service with admin access and
+running its own web server is:
+
+```python
+c.JupyterHub.services = [
+    {
+        'name': 'my-web-service',
+        'url': 'https://10.0.1.1:1984',
+        'api_token': 'super-secret',
+    }
+]
+```
+
+In this case, the `url` field will be passed along to the Service as
+`JUPYTERHUB_SERVICE_URL`.
+
+## Writing your own Services
+
+When writing your own services, you have a few decisions to make (in addition
+to what your service does!):
+
+1. Does my service need a public URL?
+2. Do I want JupyterHub to start/stop the service?
+3. Does my service need to authenticate users?
+
+When a Service is managed by JupyterHub, the Hub will pass the necessary
+information to the Service via the environment variables described above. A
+flexible Service, whether managed by the Hub or not, can make use of these
+same environment variables.
+
+When you run a service that has a url, it will be accessible under a
+`/services/` prefix, such as `https://myhub.horse/services/my-service/`. For
+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`.
+
+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
+
+JupyterHub 0.7 introduces some utilities for using the Hub's authentication
+mechanism to govern access to your service. When a user logs into JupyterHub,
+the Hub sets a **cookie (`jupyterhub-services`)**. The service can use this
+cookie to authenticate requests.
+
+JupyterHub ships with a reference implementation of Hub authentication that
+can be used by services. You may go beyond this reference implementation and
+create custom hub-authenticating clients and services. We describe the process
+below.
+
+The reference, or base, implementation is the [`HubAuth`][HubAuth] class,
+which implements the requests to the Hub.
+
+To use HubAuth, you must set the `.api_token`, either programmatically when constructing the class,
+or via the `JUPYTERHUB_API_TOKEN` environment variable.
+
+Most of the logic for authentication implementation is found in the 
+[`HubAuth.user_for_cookie`][HubAuth.user_for_cookie] 
+and in the 
+[`HubAuth.user_for_token`][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:
+
+  ```python
+  {
+    "name": "username",
+    "groups": ["list", "of", "groups"],
+    "admin": False, # or True
+  }
+  ```
+
+You are then free to use the returned user information to take appropriate
+action.
+
+HubAuth also caches the Hub's response for a number of seconds,
+configurable by the `cookie_cache_max_age` setting (default: five minutes).
+
+### Flask Example
+
+For example, you have a Flask service that returns information about a user.
+JupyterHub's HubAuth class can be used to authenticate requests to the Flask
+service. See the `service-whoami-flask` example in the
+[JupyterHub GitHub repo](https://github.com/jupyterhub/jupyterhub/tree/master/examples/service-whoami-flask)
+for more details.
+
+```python
+from functools import wraps
+import json
+import os
+from urllib.parse import quote
+
+from flask import Flask, redirect, request, Response
+
+from jupyterhub.services.auth import HubAuth
+
+prefix = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '/')
+
+auth = HubAuth(
+    api_token=os.environ['JUPYTERHUB_API_TOKEN'],
+    cookie_cache_max_age=60,
+)
+
+app = Flask(__name__)
+
+
+def authenticated(f):
+    """Decorator for authenticating with the Hub"""
+    @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:
+            return f(user, *args, **kwargs)
+        else:
+            # redirect to login url on failed auth
+            return redirect(auth.login_url + '?next=%s' % quote(request.path))
+    return decorated
+
+
+@app.route(prefix)
+@authenticated
+def whoami(user):
+    return Response(
+        json.dumps(user, indent=1, sort_keys=True),
+        mimetype='application/json',
+        )
+```
+
+
+### Authenticating tornado services with JupyterHub
+
+Since most Jupyter services are written with tornado,
+we include a mixin class, [`HubAuthenticated`][HubAuthenticated],
+for quickly authenticating your own tornado services with JupyterHub.
+
+Tornado's `@web.authenticated` method calls a Handler's `.get_current_user`
+method to identify the user. Mixing in `HubAuthenticated` defines
+`get_current_user` to use HubAuth. If you want to configure the HubAuth
+instance beyond the default, you'll want to define an `initialize` method,
+such as:
+
+```python
+class MyHandler(HubAuthenticated, web.RequestHandler):
+    hub_users = {'inara', 'mal'}
+
+    def initialize(self, hub_auth):
+        self.hub_auth = hub_auth
+
+    @web.authenticated
+    def get(self):
+        ...
+```
+
+
+The HubAuth will automatically load the desired configuration from the Service
+environment variables.
+
+If you want to limit user access, you can whitelist users through either the
+`.hub_users` attribute or `.hub_groups`. These are sets that check against the
+username and user group list, respectively. If a user matches neither the user
+list nor the group list, they will not be allowed access. If both are left
+undefined, then any user will be allowed.
+
+
+### Implementing your own Authentication with JupyterHub
+
+If you don't want to use the reference implementation
+(e.g. you find the implementation a poor fit for your Flask app),
+you can implement authentication via the Hub yourself.
+We recommend looking at the [`HubAuth`][HubAuth] class implementation for reference,
+and taking note of the following process:
+
+1. retrieve the cookie `jupyterhub-services` from the request.
+2. Make an API request `GET /hub/api/authorizations/cookie/jupyterhub-services/cookie-value`,
+    where cookie-value is the url-encoded value of the `jupyterhub-services` cookie.
+    This request must be authenticated with a Hub API token in the `Authorization` header.
+    For example, with [requests][]:
+
+    ```python
+    r = requests.get(
+        '/'.join((["http://127.0.0.1:8081/hub/api",
+                   "authorizations/cookie/jupyterhub-services",
+                   quote(encrypted_cookie, safe=''),
+        ]),
+        headers = {
+            'Authorization' : 'token %s' % api_token,
+        },
+    )
+    r.raise_for_status()
+    user = r.json()
+    ```
+
+3. On success, the reply will be a JSON model describing the user:
+
+   ```json
+   {
+     "name": "inara",
+     "groups": ["serenity", "guild"],
+
+   }
+   ```
+
+An example of using an Externally-Managed Service and authentication is
+in [nbviewer README][nbviewer example] 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 [nbviewer README][nbviewer example]
+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
+[HubAuth.user_for_cookie]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_cookie
+[HubAuth.user_for_token]: ../api/services.auth.html#jupyterhub.services.auth.HubAuth.user_for_token
+[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

@@ -0,0 +1,225 @@
+# Spawners
+
+A [Spawner][] starts each single-user notebook server.
+The Spawner represents an abstract interface to a process,
+and a custom Spawner needs to be able to take three actions:
+
+- start the process
+- poll whether the process is still running
+- stop the process
+
+
+## Examples
+Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Spawners).
+Some examples include:
+
+- [DockerSpawner](https://github.com/jupyterhub/dockerspawner) for spawning user servers in Docker containers
+  * `dockerspawner.DockerSpawner` for spawning identical Docker containers for
+    each users
+  * `dockerspawner.SystemUserSpawner` for spawning Docker containers with an
+    environment and home directory for each users
+  * both `DockerSpawner` and `SystemUserSpawner` also work with Docker Swarm for
+    launching containers on remote machines
+- [SudoSpawner](https://github.com/jupyterhub/sudospawner) enables JupyterHub to
+  run without being root, by spawning an intermediate process via `sudo`
+- [BatchSpawner](https://github.com/jupyterhub/batchspawner) for spawning remote
+  servers using batch systems
+- [RemoteSpawner](https://github.com/zonca/remotespawner) to spawn notebooks
+  and a remote server and tunnel the port via SSH
+
+
+## Spawner control methods
+
+### Spawner.start
+
+`Spawner.start` should start the single-user server for a single user.
+Information about the user can be retrieved from `self.user`,
+an object encapsulating the user's name, authentication, and server info.
+
+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.
+
+Most `Spawner.start` functions will look similar to this example:
+
+```python
+def start(self):
+    self.ip = '127.0.0.1'
+    self.port = random_port()
+    # get environment variables,
+    # several of which are required for configuring the single-user server
+    env = self.get_env()
+    cmd = []
+    # get jupyterhub command to run,
+    # typically ['jupyterhub-singleuser']
+    cmd.extend(self.cmd)
+    cmd.extend(self.get_args())
+
+    yield self._actually_start_server_somehow(cmd, env)
+    return (self.ip, self.port)
+```
+
+When `Spawner.start` returns, the single-user server process should actually be running,
+not just requested. JupyterHub can handle `Spawner.start` being very slow
+(such as PBS-style batch queues, or instantiating whole AWS instances)
+via relaxing the `Spawner.start_timeout` config value.
+
+### Spawner.poll
+
+`Spawner.poll` should check if the spawner is still running.
+It should return `None` if it is still running,
+and an integer exit status, otherwise.
+
+For the local process case, `Spawner.poll` uses `os.kill(PID, 0)`
+to check if the local process is still running.
+
+### Spawner.stop
+
+`Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
+
+
+## Spawner state
+
+JupyterHub should be able to stop and restart without tearing down
+single-user notebook servers. To do this task, a Spawner may need to persist
+some information that can be restored later.
+A JSON-able dictionary of state can be used to store persisted information.
+
+Unlike start, stop, and poll methods, the state methods must not be coroutines.
+
+For the single-process case, the Spawner state is only the process ID of the server:
+
+```python
+def get_state(self):
+    """get the current state"""
+    state = super().get_state()
+    if self.pid:
+        state['pid'] = self.pid
+    return state
+
+def load_state(self, state):
+    """load state from the database"""
+    super().load_state(state)
+    if 'pid' in state:
+        self.pid = state['pid']
+
+def clear_state(self):
+    """clear any state (called after shutdown)"""
+    super().clear_state()
+    self.pid = 0
+```
+
+
+## Spawner options form
+
+(new in 0.4)
+
+Some deployments may want to offer options to users to influence how their servers are started.
+This may include cluster-based deployments, where users specify what resources should be available,
+or docker-based deployments where users can select from a list of base images.
+
+This feature is enabled by setting `Spawner.options_form`, which is an HTML form snippet
+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)
+
+If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
+
+See [this example](https://github.com/jupyterhub/jupyterhub/blob/master/examples/spawn-form/jupyterhub_config.py) for a form that allows custom CLI args for the local spawner.
+
+### `Spawner.options_from_form`
+
+Options from this form will always be a dictionary of lists of strings, e.g.:
+
+```python
+{
+  'integer': ['5'],
+  'text': ['some text'],
+  'select': ['a', 'b'],
+}
+```
+
+When `formdata` arrives, it is passed through `Spawner.options_from_form(formdata)`,
+which is a method to turn the form data into the correct structure.
+This method must return a dictionary, and is meant to interpret the lists-of-strings into the correct types. For example, the `options_from_form` for the above form would look like:
+
+```python
+def options_from_form(self, formdata):
+    options = {}
+    options['integer'] = int(formdata['integer'][0]) # single integer value
+    options['text'] = formdata['text'][0] # single string value
+    options['select'] = formdata['select'] # list already correct
+    options['notinform'] = 'extra info' # not in the form at all
+    return options
+```
+
+which would return:
+
+```python
+{
+  'integer': 5,
+  'text': 'some text',
+  'select': ['a', 'b'],
+  'notinform': 'extra info',
+}
+```
+
+When `Spawner.start` is called, this dictionary is accessible as `self.user_options`.
+
+
+[Spawner]: https://github.com/jupyterhub/jupyterhub/blob/master/jupyterhub/spawner.py
+
+## Writing a custom spawner
+
+If you are interested in building a custom spawner, you can read [this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/spawners.html).
+
+## Spawners, resource limits, and guarantees (Optional)
+
+Some spawners of the single-user notebook servers allow setting limits or
+guarantees on resources, such as CPU and memory. To provide a consistent
+experience for sysadmins and users, we provide a standard way to set and
+discover these resource limits and guarantees, such as for memory and CPU.
+For the limits and guarantees to be useful, **the spawner must implement
+support for them**. For example, LocalProcessSpawner, the default
+spawner, does not support limits and guarantees. One of the spawners
+that supports limits and guarantees is the `systemdspawner`.
+
+
+### Memory Limits & Guarantees
+
+`c.Spawner.mem_limit`: A **limit** specifies the *maximum amount of memory*
+that may be allocated, though there is no promise that the maximum amount will
+be available. In supported spawners, you can set `c.Spawner.mem_limit` to
+limit the total amount of memory that a single-user notebook server can
+allocate. Attempting to use more memory than this limit will cause errors. The
+single-user notebook server can discover its own memory limit by looking at
+the environment variable `MEM_LIMIT`, which is specified in absolute bytes.
+
+`c.Spawner.mem_guarantee`: Sometimes, a **guarantee** of a *minumum amount of
+memory* is desirable. In this case, you can set `c.Spawner.mem_guarantee` to
+to provide a guarantee that at minimum this much memory will always be
+available for the single-user notebook server to use. The environment variable
+`MEM_GUARANTEE` will also be set in the single-user notebook server.
+
+**The spawner's underlying system or cluster is responsible for enforcing these
+limits and providing these guarantees.** If these values are set to `None`, no
+limits or guarantees are provided, and no environment values are set.
+
+### CPU Limits & Guarantees
+
+`c.Spawner.cpu_limit`: In supported spawners, you can set
+`c.Spawner.cpu_limit` to limit the total number of cpu-cores that a
+single-user notebook server can use. These can be fractional - `0.5` means 50%
+of one CPU core, `4.0` is 4 cpu-cores, etc. This value is also set in the
+single-user notebook server's environment variable `CPU_LIMIT`. The limit does
+not claim that you will be able to use all the CPU up to your limit as other
+higher priority applications might be taking up CPU.
+
+`c.Spawner.cpu_guarantee`: You can set `c.Spawner.cpu_guarantee` to provide a
+guarantee for CPU usage. The environment variable `CPU_GUARANTEE` will be set
+in the single-user notebook server when a guarantee is being provided.
+
+**The spawner's underlying system or cluster is responsible for enforcing these
+limits and providing these guarantees.** If these values are set to `None`, no
+limits or guarantees are provided, and no environment values are set.

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/templates.md

@@ -0,0 +1,93 @@
+# Working with templates and UI
+
+The pages of the JupyterHub application are generated from
+[Jinja](http://jinja.pocoo.org/) templates.  These allow the header, for
+example, to be defined once and incorporated into all pages.  By providing
+your own templates, you can have complete control over JupyterHub's
+appearance.
+
+## Custom Templates
+
+JupyterHub will look for custom templates in all of the paths in the
+`JupyterHub.template_paths` configuration option, falling back on the
+[default templates](https://github.com/jupyterhub/jupyterhub/tree/master/share/jupyterhub/templates)
+if no custom template with that name is found. This fallback
+behavior is new in version 0.9; previous versions searched only those paths
+explicitly included in `template_paths`. You may override as many
+or as few templates as you desire.
+
+## Extending Templates
+
+Jinja provides a mechanism to [extend templates](http://jinja.pocoo.org/docs/2.10/templates/#template-inheritance).
+A base template can define a `block`, and child templates can replace or
+supplement the material in the block.  The 
+[JupyterHub templates](https://github.com/jupyterhub/jupyterhub/tree/master/share/jupyterhub/templates)
+make extensive use of blocks, which allows you to customize parts of the
+interface easily.
+
+In general, a child template can extend a base template, `base.html`, by beginning with:
+
+```html
+{% extends "base.html" %}
+```
+
+This works, unless you are trying to extend the default template for the same
+file name.  Starting in version 0.9, you may refer to the base file with a
+`templates/` prefix.  Thus, if you are writing a custom `base.html`, start the
+file with this block:
+
+```html
+{% extends "templates/base.html" %}
+```
+
+By defining `block`s with same name as in the base template, child templates
+can replace those sections with custom content.  The content from the base
+template can be included with the `{{ super() }}` directive.
+
+### Example
+
+To add an additional message to the spawn-pending page, below the existing
+text about the server starting up, place this content in a file named
+`spawn_pending.html` in a directory included in the
+`JupyterHub.template_paths` configuration option.
+
+```html
+{% extends "templates/spawn_pending.html" %}
+
+{% block message %}
+{{ super() }}
+<p>Patience is a virtue.</p>
+{% endblock %}
+```
+
+## Page Announcements
+
+To add announcements to be displayed on a page, you have two options:
+
+- Extend the page templates as described above
+- Use configuration variables
+
+### Announcement Configuration Variables
+
+If you set the configuration variable `JupyterHub.template_vars =
+{'announcement': 'some_text}`, the given `some_text` will be placed on
+the top of all pages.  The more specific variables
+`announcement_login`, `announcement_spawn`, `announcement_home`, and
+`announcement_logout` are more specific and only show on their
+respective pages (overriding the global `announcement` variable).
+Note that changing these varables require a restart, unlike direct
+template extension.
+
+You can get the same effect by extending templates, which allows you
+to update the messages without restarting.  Set
+`c.JupyterHub.template_paths` as mentioned above, and then create a
+template (for example, `login.html`) with:
+
+```html
+{% extends "templates/login.html" %}
+{% set announcement = 'some message' %}
+```
+
+Extending `page.html` puts the message on all pages, but note that
+extending `page.html` take precedence over an extension of a specific
+page (unlike the variable-based approach above).

docs/source/reference/upgrading.md

@@ -0,0 +1,98 @@
+# Upgrading JupyterHub and its database
+
+From time to time, you may wish to upgrade JupyterHub to take advantage
+of new releases. Much of this process is automated using scripts,
+such as those generated by alembic for database upgrades. Whether you
+are using the default SQLite database or an RDBMS, such as PostgreSQL or
+MySQL, the process follows similar steps.
+
+**Before upgrading a JupyterHub deployment**, it's critical to backup your data
+and configurations before shutting down the JupyterHub process and server.
+
+## Note about upgrading the SQLite database
+
+When used in production systems, SQLite has some disadvantages when it
+comes to upgrading JupyterHub. These are:
+
+- `upgrade-db` may not work, and you may need to start with a fresh database
+- `downgrade-db` **will not** work if you want to rollback to an earlier
+  version, so backup the `jupyterhub.sqlite` file before upgrading
+
+## The upgrade process
+
+Five fundamental process steps are needed when upgrading JupyterHub and its
+database:
+
+1. Backup JupyterHub database
+2. Backup JupyterHub configuration file
+3. Shutdown the Hub
+4. Upgrade JupyterHub
+5. Upgrade the database using run `jupyterhub upgrade-db`
+
+Let's take a closer look at each step in the upgrade process as well as some
+additional information about JupyterHub databases.
+
+### 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.
+
+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
+
+Additionally, backing 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. This gives users the opportunity to finish any outstanding
+work in process.
+
+Next, shutdown the JupyterHub service.
+
+### Upgrade JupyterHub
+
+Follow directions that correspond to your package manager, `pip` or `conda`,
+for the new JupyterHub release. These directions will guide you to the
+specific command. In general, `pip install -U jupyterhub` or
+`conda upgrade jupyterhub`
+
+### Upgrade JupyterHub databases
+
+To run the upgrade process for JupyterHub databases, enter:
+
+```
+jupyterhub upgrade-db
+```
+
+## Upgrade checklist
+
+1. Backup JupyterHub database:
+    - `jupyterhub.sqlite` when using the default sqlite database
+    - Your JupyterHub database when using an RDBMS 
+2. Backup 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`

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/spawners.md

@@ -1,160 +0,0 @@
-# Writing a custom Spawner
-
-A [Spawner][] starts each single-user notebook server.
-The Spawner represents an abstract interface to a process,
-and a custom Spawner needs to be able to take three actions:
-
-- start the process
-- poll whether the process is still running
-- stop the process
-
-## Examples
-Custom Spawners for JupyterHub can be found on the [JupyterHub wiki](https://github.com/jupyter/jupyterhub/wiki/Spawners). Some examples include:
-- [DockerSpawner](https://github.com/jupyter/dockerspawner) for spawning user servers in Docker containers
-  * dockerspawner.DockerSpawner for spawning identical Docker containers for
-    each users
-  * dockerspawner.SystemUserSpawner for spawning Docker containers with an
-    environment and home directory for each users
-- [SudoSpawner](https://github.com/jupyter/sudospawner) enables JupyterHub to
-  run without being root, by spawning an intermediate process via `sudo`
-- [BatchSpawner](https://github.com/mbmilligan/batchspawner) for spawning remote
-  servers using batch systems
-- [RemoteSpawner](https://github.com/zonca/remotespawner) to spawn notebooks
-  and a remote server and tunnel the port via SSH
-- [SwarmSpawner](https://github.com/compmodels/jupyterhub/blob/master/swarmspawner.py)
-  for spawning containers using Docker Swarm
-
-## Spawner control methods
-
-### Spawner.start
-
-`Spawner.start` should start the single-user server for a single user.
-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`.
-
-**NOTE:** When writing coroutines, *never* `yield` in between a database change and a commit.
-
-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
-    yield self._actually_start_server_somehow()
-```
-
-When `Spawner.start` returns, the single-user server process should actually be running,
-not just requested. JupyterHub can handle `Spawner.start` being very slow
-(such as PBS-style batch queues, or instantiating whole AWS instances)
-via relaxing the `Spawner.start_timeout` config value.
-
-### Spawner.poll
-
-`Spawner.poll` should check if the spawner is still running.
-It should return `None` if it is still running,
-and an integer exit status, otherwise.
-
-For the local process case, `Spawner.poll` uses `os.kill(PID, 0)`
-to check if the local process is still running.
-
-
-### Spawner.stop
-
-`Spawner.stop` should stop the process. It must be a tornado coroutine, which should return when the process has finished exiting.
-
-## Spawner state
-
-JupyterHub should be able to stop and restart without tearing down
-single-user notebook servers. To do this task, a Spawner may need to persist
-some information that can be restored later.
-A JSON-able dictionary of state can be used to store persisted information.
-
-Unlike start, stop, and poll methods, the state methods must not be coroutines.
-
-For the single-process case, the Spawner state is only the process ID of the server:
-
-```python
-def get_state(self):
-    """get the current state"""
-    state = super().get_state()
-    if self.pid:
-        state['pid'] = self.pid
-    return state
-
-def load_state(self, state):
-    """load state from the database"""
-    super().load_state(state)
-    if 'pid' in state:
-        self.pid = state['pid']
-
-def clear_state(self):
-    """clear any state (called after shutdown)"""
-    super().clear_state()
-    self.pid = 0
-```
-
-## Spawner options form
-
-(new in 0.4)
-
-Some deployments may want to offer options to users to influence how their servers are started.
-This may include cluster-based deployments, where users specify what resources should be available,
-or docker-based deployments where users can select from a list of base images.
-
-This feature is enabled by setting `Spawner.options_form`, which is an HTML form snippet
-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)
-
-If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
-
-See [this example](https://github.com/jupyter/jupyterhub/blob/master/examples/spawn-form/jupyterhub_config.py) for a form that allows custom CLI args for the local spawner.
-
-
-### `Spawner.options_from_form`
-
-Options from this form will always be a dictionary of lists of strings, e.g.:
-
-```python
-{
-  'integer': ['5'],
-  'text': ['some text'],
-  'select': ['a', 'b'],
-}
-```
-
-When `formdata` arrives, it is passed through `Spawner.options_from_form(formdata)`,
-which is a method to turn the form data into the correct structure.
-This method must return a dictionary, and is meant to interpret the lists-of-strings into the correct types. For example, the `options_from_form` for the above form would look like:
-
-```python
-def options_from_form(self, formdata):
-    options = {}
-    options['integer'] = int(formdata['integer'][0]) # single integer value
-    options['text'] = formdata['text'][0] # single string value
-    options['select'] = formdata['select'] # list already correct
-    options['notinform'] = 'extra info' # not in the form at all
-    return options
-```
-
-which would return:
-
-```python
-{
-  'integer': 5,
-  'text': 'some text',
-  'select': ['a', 'b'],
-  'notinform': 'extra info',
-}
-```
-
-When `Spawner.spawn` is called, this dictionary is accessible as `self.user_options`.
-
-
-
-[Spawner]: https://github.com/jupyter/jupyterhub/blob/master/jupyterhub/spawner.py

docs/source/spelling_wordlist.txt

@@ -0,0 +1,213 @@
+admin
+Afterwards
+alchemyst
+alope
+api
+API
+apps
+args
+asctime
+auth
+authenticator
+Authenticator
+authenticators
+Authenticators
+Autograde
+autograde
+autogradeapp
+autograded
+Autograded
+autograder
+Autograder
+autograding
+backends
+Bitdiddle
+bugfix
+Bugfixes
+bugtracker
+Carreau
+Changelog
+changelog
+checksum
+checksums
+cmd
+cogsci
+conda
+config
+coroutine
+coroutines
+crt
+customizable
+datefmt
+decrypted
+dev
+DockerSpawner
+dockerspawner
+dropdown
+duedate
+Duedate
+ellachao
+ellisonbg
+entrypoint
+env
+Filenames
+filesystem
+formatters
+formdata
+formgrade
+formgrader
+gif
+GitHub
+Gradebook
+gradebook
+Granger
+hardcoded
+hOlle
+Homebrew
+html
+http
+https
+hubapi
+Indices
+IFramed
+inline
+iopub
+ip
+ipynb
+IPython
+ischurov
+ivanslapnicar
+jdfreder
+jhamrick
+jklymak
+jonathanmorgan
+joschu
+JUPYTER
+Jupyter
+jupyter
+jupyterhub
+Kerberos
+kerberos
+letsencrypt
+lgpage
+linkcheck
+linux
+localhost
+logfile
+login
+logins
+logout
+lookup
+lphk
+mandli
+Marr
+mathjax
+matplotlib
+metadata
+mikebolt
+minrk
+Mitigations
+mixin
+Mixin
+multi
+multiuser
+namespace
+nbconvert
+nbgrader
+neuroscience
+nginx
+np
+npm
+oauth
+OAuth
+oauthenticator
+ok
+olgabot
+osx
+PAM
+phantomjs
+Phantomjs
+plugin
+plugins
+Popen
+positionally
+postgres
+pregenerated
+prepend
+prepopulate
+preprocessor
+Preprocessor
+prev
+Programmatically
+programmatically
+ps
+py
+Qualys
+quickstart
+readonly
+redSlug
+reinstall
+resize
+rst
+runtime
+rw
+sandboxed
+sansary
+singleuser
+smeylan
+spawner
+Spawner
+spawners
+Spawners
+spellcheck
+SQL
+sqlite
+startup
+statsd
+stdin
+stdout
+stoppped
+subclasses
+subcommand
+subdomain
+subdomains
+Subdomains
+suchow
+suprocesses
+svurens
+sys
+SystemUserSpawner
+systemwide
+tasilb
+teardown
+threadsafe
+timestamp
+timestamps
+TLD
+todo
+toolbar
+traitlets
+travis
+tuples
+undeletable
+unicode
+uninstall
+UNIX
+unix
+untracked
+untrusted
+url
+username
+usernames
+utcnow
+utils
+vinaykola
+virtualenv
+whitelist
+whitespace
+wildcard
+Wildcards
+willingc
+wordlist
+Workflow
+workflow

docs/source/troubleshooting.md

@@ -1,11 +1,339 @@
 # Troubleshooting
 
-This document is under active development.
+When troubleshooting, you may see unexpected behaviors or receive an error
+message. This section provide links for identifying the cause of the
+problem and how to resolve it.
 
-## Networking
+[*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?
+- JupyterHub Docker container not accessible at localhost
 
-If JupyterHub proxy fails to start:
+[*Errors*](#errors)
+- 500 error after spawning my single-user server
+
+[*How do I...?*](#how-do-i)
+- Use a chained SSL certificate
+- Install JupyterHub without a network connection
+- I want access to the whole filesystem, but still default users to their home directory
+- 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)
+
+## Behavior
+
+### JupyterHub proxy fails to start
+
+If you have tried to start the JupyterHub proxy and it fails to start:
 
 - check if the JupyterHub IP configuration setting is
   ``c.JupyterHub.ip = '*'``; if it is, try ``c.JupyterHub.ip = ''``
-- Try starting with ``jupyterhub --ip=0.0.0.0``
+- 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.
+To avoid this, specify sudospawner's absolute path. For example, start
+jupyterhub with:
+
+    jupyterhub --SudoSpawner.sudospawner_path='/absolute/path/to/sudospawner'
+
+or add:
+
+    c.SudoSpawner.sudospawner_path = '/absolute/path/to/sudospawner'
+
+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).
+
+### JupyterHub Docker container not accessible at localhost
+
+Even though the command to start your Docker container exposes port 8000 
+(`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub`), 
+it is possible that the IP address itself is not accessible/visible. As a result 
+when you try http://localhost:8000 in your browser, you are unable to connect 
+even though the container is running properly. One workaround is to explicitly 
+tell Jupyterhub to start at `0.0.0.0` which is visible to everyone. Try this 
+command: 
+`docker run -p 8000:8000 -d --name jupyterhub jupyterhub/jupyterhub jupyterhub --ip 0.0.0.0 --port 8000`
+
+
+## Errors
+
+### 500 error after spawning my single-user server
+
+You receive a 500 error when accessing the URL `/user/<your_name>/...`.
+This is often seen when your single-user server cannot verify your user cookie
+with the Hub.
+
+There are two likely reasons for this:
+
+1. The single-user server cannot connect to the Hub's API (networking
+   configuration problems)
+2. The single-user server cannot *authenticate* its requests (invalid token)
+
+#### Symptoms
+
+The main symptom is a failure to load *any* page served by the single-user
+server, met with a 500 error. This is typically the first page at `/user/<your_name>`
+after logging in or clicking "Start my server". When a single-user notebook server
+receives a request, the notebook server makes an API request to the Hub to
+check if the cookie corresponds to the right user. This request is logged.
+
+If everything is working, the response logged will be similar to this:
+
+```
+200 GET /hub/api/authorizations/cookie/jupyterhub-token-name/[secret] (@10.0.1.4) 6.10ms
+```
+
+You should see a similar 200 message, as above, in the Hub log when you first
+visit your single-user notebook server. If you don't see this message in the log, it
+may mean that your single-user notebook server isn't connecting to your Hub.
+
+If you see 403 (forbidden) like this, it's a token problem:
+
+```
+403 GET /hub/api/authorizations/cookie/jupyterhub-token-name/[secret] (@10.0.1.4) 4.14ms
+```
+
+Check the logs of the single-user notebook server, which may have more detailed
+information on the cause.
+
+#### Causes and resolutions
+
+##### No authorization request
+
+If you make an API request and it is not received by the server, you likely
+have a network configuration issue. Often, this happens when the Hub is only
+listening on 127.0.0.1 (default) and the single-user servers are not on the
+same 'machine' (can be physically remote, or in a docker container or VM). The
+fix for this case is to make sure that `c.JupyterHub.hub_ip` is an address
+that all single-user servers can connect to, e.g.:
+
+```python
+c.JupyterHub.hub_ip = '10.0.0.1'
+```
+
+##### 403 GET /hub/api/authorizations/cookie
+
+If you receive a 403 error, the API token for the single-user server is likely
+invalid. Commonly, the 403 error is caused by resetting the JupyterHub
+database (either removing jupyterhub.sqlite or some other action) while
+leaving single-user servers running. This happens most frequently when using
+DockerSpawner, because Docker's default behavior is to stop/start containers
+which resets the JupyterHub database, rather than destroying and recreating
+the container every time. This means that the same API token is used by the
+server for its whole life, until the container is rebuilt.
+
+The fix for this Docker case is to remove any Docker containers seeing this
+issue (typically all containers created before a certain point in time):
+
+    docker rm -f jupyter-name
+
+After this, when you start your server via JupyterHub, it will build a
+new container. If this was the underlying cause of the issue, you should see
+your server again.
+
+
+## How do I...?
+
+### Use a chained SSL certificate
+
+Some certificate providers, i.e. Entrust, may provide you with a chained
+certificate that contains multiple files. If you are using a chained
+certificate you will need to concatenate the individual files by appending the
+chain cert and root cert to your host cert:
+
+    cat your_host.crt chain.crt root.crt > your_host-chained.crt
+
+You would then set in your `jupyterhub_config.py` file the `ssl_key` and
+`ssl_cert` as follows:
+
+    c.JupyterHub.ssl_cert = your_host-chained.crt
+    c.JupyterHub.ssl_key = your_host.key
+
+
+#### Example
+
+Your certificate provider gives you the following files: `example_host.crt`,
+`Entrust_L1Kroot.txt` and `Entrust_Root.txt`.
+
+Concatenate the files appending the chain cert and root cert to your host cert:
+
+    cat example_host.crt Entrust_L1Kroot.txt Entrust_Root.txt > example_host-chained.crt
+
+You would then use the `example_host-chained.crt` as the value for
+JupyterHub's `ssl_cert`. You may pass this value as a command line option
+when starting JupyterHub or more conveniently set the `ssl_cert` variable in
+JupyterHub's configuration file, `jupyterhub_config.py`. In `jupyterhub_config.py`,
+set:
+
+    c.JupyterHub.ssl_cert = /path/to/example_host-chained.crt
+    c.JupyterHub.ssl_key = /path/to/example_host.key
+
+where `ssl_cert` is example-chained.crt and ssl_key to your private key.
+
+Then restart JupyterHub.
+
+See also [JupyterHub SSL encryption](getting-started.md#ssl-encryption).
+
+### Install JupyterHub without a network connection
+
+Both conda and pip can be used without a network connection. You can make your
+own repository (directory) of conda packages and/or wheels, and then install
+from there instead of the internet.
+
+For instance, you can install JupyterHub with pip and configurable-http-proxy
+with npmbox:
+
+    pip wheel jupyterhub
+    npmbox configurable-http-proxy
+
+### I want access to the whole filesystem, but still default users to their home directory
+
+Setting the following in `jupyterhub_config.py` will configure access to
+the entire filesystem and set the default to the user's home directory.
+
+    c.Spawner.notebook_dir = '/'
+    c.Spawner.default_url = '/home/%U' # %U will be replaced with the username
+
+### How do I increase the number of pySpark executors on YARN?
+
+From the command line, pySpark executors can be configured using a command
+similar to this one:
+
+    pyspark --total-executor-cores 2 --executor-memory 1G
+
+[Cloudera documentation for configuring spark on YARN applications](https://www.cloudera.com/documentation/enterprise/latest/topics/cdh_ig_running_spark_on_yarn.html#spark_on_yarn_config_apps)
+provides additional information. The [pySpark configuration documentation](https://spark.apache.org/docs/0.9.0/configuration.html)
+is also helpful for programmatic configuration examples.
+
+### How do I use JupyterLab's prerelease version with JupyterHub?
+
+While JupyterLab is still under active development, we have had users
+ask about how to try out JupyterLab with JupyterHub.
+
+You need to install and enable the JupyterLab extension system-wide,
+then you can change the default URL to `/lab`.
+
+For instance:
+
+    pip install jupyterlab
+    jupyter serverextension enable --py jupyterlab --sys-prefix
+
+The important thing is that jupyterlab is installed and enabled in the
+single-user notebook server environment. For system users, this means
+system-wide, as indicated above. For Docker containers, it means inside
+the single-user docker image, etc.
+
+In `jupyterhub_config.py`, configure the Spawner to tell the single-user
+notebook servers to default to JupyterLab:
+
+    c.Spawner.default_url = '/lab'
+
+### How do I set up JupyterHub for a workshop (when users are not known ahead of time)?
+
+1. Set up JupyterHub using OAuthenticator for GitHub authentication
+2. Configure whitelist to be an empty list in` jupyterhub_config.py`
+3. Configure admin list to have workshop leaders be listed with administrator privileges.
+
+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,
+versions, and system information that may be helpful when troubleshooting
+a JupyterHub deployment. The commands are:
+
+- System and deployment information
+
+```bash
+jupyter troubleshooting
+```
+
+- Kernel information
+
+```bash
+jupyter kernelspec list
+```
+
+- Debug logs when running JupyterHub
+
+```bash
+jupyterhub --debug
+```
+
+### Toree integration with HDFS rack awareness script
+
+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
+16/11/29 16:24:20 WARN ScriptBasedMapping: Exception running /etc/hadoop/conf/topology_script.py some.ip.address
+ExitCodeException exitCode=1:   File "/etc/hadoop/conf/topology_script.py", line 63
+    print rack
+             ^
+SyntaxError: Missing parentheses in call to 'print'
+
+    at `org.apache.hadoop.util.Shell.runCommand(Shell.java:576)`
+```
+
+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
+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/sphinxext/autodoc_traits.py

@@ -0,0 +1,55 @@
+"""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,133 @@
+# 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. 
+
+Similarly, there may be cases where you would like to clean up after a spawner stops.
+You may implement a `post_stop_hook` that is always executed after the spawner stops.
+
+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,34 @@
+# Example for a Spawner.pre_spawn_hook
+# create a directory for the user before the spawner starts
+
+import os
+import shutil
+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
+        # ...
+
+def clean_dir_hook(spawner):
+    username = spawner.user.name # get the username
+    temp_path = os.path.join('/volumes/jupyterhub', username, 'temp')
+    if os.path.exists(temp_path) and os.path.isdir(temp_path):
+        shutil.rmtree(temp_path)
+
+# attach the hook functions to the spawner
+c.Spawner.pre_spawn_hook = create_dir_hook
+c.Spawner.post_stop_hook = clean_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/README.md

@@ -0,0 +1,41 @@
+# `cull-idle` Example
+
+The `cull_idle_servers.py` file provides a script to cull and shut down idle
+single-user notebook servers. This script is used when `cull-idle` is run as
+a Service or when it is run manually as a standalone script.
+
+
+## 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': 'python3 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 managed by the Hub.
+
+## Run `cull-idle` manually as a standalone script
+
+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=`jupyterhub token`
+    python3 cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+```

examples/cull-idle/cull_idle_servers.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 """script to monitor and cull idle single-user servers
 
 Caveats:
@@ -9,71 +9,355 @@ so cull timeout should be greater than the sum of:
 - single-user websocket ping interval (default: 30s)
 - JupyterHub.last_activity_interval (default: 5 minutes)
 
-Generate an API token and store it in `JPY_API_TOKEN`:
+You can run this as a service managed by JupyterHub with this in your config::
 
-    export JPY_API_TOKEN=`jupyterhub token`
-    python cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub]
+
+    c.JupyterHub.services = [
+        {
+            'name': 'cull-idle',
+            'admin': True,
+            'command': 'python3 cull_idle_servers.py --timeout=3600'.split(),
+        }
+    ]
+
+Or run it manually by generating an API token and storing it in `JUPYTERHUB_API_TOKEN`:
+
+    export JUPYTERHUB_API_TOKEN=`jupyterhub token`
+    python3 cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+
+This script uses the same ``--timeout`` and ``--max-age`` values for
+culling users and users' servers.  If you want a different value for
+users and servers, you should add this script to the services list
+twice, just with different ``name``s, different values, and one with
+the ``--cull-users`` option.
 """
 
-import datetime
+from datetime import datetime, timezone
+from functools import partial
 import json
 import os
 
-from dateutil.parser import parse as parse_date
+try:
+    from urllib.parse import quote
+except ImportError:
+    from urllib import quote
 
-from tornado.gen import coroutine
+import dateutil.parser
+
+from tornado.gen import coroutine, multi
+from tornado.locks import Semaphore
 from tornado.log import app_log
 from tornado.httpclient import AsyncHTTPClient, HTTPRequest
 from tornado.ioloop import IOLoop, PeriodicCallback
 from tornado.options import define, options, parse_command_line
 
 
+def parse_date(date_string):
+    """Parse a timestamp
+
+    If it doesn't have a timezone, assume utc
+
+    Returned datetime object will always be timezone-aware
+    """
+    dt = dateutil.parser.parse(date_string)
+    if not dt.tzinfo:
+        # assume naïve timestamps are UTC
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def format_td(td):
+    """
+    Nicely format a timedelta object
+
+    as HH:MM:SS
+    """
+    if td is None:
+        return "unknown"
+    if isinstance(td, str):
+        return td
+    seconds = int(td.total_seconds())
+    h = seconds // 3600
+    seconds = seconds % 3600
+    m = seconds // 60
+    seconds = seconds % 60
+    return "{h:02}:{m:02}:{seconds:02}".format(h=h, m=m, seconds=seconds)
+
+
 @coroutine
-def cull_idle(url, api_token, timeout):
-    """cull idle single-user servers"""
+def cull_idle(url, api_token, inactive_limit, cull_users=False, max_age=0, concurrency=10):
+    """Shutdown idle single-user servers
+
+    If cull_users, inactive *users* will be deleted as well.
+    """
     auth_header = {
-            'Authorization': 'token %s' % api_token
-        }
-    req = HTTPRequest(url=url + '/api/users',
+        'Authorization': 'token %s' % api_token,
+    }
+    req = HTTPRequest(
+        url=url + '/users',
         headers=auth_header,
     )
-    now = datetime.datetime.utcnow()
-    cull_limit = now - datetime.timedelta(seconds=timeout)
+    now = datetime.now(timezone.utc)
     client = AsyncHTTPClient()
-    resp = yield client.fetch(req)
+
+    if concurrency:
+        semaphore = Semaphore(concurrency)
+        @coroutine
+        def fetch(req):
+            """client.fetch wrapped in a semaphore to limit concurrency"""
+            yield semaphore.acquire()
+            try:
+                return (yield client.fetch(req))
+            finally:
+                yield semaphore.release()
+    else:
+        fetch = client.fetch
+
+    resp = yield 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)
-            req = HTTPRequest(url=url + '/api/users/%s/server' % user['name'],
-                method='DELETE',
-                headers=auth_header,
+
+    @coroutine
+    def handle_server(user, server_name, server):
+        """Handle (maybe) culling a single server
+
+        Returns True if server is now stopped (user removable),
+        False otherwise.
+        """
+        log_name = user['name']
+        if server_name:
+            log_name = '%s/%s' % (user['name'], server_name)
+        if server.get('pending'):
+            app_log.warning(
+                "Not culling server %s with pending %s",
+                log_name, server['pending'])
+            return False
+
+        # jupyterhub < 0.9 defined 'server.url' once the server was ready
+        # as an *implicit* signal that the server was ready.
+        # 0.9 adds a dedicated, explicit 'ready' field.
+        # By current (0.9) definitions, servers that have no pending
+        # events and are not ready shouldn't be in the model,
+        # but let's check just to be safe.
+
+        if not server.get('ready', bool(server['url'])):
+            app_log.warning(
+                "Not culling not-ready not-pending server %s: %s",
+                log_name, server)
+            return False
+
+        if server.get('started'):
+            age = now - parse_date(server['started'])
+        else:
+            # started may be undefined on jupyterhub < 0.9
+            age = None
+
+        # check last activity
+        # last_activity can be None in 0.9
+        if server['last_activity']:
+            inactive = now - parse_date(server['last_activity'])
+        else:
+            # no activity yet, use start date
+            # last_activity may be None with jupyterhub 0.9,
+            # which introduces the 'started' field which is never None
+            # for running servers
+            inactive = age
+
+        should_cull = (inactive is not None and
+                       inactive.total_seconds() >= inactive_limit)
+        if should_cull:
+            app_log.info(
+                "Culling server %s (inactive for %s)",
+                log_name, format_td(inactive))
+
+        if max_age and not should_cull:
+            # only check started if max_age is specified
+            # so that we can still be compatible with jupyterhub 0.8
+            # which doesn't define the 'started' field
+            if age is not None and age.total_seconds() >= max_age:
+                app_log.info(
+                    "Culling server %s (age: %s, inactive for %s)",
+                    log_name, format_td(age), format_td(inactive))
+                should_cull = True
+
+        if not should_cull:
+            app_log.debug(
+                "Not culling server %s (age: %s, inactive for %s)",
+                log_name, format_td(age), format_td(inactive))
+            return False
+
+        if server_name:
+            # culling a named server
+            delete_url = url + "/users/%s/servers/%s" % (
+                quote(user['name']), quote(server['name'])
             )
-            futures.append((user['name'], client.fetch(req)))
-        elif user['server'] and last_activity > cull_limit:
-            app_log.debug("Not culling %s (active since %s)", user['name'], last_activity)
-    
+        else:
+            delete_url = url + '/users/%s/server' % quote(user['name'])
+
+        req = HTTPRequest(
+            url=delete_url, method='DELETE', headers=auth_header,
+        )
+        resp = yield fetch(req)
+        if resp.code == 202:
+            app_log.warning(
+                "Server %s is slow to stop",
+                log_name,
+            )
+            # return False to prevent culling user with pending shutdowns
+            return False
+        return True
+
+    @coroutine
+    def handle_user(user):
+        """Handle one user.
+
+        Create a list of their servers, and async exec them.  Wait for
+        that to be done, and if all servers are stopped, possibly cull
+        the user.
+        """
+        # shutdown servers first.
+        # Hub doesn't allow deleting users with running servers.
+        # jupyterhub 0.9 always provides a 'servers' model.
+        # 0.8 only does this when named servers are enabled.
+        if 'servers' in user:
+            servers = user['servers']
+        else:
+            # jupyterhub < 0.9 without named servers enabled.
+            # create servers dict with one entry for the default server
+            # from the user model.
+            # only if the server is running.
+            servers = {}
+            if user['server']:
+                servers[''] = {
+                    'last_activity': user['last_activity'],
+                    'pending': user['pending'],
+                    'url': user['server'],
+                }
+        server_futures = [
+            handle_server(user, server_name, server)
+            for server_name, server in servers.items()
+        ]
+        results = yield multi(server_futures)
+        if not cull_users:
+            return
+        # some servers are still running, cannot cull users
+        still_alive = len(results) - sum(results)
+        if still_alive:
+            app_log.debug(
+                "Not culling user %s with %i servers still alive",
+                user['name'], still_alive)
+            return False
+
+        should_cull = False
+        if user.get('created'):
+            age = now - parse_date(user['created'])
+        else:
+            # created may be undefined on jupyterhub < 0.9
+            age = None
+
+        # check last activity
+        # last_activity can be None in 0.9
+        if user['last_activity']:
+            inactive = now - parse_date(user['last_activity'])
+        else:
+            # no activity yet, use start date
+            # last_activity may be None with jupyterhub 0.9,
+            # which introduces the 'created' field which is never None
+            inactive = age
+
+        should_cull = (inactive is not None and
+                       inactive.total_seconds() >= inactive_limit)
+        if should_cull:
+            app_log.info(
+                "Culling user %s (inactive for %s)",
+                user['name'], inactive)
+
+        if max_age and not should_cull:
+            # only check created if max_age is specified
+            # so that we can still be compatible with jupyterhub 0.8
+            # which doesn't define the 'started' field
+            if age is not None and age.total_seconds() >= max_age:
+                app_log.info(
+                    "Culling user %s (age: %s, inactive for %s)",
+                    user['name'], format_td(age), format_td(inactive))
+                should_cull = True
+
+        if not should_cull:
+            app_log.debug(
+                "Not culling user %s (created: %s, last active: %s)",
+                user['name'], format_td(age), format_td(inactive))
+            return False
+
+        req = HTTPRequest(
+            url=url + '/users/%s' % user['name'],
+            method='DELETE',
+            headers=auth_header,
+        )
+        yield fetch(req)
+        return True
+
+    for user in users:
+        futures.append((user['name'], handle_user(user)))
+
     for (name, f) in futures:
-        yield f
-        app_log.debug("Finished culling %s", name)
+        try:
+            result = yield f
+        except Exception:
+            app_log.exception("Error processing %s", name)
+        else:
+            if result:
+                app_log.debug("Finished culling %s", name)
+
 
 if __name__ == '__main__':
-    define('url', default='http://127.0.0.1:8081/hub', help="The JupyterHub API URL")
+    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_every', default=0,
+           help="The interval (in seconds) for checking for idle servers to cull")
+    define('max_age', default=0,
+           help="The maximum age (in seconds) of servers that should be culled even if they are active")
+    define('cull_users', default=False,
+           help="""Cull users in addition to servers.
+                This is for use in temporary-user cases such as tmpnb.""",
+           )
+    define('concurrency', default=10,
+           help="""Limit the number of concurrent requests made to the Hub.
+
+                Deleting a lot of users at the same time can slow down the Hub,
+                so limit the number of API requests we have outstanding at any given time.
+                """
+           )
+
     parse_command_line()
     if not options.cull_every:
         options.cull_every = options.timeout // 2
-    
-    api_token = os.environ['JPY_API_TOKEN']
-    
+    api_token = os.environ['JUPYTERHUB_API_TOKEN']
+
+    try:
+        AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")
+    except ImportError as e:
+        app_log.warning(
+            "Could not load pycurl: %s\n"
+            "pycurl is recommended if you have a large number of users.",
+            e)
+
     loop = IOLoop.current()
-    cull = lambda : cull_idle(options.url, api_token, options.timeout)
-    # run once before scheduling periodic call
-    loop.run_sync(cull)
+    cull = partial(
+        cull_idle,
+        url=options.url,
+        api_token=api_token,
+        inactive_limit=options.timeout,
+        cull_users=options.cull_users,
+        max_age=options.max_age,
+        concurrency=options.concurrency,
+    )
+    # schedule first cull immediately
+    # because PeriodicCallback doesn't start until the end of the first interval
+    loop.add_callback(cull)
     # schedule periodic cull
     pc = PeriodicCallback(cull, 1e3 * options.cull_every)
     pc.start()
@@ -81,4 +365,3 @@ if __name__ == '__main__':
         loop.start()
     except KeyboardInterrupt:
         pass
-    

examples/cull-idle/jupyterhub_config.py

@@ -0,0 +1,8 @@
+# run cull-idle as a service
+c.JupyterHub.services = [
+    {
+        'name': 'cull-idle',
+        'admin': True,
+        'command': 'python3 cull_idle_servers.py --timeout=3600'.split(),
+    }
+]

examples/external-oauth/README.md

@@ -0,0 +1,90 @@
+# Using JupyterHub as an OAuth provider
+
+JupyterHub 0.9 introduces the ability to use JupyterHub as an OAuth provider
+for external services that may not be otherwise integrated with JupyterHub.
+The main feature this enables is using JupyterHub like a 'regular' OAuth 2
+provider for services running anywhere.
+
+There are two examples here. `whoami-oauth` (in the service-whoami directory) uses `jupyterhub.services.HubOAuthenticated`
+to authenticate requests with the Hub for a service run on its own host.
+This is an implementation of OAuth 2.0 provided by the jupyterhub package,
+which configures all of the necessary URLs from environment variables.
+
+The second is `whoami-oauth-basic`, which implements the full OAuth process
+without any inheritance, so it can be used as a reference for OAuth
+implementations in other web servers or languages.
+
+## Run the example
+
+1. generate an API token:
+
+        export JUPYTERHUB_API_TOKEN=`openssl rand -hex 32`
+
+2. launch a version of the the whoami service.
+   For `whoami-oauth`:
+
+        bash launch-service.sh &
+
+    or for `whoami-oauth-basic`:
+
+        bash launch-service-basic.sh &
+
+3. Launch JupyterHub:
+
+        jupyterhub
+
+4. Visit http://127.0.0.1:5555/
+
+After logging in with your local-system credentials, you should see a JSON dump of your user info:
+
+```json
+{
+ "admin": false,
+ "last_activity": "2016-05-27T14:05:18.016372",
+ "name": "queequeg",
+ "pending": null,
+ "server": "/user/queequeg"
+}
+```
+
+
+The essential pieces for using JupyterHub as an OAuth provider are:
+
+1. registering your service with jupyterhub:
+
+    ```python
+    c.JupyterHub.services = [
+        {
+            # the name of your service
+            # should be simple and unique.
+            # mostly used to identify your service in logging
+            "name": "my-service",
+            # the oauth client id of your service
+            # must be unique but isn't private
+            # can be randomly generated or hand-written
+            "oauth_client_id": "abc123",
+            # the API token and client secret of the service
+            # should be generated securely,
+            # e.g. via `openssl rand -hex 32`
+            "api_token": "abc123...",
+            # the redirect target for jupyterhub to send users
+            # after successful authentication
+            "oauth_redirect_uri": "https://service-host/oauth_callback"
+        }
+    ]
+    ```
+
+2. Telling your service how to authenticate with JupyterHub.
+
+The relevant OAuth URLs and keys for using JupyterHub as an OAuth provider are:
+
+1. the client_id, used in oauth requests
+2. the api token registered with jupyterhub is the client_secret for oauth requests
+3. oauth url of the Hub, which is "/hub/api/oauth2/authorize", e.g. `https://myhub.horse/hub/api/oauth2/authorize`
+4. a redirect handler to receive the authenticated response
+   (at `oauth_redirect_uri` registered in jupyterhub config)
+5. the token URL for completing the oauth process is "/hub/api/oauth2/token",
+   e.g. `https://myhub.horse/hub/api/oauth2/token`.
+   The reply is JSON and the token is in the field `access_token`.
+6. Users can be identified by oauth token by making a request to `/hub/api/user`
+   with the new token in the `Authorization` header.

examples/external-oauth/jupyterhub_config.py

@@ -0,0 +1,18 @@
+import os
+
+# get the oauth client's API token.
+# this could come from anywhere
+api_token = os.getenv("JUPYTERHUB_API_TOKEN")
+if not api_token:
+    raise ValueError("Make sure to `export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32)`")
+
+# tell JupyterHub to register the service as an external oauth client
+
+c.JupyterHub.services = [
+    {
+        'name': 'external-oauth',
+        'oauth_client_id': "whoami-oauth-client-test",
+        'api_token': api_token,
+        'oauth_redirect_uri': 'http://127.0.0.1:5555/oauth_callback',
+    },
+]