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

.github/issue_template.md

@@ -1,29 +0,0 @@
-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.
-
-- Where applicable, please fill out the details below to help us troubleshoot
-  the issue that you are facing. Please be as thorough as you are able to
-  provide details on the issue.
-
-**How to reproduce the issue**
-
-**What you expected to happen**
-
-**What actually happens**
-
-**Share what version of JupyterHub you are using**
-
-Running `jupyter troubleshoot` from the command line, if possible, and posting
-its output would also be helpful.
-
-```
-
-Insert jupyter troubleshoot output here
-
-
-```

.gitignore

@@ -3,9 +3,10 @@ node_modules
 *~
 .cache
 .DS_Store
-build
+/build
 dist
 docs/_build
+docs/build
 docs/source/_static/rest-api
 .ipynb_checkpoints
 # ignore config file at the top-level of the repo
@@ -13,11 +14,13 @@ docs/source/_static/rest-api
 /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,21 +1,68 @@
-# http://travis-ci.org/#!/jupyter/jupyterhub
 language: python
 sudo: false
+cache:
+  - pip
 python:
+  - 3.6
   - 3.5
-    - 3.4
-    - 3.3
+  - nightly
+env:
+  global:
+    - ASYNC_TEST_TIMEOUT=15
+    - MYSQL_HOST=127.0.0.1
+    - MYSQL_TCP_PORT=13306
+services:
+  - postgres
+  - docker
+
+# installing dependencies
 before_install:
+  - nvm install 6; nvm use 6
   - npm install
   - npm install -g configurable-http-proxy
-    - git clone --quiet --depth 1 https://github.com/minrk/travis-wheels travis-wheels
+  - |
+    # 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 --pre -f travis-wheels/wheelhouse -r dev-requirements.txt .
+  - pip install --upgrade pip
+  - pip install --pre -r dev-requirements.txt .
+  - pip freeze
+
+# running tests
 script:
-    - travis_retry 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
+
 matrix:
+  fast_finish: true
   include:
-    - python: 3.5
-      env: JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://127.0.0.1.xip.io:8000
+    - python: 3.6
+      env: JUPYTERHUB_TEST_SUBDOMAIN_HOST=http://localhost.jovyan.org:8000
+    - python: 3.6
+      env:
+        - 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

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

@@ -21,28 +21,26 @@
 # your jupyterhub_config.py will be added automatically
 # from your docker directory.
 
-FROM debian:jessie
-MAINTAINER Jupyter Project <jupyter@googlegroups.com>
+FROM ubuntu:18.04
+LABEL maintainer="Jupyter Project <jupyter@googlegroups.com>"
 
 # install nodejs, utf8 locale, set CDN because default httpredir is unreliable
 ENV DEBIAN_FRONTEND noninteractive
-RUN REPO=http://cdn-fastly.deb.debian.org && \
-    echo "deb $REPO/debian jessie main\ndeb $REPO/debian-security jessie/updates main" > /etc/apt/sources.list && \
-    apt-get -y update && \
+RUN apt-get -y update && \
     apt-get -y upgrade && \
-    apt-get -y install wget locales git bzip2 &&\
-    /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 + NodeJS with conda
-RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-4.2.12-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
-    echo 'd0c7c71cc5659e54ab51f2005a8d96f3 */tmp/miniconda.sh' | md5sum -c - && \
+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 -c conda-forge python=3.5 sqlalchemy tornado jinja2 traitlets requests pip nodejs configurable-http-proxy && \
+    /opt/conda/bin/conda install --yes -c conda-forge \
+      python=3.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
@@ -50,7 +48,7 @@ ENV PATH=/opt/conda/bin:$PATH
 ADD . /src/jupyterhub
 WORKDIR /src/jupyterhub
 
-RUN python setup.py js && pip install . && \
+RUN pip install . && \
     rm -rf $PWD ~/.cache ~/.npm
 
 RUN mkdir -p /srv/jupyterhub/

MANIFEST.in

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

dev-requirements.txt

@@ -1,7 +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

docs/environment.yml

@@ -1,16 +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
+- python=3.6
+- alembic
 - jinja2
 - pamela
 - requests
 - sqlalchemy>=1
-- tornado>=4.1
+- tornado>=5.0
 - traitlets>=4.1
-- sphinx>=1.3.6
-- sphinx_rtd_theme
+- sphinx>=1.7
 - pip:
+  - python-oauth2
   - recommonmark==0.4.0
+  - async_generator
+  - prometheus_client
+  - attrs>=17.4.0

docs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyterhub-docs-build",
-  "version": "0.0.0",
+  "version": "0.8.0",
   "description": "build JupyterHub swagger docs",
   "scripts": {
     "rest-api": "bootprint openapi ./rest-api.yml source/_static/rest-api"
@@ -8,7 +8,7 @@
   "author": "",
   "license": "BSD-3-Clause",
   "devDependencies": {
-    "bootprint": "^0.8.5",
-    "bootprint-openapi": "^0.17.0"
+    "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>=1.3.6
+sphinx>=1.7
 recommonmark==0.4.0

docs/rest-api.yml

@@ -3,7 +3,7 @@ swagger: '2.0'
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 0.7.0
+  version: 0.9.0dev
   license:
     name: BSD-3-Clause
 schemes:
@@ -203,18 +203,91 @@ paths:
           description: The user's notebook server has stopped
         '202':
           description: The user's notebook server has not yet stopped as it is taking a while to stop
-  /users/{name}/admin-access:
+  /users/{name}/servers/{server_name}:
     post:
-      summary: Grant admin access to this user's notebook 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 administrator access to the user's notebook 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
@@ -377,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
@@ -387,9 +489,9 @@ paths:
         type: string
       responses:
         '200':
-          description: The user identified by the API token
-          schema:
-            $ref: '#/definitions/User'
+          description: The user or service identified by the API token
+        '404':
+          description: A user or service is not found.
   /authorizations/cookie/{cookie_name}/{cookie_value}:
     get:
       summary: Identify a user from a cookie
@@ -408,6 +510,81 @@ paths:
           description: The user identified by the cookie
           schema:
             $ref: '#/definitions/User'
+        '404':
+          description: A user is not found.
+  /oauth2/authorize:
+    get:
+      summary: 'OAuth 2.0 authorize endpoint'
+      description: |
+        Redirect users to this URL to begin the OAuth process.
+        It is not an API endpoint.
+      parameters:
+        - name: client_id
+          description: The client id
+          in: query
+          required: true
+          type: string
+        - name: response_type
+          description: The response type (always 'code')
+          in: query
+          required: true
+          type: string
+        - name: state
+          description: A state string
+          in: query
+          required: false
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: query
+          required: true
+          type: string
+  /oauth2/token:
+    post:
+      summary: Request an OAuth2 token
+      description: |
+        Request an OAuth2 token from an authorization code.
+        This request completes the OAuth process.
+      consumes:
+        - application/x-www-form-urlencoded
+      parameters:
+        - name: client_id
+          description: The client id
+          in: form
+          required: true
+          type: string
+        - name: client_secret
+          description: The client secret
+          in: form
+          required: true
+          type: string
+        - name: grant_type
+          description: The grant type (always 'authorization_code')
+          in: form
+          required: true
+          type: string
+        - name: code
+          description: The code provided by the authorization redirect
+          in: form
+          required: true
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: form
+          required: true
+          type: string
+      responses:
+        '200':
+          description: JSON response including the token
+          schema:
+            type: object
+            properties:
+              access_token:
+                type: string
+                description: The new API token for the user
+              token_type:
+                type: string
+                description: Will always be 'Bearer'
   /shutdown:
     post:
       summary: Shutdown the Hub
@@ -419,10 +596,7 @@ paths:
         - name: servers
           in: body
           type: boolean
-          description: Whether users's notebook servers should be shutdown as well (default from Hub config)
-      responses:
-        '200':
-          description: Hub has shutdown
+          description: Whether users' notebook servers should be shutdown as well (default from Hub config)
 definitions:
   User:
     type: object
@@ -443,12 +617,55 @@ definitions:
         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: 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:
@@ -483,3 +700,40 @@ definitions:
         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,19 +1,21 @@
 .. _api-index:
 
-####################
+##################
 The JupyterHub API
-####################
+##################
 
 :Release: |release|
 :Date: |today|
 
 JupyterHub also provides a REST API for administration of the Hub and users.
-The documentation on `Using JupyterHub's REST API <../rest.html>`_ provides
+The documentation on `Using JupyterHub's REST API <../reference/rest.html>`_ provides
 information on:
 
-- Creating an API token
-- Adding tokens to the configuration file (optional)
-- Making an API request
+- what you can do with the API
+- creating an API token
+- adding API tokens to the config files
+- making an API request programmatically using the requests library
+- learning more about JupyterHub's API
 
 The same JupyterHub API spec, as found here, is available in an interactive form
 `here (on swagger's petstore) <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default>`__.
@@ -24,9 +26,12 @@ JupyterHub API Reference:
 
 .. toctree::
 
+    app
     auth
     spawner
+    proxy
     user
+    service
     services.auth
 
 

docs/source/api/proxy.rst

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

docs/source/api/service.rst

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

docs/source/api/services.auth.rst

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

docs/source/api/spawner.rst

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

docs/source/api/user.rst

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

docs/source/authenticators.md

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

docs/source/changelog.md

@@ -1,14 +1,298 @@
-# Change log summary
+# Changelog
 
 For detailed changes from the prior release, click on the version number, and
 its link will bring up a GitHub listing of changes. Use `git log` on the
 command line for details.
 
 
-## [Unreleased] 0.8
+## [Unreleased]
+
+## 0.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
@@ -118,8 +402,15 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 First preview release
 
 
-[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/0.7.0...HEAD
-[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/0.6.1...0.7.0
+[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

docs/source/conf.py

@@ -8,7 +8,7 @@ import shlex
 import recommonmark.parser
 
 # Set paths
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
@@ -20,6 +20,7 @@ extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'autodoc_traits',
 ]
 
 templates_path = ['_templates']
@@ -34,11 +35,14 @@ author = u'Project Jupyter team'
 
 # Autopopulate version
 from os.path import dirname
+
 docs = dirname(dirname(__file__))
 root = dirname(docs)
 sys.path.insert(0, root)
+sys.path.insert(0, os.path.join(docs, 'sphinxext'))
 
 import jupyterhub
+
 # The short X.Y version.
 version = '%i.%i' % jupyterhub.version_info[:2]
 # The full version, including alpha/beta/rc tags.
@@ -49,11 +53,12 @@ exclude_patterns = []
 pygments_style = 'sphinx'
 todo_include_todos = False
 
+# Set the default role so we can use `foo` instead of ``foo``
+default_role = 'literal'
+
 # -- Source -------------------------------------------------------------
 
-source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
-}
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
 
 source_suffix = ['.rst', '.md']
 # source_encoding = 'utf-8-sig'
@@ -61,34 +66,39 @@ source_suffix = ['.rst', '.md']
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'alabaster'
 
-#html_theme_options = {}
-#html_theme_path = []
-#html_title = None
-#html_short_title = None
-#html_logo = None
-#html_favicon = None
+html_logo = '_static/images/logo/logo.png'
+html_favicon = '_static/images/logo/favicon.ico'
 
 # Paths that contain custom static files (such as style sheets)
 html_static_path = ['_static']
 
-#html_extra_path = []
-#html_last_updated_fmt = '%b %d, %Y'
-#html_use_smartypants = True
-#html_sidebars = {}
-#html_additional_pages = {}
-#html_domain_indices = True
-#html_use_index = True
-#html_split_index = False
-#html_show_sourcelink = True
-#html_show_sphinx = True
-#html_show_copyright = True
-#html_use_opensearch = ''
-#html_file_suffix = None
-#html_search_language = 'en'
-#html_search_options = {'type': 'default'}
-#html_search_scorer = 'scorer.js'
+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',
+    },
+}
+
+html_sidebars = {
+    '**': [
+        'about.html',
+        'searchbox.html',
+        'navigation.html',
+        'relations.html',
+        'sourcelink.html',
+    ]
+}
+
 htmlhelp_basename = 'JupyterHubdoc'
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -104,8 +114,13 @@ latex_elements = {
 # (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',
+    )
 ]
 
 # latex_logo = None
@@ -120,10 +135,7 @@ latex_documents = [
 
 # 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)]
 
 # man_show_urls = False
 
@@ -134,9 +146,15 @@ man_pages = [
 # (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',
+    )
 ]
 
 # texinfo_appendices = []
@@ -158,21 +176,18 @@ epub_exclude_files = ['search.html']
 
 # -- Intersphinx ----------------------------------------------------------
 
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3/': None}
 
 # -- Read The Docs --------------------------------------------------------
 
 on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
-
 if not on_rtd:
-    # only import and set the theme if we're building docs locally
-    import sphinx_rtd_theme
-    html_theme = 'sphinx_rtd_theme'
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    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
+
     sh(['make', 'rest-api'], cwd=docs)
 
 # -- Spell checking -------------------------------------------------------

docs/source/config-examples.md

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

docs/source/contributor-list.md

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

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

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

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

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

docs/source/getting-started/index.rst

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

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

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

docs/source/index.rst

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

docs/source/installation-basics.md

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

docs/source/installation-guide.rst

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

docs/source/quickstart-docker.rst

@@ -0,0 +1,49 @@
+Using Docker
+============
+
+.. important::
+
+   We highly recommend following the `Zero to JupyterHub`_ tutorial for
+   installing JupyterHub.
+
+Alternate installation using Docker
+-----------------------------------
+
+A ready to go `docker image <https://hub.docker.com/r/jupyterhub/jupyterhub/>`_
+gives a straightforward deployment of JupyterHub.
+
+.. note::
+
+    This ``jupyterhub/jupyterhub`` docker image is only an image for running
+    the Hub service itself. It does not provide the other Jupyter components,
+    such as Notebook installation, which are needed by the single-user servers.
+    To run the single-user servers, which may be on the same system as the Hub or
+    not, Jupyter Notebook version 4 or greater must be installed.
+
+Starting JupyterHub with docker
+-------------------------------
+
+The JupyterHub docker image can be started with the following command::
+
+    docker run -d --name jupyterhub jupyterhub/jupyterhub jupyterhub
+
+This command will create a container named ``jupyterhub`` that you can
+**stop and resume** with ``docker stop/start``.
+
+The Hub service will be listening on all interfaces at port 8000, which makes
+this a good choice for **testing JupyterHub on your desktop or laptop**.
+
+If you want to run docker on a computer that has a public IP then you should
+(as in MUST) **secure it with ssl** by adding ssl options to your docker
+configuration or using a ssl enabled proxy.
+
+`Mounting volumes <https://docs.docker.com/engine/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

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

docs/source/reference/authenticators.md

@@ -0,0 +1,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

@@ -4,18 +4,18 @@ With version 0.7, JupyterHub adds support for **Services**.
 
 This section provides the following information about Services:
 
-- [Definition of a Service](services.html#definition-of-a-service)
-- [Properties of a Service](services.html#properties-of-a-service)
-- [Hub-Managed Services](services.html#hub-managed-services)
-- [Launching a Hub-Managed Service](services.html#launching-a-hub-managed-service)
-- [Externally-Managed Services](services.html#externally-managed-services)
-- [Writing your own Services](services.html#writing-your-own-services)
-- [Hub Authentication and Services](services.html#hub-authentication-and-services)
+- [Definition of a Service](#definition-of-a-service)
+- [Properties of a Service](#properties-of-a-service)
+- [Hub-Managed Services](#hub-managed-services)
+- [Launching a Hub-Managed Service](#launching-a-hub-managed-service)
+- [Externally-Managed Services](#externally-managed-services)
+- [Writing your own Services](#writing-your-own-services)
+- [Hub Authentication and Services](#hub-authentication-and-services)
 
 ## Definition of a Service
 
 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
+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
@@ -45,6 +45,8 @@ A Service may have the following properties:
 - `url: str (default - None)` - The URL where the service is/should be. If a
   url is specified for where the Service runs its own web server,
   the service will be added to the proxy at `/services/:name`
+- `api_token: str (default - None)` - For Externally-Managed Services you need to specify 
+  an API token to perform API requests to the Hub
 
 If a service is also to be managed by the Hub, it has a few extra options:
 
@@ -54,7 +56,7 @@ If a service is also to be managed by the Hub, it has a few extra options:
         externally.
       - If a command is specified for launching the Service, the Service will
         be started and managed by the Hub.
-- `env: dict` - environment variables to add to the current env
+- `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.
 
@@ -99,7 +101,7 @@ c.JupyterHub.services = [
 A Hub-Managed Service may also be configured with additional optional
 parameters, which describe the environment needed to start the Service process:
 
-- `env: dict` - additional environment variables for the Service.
+- `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
@@ -176,7 +178,13 @@ When you run a service that has a url, it will be accessible under a
 your service to route proxied requests properly, it must take
 `JUPYTERHUB_SERVICE_PREFIX` into account when routing requests. For example, a
 web service would normally service its root handler at `'/'`, but the proxied
-service would need to serve `JUPYTERHUB_SERVICE_PREFIX + '/'`.
+service would need to serve `JUPYTERHUB_SERVICE_PREFIX`.
+
+Note that `JUPYTERHUB_SERVICE_PREFIX` will contain a trailing slash. This must
+be taken into consideration when creating the service routes. If you include an
+extra slash you might get unexpected behavior. For example if your service has a
+`/foo` endpoint, the route would be `JUPYTERHUB_SERVICE_PREFIX + foo`, and
+`/foo/bar` would be `JUPYTERHUB_SERVICE_PREFIX + foo/bar`.
 
 ## Hub Authentication and Services
 
@@ -197,8 +205,10 @@ To use HubAuth, you must set the `.api_token`, either programmatically when cons
 or via the `JUPYTERHUB_API_TOKEN` environment variable.
 
 Most of the logic for authentication implementation is found in the 
-[`HubAuth.user_for_cookie`](services.auth.html#jupyterhub.services.auth.HubAuth.user_for_cookie)
-method, which makes a request of the Hub, and returns:
+[`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:
@@ -250,8 +260,11 @@ def authenticated(f):
     @wraps(f)
     def decorated(*args, **kwargs):
         cookie = request.cookies.get(auth.cookie_name)
+        token = request.headers.get(auth.auth_header_name)
         if cookie:
             user = auth.user_for_cookie(cookie)
+        elif token:
+            user = auth.user_for_token(token)
         else:
             user = None
         if user:
@@ -262,7 +275,7 @@ def authenticated(f):
     return decorated
 
 
-@app.route(prefix + '/')
+@app.route(prefix)
 @authenticated
 def whoami(user):
     return Response(
@@ -346,12 +359,16 @@ and taking note of the following process:
    ```
 
 An example of using an Externally-Managed Service and authentication is
-[nbviewer](https://github.com/jupyter/nbviewer#securing-the-notebook-viewer),
+in [nbviewer README][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 [here](https://github.com/jupyter/nbviewer#securing-the-notebook-viewer).
+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
-[HubAuthenticated]: api/services.auth.html#jupyterhub.services.auth.HubAuthenticated
+[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

@@ -36,8 +36,7 @@ Some examples include:
 Information about the user can be retrieved from `self.user`,
 an object encapsulating the user's name, authentication, and server info.
 
-When `Spawner.start` returns, it should have stored the IP and port
-of the single-user server in `self.user.server`.
+The return value of `Spawner.start` should be the (ip, port) of the running server.
 
 **NOTE:** When writing coroutines, *never* `yield` in between a database change and a commit.
 
@@ -45,10 +44,19 @@ 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()
+    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,
@@ -114,7 +122,7 @@ This feature is enabled by setting `Spawner.options_form`, which is an HTML form
 inserted unmodified into the spawn form.
 If the `Spawner.options_form` is defined, when a user tries to start their server, they will be directed to a form page, like this:
 
-![spawn-form](images/spawn-form.png)
+![spawn-form](../images/spawn-form.png)
 
 If `Spawner.options_form` is undefined, the user's server is spawned directly, and no spawn page is rendered.
 
@@ -171,9 +179,12 @@ If you are interested in building a custom spawner, you can read [this tutorial]
 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.
+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
 
@@ -191,8 +202,8 @@ 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
+**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
@@ -209,6 +220,6 @@ higher priority applications might be taking up CPU.
 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
+**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

@@ -2,33 +2,25 @@
 
 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. Before upgrading a
-JupyterHub deployment, it's critical to backup your data and configurations
-before shutting down the JupyterHub process and server.
+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.
 
-## Databases: SQLite (default) or RDBMS (PostgreSQL, MySQL)
+**Before upgrading a JupyterHub deployment**, it's critical to backup your data
+and configurations before shutting down the JupyterHub process and server.
 
-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.
+## Note about upgrading the SQLite database
 
-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.
-
-For production systems, SQLite has some disadvantages when used with JupyterHub:
+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 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).
-
 ## The upgrade process
 
-Four fundamental process steps are needed when upgrading JupyterHub and its
+Five fundamental process steps are needed when upgrading JupyterHub and its
 database:
 
 1. Backup JupyterHub database

docs/source/reference/websecurity.md

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

docs/source/rest.md

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

docs/source/troubleshooting.md

@@ -7,6 +7,9 @@ problem and how to resolve it.
 [*Behavior*](#behavior)
 - JupyterHub proxy fails to start
 - sudospawner fails to run
+- What is the default behavior when none of the lists (admin, whitelist,
+  group whitelist) are set?
+- JupyterHub Docker container not accessible at localhost
 
 [*Errors*](#errors)
 - 500 error after spawning my single-user server
@@ -18,6 +21,9 @@ problem and how to resolve it.
 - How do I increase the number of pySpark executors on YARN?
 - How do I use JupyterLab's prerelease version with JupyterHub?
 - How do I set up JupyterHub for a workshop (when users are not known ahead of time)?
+- How do I set up rotating daily logs?
+- Toree integration with HDFS rack awareness script
+- Where do I find Docker images and Dockerfiles related to JupyterHub?
 
 [*Troubleshooting commands*](#troubleshooting-commands)
 
@@ -31,6 +37,10 @@ If you have tried to start the JupyterHub proxy and it fails to start:
   ``c.JupyterHub.ip = '*'``; if it is, try ``c.JupyterHub.ip = ''``
 - Try starting with ``jupyterhub --ip=0.0.0.0``
 
+**Note**: If this occurs on Ubuntu/Debian, check that the you are using a
+recent version of node. Some versions of Ubuntu/Debian come with a version
+of node that is very old, and it is necessary to update node.
+
 ### sudospawner fails to run
 
 If the sudospawner script is not found in the path, sudospawner will not run.
@@ -45,6 +55,27 @@ or add:
 
 to the config file, `jupyterhub_config.py`.
 
+### What is the default behavior when none of the lists (admin, whitelist, group whitelist) are set?
+
+When nothing is given for these lists, there will be no admins, and all users
+who can authenticate on the system (i.e. all the unix users on the server with
+a password) will be allowed to start a server. The whitelist lets you limit
+this to a particular set of users, and the admin_users lets you specify who
+among them may use the admin interface (not necessary, unless you need to do
+things like inspect other users' servers, or modify the userlist at runtime).
+
+### 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
@@ -70,7 +101,7 @@ 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/jupyter-hub-token-name/[secret] (@10.0.1.4) 6.10ms
+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
@@ -80,7 +111,7 @@ 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/jupyter-hub-token-name/[secret] (@10.0.1.4) 4.14ms
+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
@@ -226,6 +257,31 @@ notebook servers to default to JupyterLab:
 
 Users will need a GitHub account to login and be authenticated by the Hub.
 
+### How do I set up rotating daily logs?
+
+You can do this with [logrotate](https://linux.die.net/man/8/logrotate),
+or pipe to `logger` to use syslog instead of directly to a file.
+
+For example, with this logrotate config file:
+
+```
+/var/log/jupyterhub.log {
+  copytruncate
+  daily
+}
+```
+
+and run this daily by putting a script in `/etc/cron.daily/`:
+
+```bash
+logrotate /path/to/above-config
+```
+
+Or use syslog:
+
+    jupyterhub | logger -t jupyterhub
+
+
 ## Troubleshooting commands
 
 The following commands provide additional detail about installed packages,
@@ -249,3 +305,35 @@ jupyter kernelspec list
 ```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/source/websecurity.md

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

docs/sphinxext/autodoc_traits.py

@@ -0,0 +1,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

@@ -15,7 +15,7 @@ c.JupyterHub.services = [
     {
         'name': 'cull-idle',
         'admin': True,
-        'command': 'python cull_idle_servers.py --timeout=3600'.split(),
+        'command': 'python3 cull_idle_servers.py --timeout=3600'.split(),
     }
 ]
 ```
@@ -37,5 +37,5 @@ variable. Run `cull_idle_servers.py` manually.
 
 ```bash
     export JUPYTERHUB_API_TOKEN=`jupyterhub token`
-    python cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+    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:
@@ -16,75 +16,348 @@ You can run this as a service managed by JupyterHub with this in your config::
         {
             'name': 'cull-idle',
             'admin': True,
-            'command': 'python cull_idle_servers.py --timeout=3600'.split(),
+            '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`
-    python cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+    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
+        'Authorization': 'token %s' % api_token,
     }
-    req = HTTPRequest(url=url + '/users',
+    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 + '/users/%s/server' % user['name'],
+
+    @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'])
+            )
+        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,
         )
-            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)
+        yield fetch(req)
+        return True
+
+    for user in users:
+        futures.append((user['name'], handle_user(user)))
 
     for (name, f) in futures:
-        yield f
+        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=os.environ.get('JUPYTERHUB_API_URL'), 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['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()
@@ -92,4 +365,3 @@ if __name__ == '__main__':
         loop.start()
     except KeyboardInterrupt:
         pass
-    

examples/cull-idle/jupyterhub_config.py

@@ -3,6 +3,6 @@ c.JupyterHub.services = [
     {
         'name': 'cull-idle',
         'admin': True,
-        'command': 'python cull_idle_servers.py --timeout=3600'.split(),
+        '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',
+    },
+]

examples/external-oauth/launch-service-basic.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# script to launch whoami-oauth-basic service
+set -euo pipefail
+
+# the service needs to know:
+# 1. API token
+if [[ -z "${JUPYTERHUB_API_TOKEN}" ]]; then
+    echo 'set API token with export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32)'
+fi
+
+# 2. oauth client ID
+export JUPYTERHUB_CLIENT_ID='whoami-oauth-client-test'
+# 3. where the Hub is
+export JUPYTERHUB_URL='http://127.0.0.1:8000'
+
+# 4. where to run
+export JUPYTERHUB_SERVICE_URL='http://127.0.0.1:5555'
+
+# launch the service
+exec python3 whoami-oauth-basic.py

examples/external-oauth/launch-service.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# script to launch whoami-oauth service
+set -euo pipefail
+
+# the service needs to know:
+# 1. API token
+if [[ -z "${JUPYTERHUB_API_TOKEN}" ]]; then
+    echo 'set API token with export JUPYTERHUB_API_TOKEN=$(openssl rand -hex 32)'
+fi
+
+# 2. oauth client ID
+export JUPYTERHUB_CLIENT_ID="whoami-oauth-client-test"
+# 3. what URL to run on
+export JUPYTERHUB_SERVICE_PREFIX='/'
+export JUPYTERHUB_SERVICE_URL='http://127.0.0.1:5555'
+export JUPYTERHUB_OAUTH_CALLBACK_URL="$JUPYTERHUB_SERVICE_URL/oauth_callback"
+# 4. where the Hub is
+export JUPYTERHUB_HOST='http://127.0.0.1:8000'
+
+# launch the service
+exec python3 ../service-whoami/whoami-oauth.py