Merge pull request #2545 from minrk/changelog-1.0

releasing 1.0

.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,18 @@
 [run]
+parallel = True
+branch = False
 omit =
     jupyterhub/tests/*
-    jupyterhub/singleuser.py
+    jupyterhub/alembic/*
+
+[report]
+exclude_lines =
+    if self.debug:
+    pragma: no cover
+    raise NotImplementedError
+    if __name__ == .__main__.:
+ignore_errors = True
+omit =
+    jupyterhub/tests/*
+    jupyterhub/alembic/*
+    */site-packages/*

.dockerignore

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

.flake8

@@ -0,0 +1,24 @@
+[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, D400
+builtins = c, get_config
+exclude =
+    .cache,
+    .github,
+    docs,
+    jupyterhub/alembic*,
+    onbuild,
+    scripts,
+    share,
+    tools,
+    setup.py

.github/ISSUE_TEMPLATE/bug_report.md

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

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

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

.gitignore

@@ -1,21 +1,28 @@
 node_modules
 *.py[co]
 *~
+.cache
 .DS_Store
-build
+/build
 dist
 docs/_build
+docs/build
+docs/source/_static/rest-api
 .ipynb_checkpoints
 # ignore config file at the top-level of the repo
 # but not sub-dirs
 /jupyterhub_config.py
 jupyterhub_cookie_secret
 jupyterhub.sqlite
-share/jupyter/hub/static/components
-share/jupyter/hub/static/css/style.min.css
-share/jupyter/hub/static/css/style.min.css.map
+package-lock.json
+share/jupyterhub/static/components
+share/jupyterhub/static/css/style.min.css
+share/jupyterhub/static/css/style.min.css.map
 *.egg-info
 MANIFEST
 .coverage
+.coverage.*
 htmlcov
-
+.idea/
+.pytest_cache
+pip-wheel-metadata

.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+- repo: https://github.com/asottile/reorder_python_imports
+  rev: v1.3.5
+  hooks:
+  - id: reorder-python-imports
+    language_version: python3.6
+- repo: https://github.com/ambv/black
+  rev: 18.9b0
+  hooks:
+  - id: black
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v2.1.0
+  hooks:
+  - id: end-of-file-fixer
+  - id: check-json
+  - id: check-yaml
+  - id: check-case-conflict
+  - id: check-executables-have-shebangs
+  - id: requirements-txt-fixer
+  - id: flake8

.travis.yml

@@ -1,21 +1,100 @@
-# 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:
+  - set -e
+  - 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
+      # FIXME: mysql-connector-python 8.0.16 incorrectly decodes bytes to str
+      # ref: https://bugs.mysql.com/bug.php?id=94944
+      pip install 'mysql-connector-python==8.0.15'
+    elif [[ $JUPYTERHUB_TEST_DB_URL == postgresql* ]]; then
+      psql -c "CREATE USER $PGUSER WITH PASSWORD '$PGPASSWORD';" -U postgres
+      DB=postgres bash ci/init-db.sh
+      pip install psycopg2-binary
+    fi
 install:
-    - pip install -f travis-wheels/wheelhouse -r dev-requirements.txt .
+  - pip install --upgrade pip
+  - pip install --upgrade --pre -r dev-requirements.txt .
+  - pip freeze
+
+# running tests
 script:
-    - travis_retry py.test --cov jupyterhub jupyterhub/tests -v
+  - |
+    # run tests
+    if [[ -z "$TEST" ]]; then
+      pytest -v --maxfail=2 --cov=jupyterhub jupyterhub/tests
+    fi
+  - |
+    # run autoformat
+    if [[ "$TEST" == "lint" ]]; then
+      pre-commit run --all-files
+    fi
+  - |
+    # build docs
+    if [[ "$TEST" == "docs" ]]; then
+      pushd docs
+      pip install --upgrade -r requirements.txt
+      pip install --upgrade alabaster_jupyterhub
+      make html
+      popd
+    fi
 after_success:
   - codecov
+after_failure:
+  - |
+    # point to auto-lint-fix
+    if [[ "$TEST" == "lint" ]]; then
+      echo "You can install pre-commit hooks to automatically run formatting"
+      echo "on each commit with:"
+      echo "    pre-commit install"
+      echo "or you can run by hand on staged files with"
+      echo "    pre-commit run"
+      echo "or after-the-fact on already committed files with"
+      echo "    pre-commit run --all-files"
+    fi
+
 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: TEST=lint
+    - python: 3.6
+      env: TEST=docs
+    - 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:
+        - PGUSER=jupyterhub
+        - PGPASSWORD=hub[test/:?
+        # password in url is url-encoded (urllib.parse.quote($PGPASSWORD, safe=''))
+        - JUPYTERHUB_TEST_DB_URL=postgresql://jupyterhub:hub%5Btest%2F%3A%3F@127.0.0.1/jupyterhub
+    - python: 3.7
+      dist: xenial
+  allow_failures:
+    - python: nightly

CHECKLIST-Release.md

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

CODE_OF_CONDUCT.md

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

CONTRIBUTING.md

@@ -1,3 +1,102 @@
-# Contributing
+# Contributing to JupyterHub
 
-We mainly follow the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/master/CONTRIBUTING.md).
+Welcome! As a [Jupyter](https://jupyter.org) project,
+you can follow the [Jupyter contributor guide](https://jupyter.readthedocs.io/en/latest/contributor/content-contributor.html).
+
+Make sure to also follow [Project Jupyter's Code of Conduct](https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md)
+for a friendly and welcoming collaborative environment.
+
+## Setting up a development environment
+
+JupyterHub requires Python >= 3.5 and nodejs.
+
+As a Python project, a development install of JupyterHub follows standard practices for the basics (steps 1-2).
+
+
+1. clone the repo
+    ```bash
+    git clone https://github.com/jupyterhub/jupyterhub
+    ```
+2. do a development install with pip
+
+    ```bash
+    cd jupyterhub
+    python3 -m pip install --editable .
+    ```
+3. install the development requirements,
+   which include things like testing tools
+
+    ```bash
+    python3 -m pip install -r dev-requirements.txt
+    ```
+4. install configurable-http-proxy with npm:
+
+    ```bash
+    npm install -g configurable-http-proxy
+    ```
+5. set up pre-commit hooks for automatic code formatting, etc.
+
+    ```bash
+    pre-commit install
+    ```
+
+    You can also invoke the pre-commit hook manually at any time with
+
+    ```bash
+    pre-commit run
+    ```
+
+## Contributing
+
+JupyterHub has adopted automatic code formatting so you shouldn't
+need to worry too much about your code style.
+As long as your code is valid,
+the pre-commit hook should take care of how it should look.
+You can invoke the pre-commit hook by hand at any time with:
+
+```bash
+pre-commit run
+```
+
+which should run any autoformatting on your code
+and tell you about any errors it couldn't fix automatically.
+You may also install [black integration](https://github.com/ambv/black#editor-integration)
+into your text editor to format code automatically.
+
+If you have already committed files before setting up the pre-commit
+hook with `pre-commit install`, you can fix everything up using
+`pre-commit run --all-files`.  You need to make the fixing commit
+yourself after that.
+
+## Testing
+
+It's a good idea to write tests to exercise any new features,
+or that trigger any bugs that you have fixed to catch regressions.
+
+You can run the tests with:
+
+```bash
+pytest -v
+```
+
+in the repo directory. If you want to just run certain tests,
+check out the [pytest docs](https://pytest.readthedocs.io/en/latest/usage.html)
+for how pytest can be called.
+For instance, to test only spawner-related things in the REST API:
+
+```bash
+pytest -v -k spawn jupyterhub/tests/test_api.py
+```
+
+The tests live in `jupyterhub/tests` and are organized roughly into:
+
+1. `test_api.py` tests the REST API
+2. `test_pages.py` tests loading the HTML pages
+
+and other collections of tests for different components.
+When writing a new test, there should usually be a test of
+similar functionality already written and related tests should
+be added nearby.
+When in doubt, feel free to ask.
+
+TODO: describe some details about fixtures, etc.

Dockerfile

@@ -21,37 +21,34 @@
 # 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
+# install nodejs, utf8 locale, set CDN because default httpredir is unreliable
 ENV DEBIAN_FRONTEND noninteractive
 RUN apt-get -y update && \
     apt-get -y upgrade && \
-    apt-get -y install npm nodejs nodejs-legacy wget locales git &&\
-    /usr/sbin/update-locale LANG=C.UTF-8 && \
-    locale-gen C.UTF-8 && \
-    apt-get remove -y locales && \
+    apt-get -y install wget git bzip2 && \
+    apt-get purge && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
 ENV LANG C.UTF-8
 
-# install Python with conda
-RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-4.0.5-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
-    echo 'a7bcd0425d8b6688753946b59681572f63c2241aed77bf0ec6de4c5edc5ceeac */tmp/miniconda.sh' | shasum -a 256 -c - && \
+# install Python + NodeJS with conda
+RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-4.5.11-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
+    echo 'e1045ee415162f944b6aebfe560b8fee */tmp/miniconda.sh' | md5sum -c - && \
     bash /tmp/miniconda.sh -f -b -p /opt/conda && \
-    /opt/conda/bin/conda install --yes python=3.5 sqlalchemy tornado jinja2 traitlets requests pip && \
+    /opt/conda/bin/conda install --yes -c conda-forge \
+      python=3.6 sqlalchemy tornado jinja2 traitlets requests pip pycurl \
+      nodejs configurable-http-proxy && \
     /opt/conda/bin/pip install --upgrade pip && \
     rm /tmp/miniconda.sh
 ENV PATH=/opt/conda/bin:$PATH
 
-# install js dependencies
-RUN npm install -g configurable-http-proxy && rm -rf ~/.npm
-
 ADD . /src/jupyterhub
 WORKDIR /src/jupyterhub
 
-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,19 +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 *~

README.md

@@ -1,158 +1,256 @@
-# JupyterHub: A multi-user server for Jupyter notebooks
+**[Technical Overview](#technical-overview)** |
+**[Installation](#installation)** |
+**[Configuration](#configuration)** |
+**[Docker](#docker)** |
+**[Contributing](#contributing)** |
+**[License](#license)** |
+**[Help and Resources](#help-and-resources)**
 
-Questions, comments? Visit our Google Group:
 
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+# [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)
 [![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)
-[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
-[![codecov.io](https://codecov.io/github/jupyter/jupyterhub/coverage.svg?branch=master)](https://codecov.io/github/jupyter/jupyterhub?branch=master)
+[![codecov.io](https://codecov.io/github/jupyterhub/jupyterhub/coverage.svg?branch=master)](https://codecov.io/github/jupyterhub/jupyterhub?branch=master)
+[![GitHub](https://img.shields.io/badge/issue_tracking-github-blue.svg)](https://github.com/jupyterhub/jupyterhub/issues)
+[![Discourse](https://img.shields.io/badge/help_forum-discourse-blue.svg)](https://discourse.jupyter.org/c/jupyterhub)
+[![Gitter](https://img.shields.io/badge/social_chat-gitter-blue.svg)](https://gitter.im/jupyterhub/jupyterhub)
 
+With [JupyterHub](https://jupyterhub.readthedocs.io) you can create a
+**multi-user Hub** which spawns, manages, and proxies multiple instances of the
+single-user [Jupyter notebook](https://jupyter-notebook.readthedocs.io)
+server.
 
-JupyterHub, a multi-user server, manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
+[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.
 
-Three actors:
+## Technical overview
 
-- multi-user Hub (tornado process)
-- configurable http proxy (node-http-proxy)
-- multiple single-user IPython notebook servers (Python/IPython/tornado)
+Three main actors make up JupyterHub:
 
-Basic principles:
+- multi-user **Hub** (tornado process)
+- configurable http **proxy** (node-http-proxy)
+- multiple **single-user Jupyter notebook servers** (Python/Jupyter/tornado)
 
-- 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
+Basic principles for operation are:
 
+- 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.
 
-## Dependencies
-
-JupyterHub itself requires [Python](https://www.python.org/downloads/) ≥ 3.3. To run the single-user servers (which may be on the same system as the Hub or not), [Jupyter Notebook](https://jupyter.readthedocs.org/en/latest/install.html) ≥ 4 is required.
-
-Install [nodejs/npm](https://www.npmjs.com/), 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.)
-
-Next, install JavaScript dependencies:
-
-    sudo npm install -g configurable-http-proxy
-
-### (Optional) Installation Prerequisite (pip)
-
-Notes on the `pip` command used in the installation directions below:
-- `sudo` may be needed for `pip install`, depending on the user's filesystem permissions.
-- JupyterHub requires Python >= 3.3, so `pip3` may be required on some machines for package installation instead of `pip` (especially when both Python 2 and Python 3 are installed on a machine). If `pip3` is not found, install it using (on Linux Debian/Ubuntu):
-
-        sudo apt-get install python3-pip
-
+JupyterHub also provides a
+[REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
+for administration of the Hub and its users.
 
 ## Installation
 
-JupyterHub can be installed with pip, and the proxy with npm:
 
+### 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 may also need to install the
-Jupyter ~~IPython~~ notebook:
+If you plan to run notebook servers locally, you will need to install the
+[Jupyter notebook](https://jupyter.readthedocs.io/en/latest/install.html)
+package:
 
-    pip3 install --upgrade notebook
+    python3 -m pip install --upgrade notebook
 
+### Run the Hub server
 
-### Development install
-
-For a development install, clone the repository and then install from source:
-
-    git clone https://github.com/jupyter/jupyterhub
-    cd jupyterhub
-    pip3 install -r dev-requirements.txt -e .
-
-If the `pip3 install` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional JavaScript dependencies:
-
-    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:
-
-    python3 setup.py js    # fetch updated client-side js (changes rarely)
-    python3 setup.py css   # recompile CSS from LESS sources
-
-
-## Running the server
-
-To start the server, run the command:
+To start the Hub server, run the command:
 
     jupyterhub
 
-and then visit `http://localhost:8000`, and sign in with your unix credentials.
+Visit `https://localhost:8000` in your browser, and sign in with your unix
+PAM credentials.
 
-To allow multiple users to sign into the server, you will need to
+*Note*: To allow multiple users to sign into the server, you will need to
 run the `jupyterhub` command as a *privileged user*, such as root.
-The [wiki](https://github.com/jupyter/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
-describes how to run the server as a *less privileged user*, which requires more
-configuration of the system.
+The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+describes how to run the server as a *less privileged user*, which requires
+more configuration of the system.
 
-## Getting started
+## Configuration
 
-See the [getting started document](docs/source/getting-started.md) for the
-basics of configuring your JupyterHub deployment.
+The [Getting Started](https://jupyterhub.readthedocs.io/en/latest/getting-started/index.html) section of the
+documentation explains the common steps in setting up JupyterHub.
 
-### Some examples
+The [**JupyterHub tutorial**](https://github.com/jupyterhub/jupyterhub-tutorial)
+provides an in-depth video and sample configurations of JupyterHub.
 
-Generate a default config file:
+### Create a configuration file
+
+To generate a default config file with settings and descriptions:
 
     jupyterhub --generate-config
 
-Spawn the server on ``10.0.1.2:443`` with **https**:
+### Start the Hub
+
+To start the Hub on a specific url and port ``10.0.1.2:443`` with **https**:
 
     jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
 
-The authentication and process spawning mechanisms can be replaced,
-which should allow plugging into a variety of authentication or process control environments.
-Some examples, meant as illustration and testing of this concept:
+### Authenticators
 
-- Using GitHub OAuth instead of PAM with [OAuthenticator](https://github.com/jupyter/oauthenticator)
-- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyter/dockerspawner)
+| Authenticator                                                               | Description                                       |
+| --------------------------------------------------------------------------- | ------------------------------------------------- |
+| PAMAuthenticator                                                            | Default, built-in authenticator                   |
+| [OAuthenticator](https://github.com/jupyterhub/oauthenticator)              | OAuth + JupyterHub Authenticator = OAuthenticator |
+| [ldapauthenticator](https://github.com/jupyterhub/ldapauthenticator)        | Simple LDAP Authenticator Plugin for JupyterHub   |
+| [kerberosauthenticator](https://github.com/jcrist/kerberosauthenticator)    | Kerberos Authenticator Plugin for JupyterHub      |
 
-### Docker
+### Spawners
 
-There is a ready to go [docker image for JupyterHub](https://hub.docker.com/r/jupyter/jupyterhub/).
-[Note: This `jupyter/jupyterhub` docker image is only an image for running the Hub service itself.
-It does not require the other Jupyter components, 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, installation of Jupyter Notebook ≥ 4 is required.]
+| 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                      |
+| [yarnspawner](https://github.com/jcrist/yarnspawner)           | Spawn single-user notebook servers distributed on a Hadoop cluster         |
+| [wrapspawner](https://github.com/jupyterhub/wrapspawner)       | WrapSpawner and ProfilesSpawner enabling runtime configuration of spawners |
+
+## Docker
+
+A starter [**docker image for JupyterHub**](https://hub.docker.com/r/jupyterhub/jupyterhub/)
+gives a baseline deployment of JupyterHub 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.
 
 The JupyterHub docker image can be started with the following command:
 
-    docker run -d --name jupyterhub jupyter/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`.
-It will be listening on all interfaces at port 8000, so this is perfect to test 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 it to create system users in the container. These accounts will be used for authentication
-in jupyterhub's default configuration. In order to run without SSL (for testing purposes only), you'll need to set `--no-ssl` explicitly.
+This command will create a container named `jupyterhub` that you can
+**stop and resume** with `docker stop/start`.
 
-# Getting help
+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**.
 
-We encourage you to ask questions on the mailing list:
+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.
 
-[![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+[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.
 
-and you may participate in development discussions or get live help on Gitter:
+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.
 
-[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter/jupyterhub?utm_source=badge&utm_medium=badge)
+## Contributing
 
-## Resources
+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.
+
+For a high-level view of the vision and next directions of the project, see the
+[JupyterHub community roadmap](docs/source/contributing/roadmap.md).
+
+### A note about platform support
+
+JupyterHub is supported on Linux/Unix based systems.
+
+JupyterHub officially **does not** support Windows. You may be able to use
+JupyterHub on Windows if you use a Spawner and Authenticator that work on
+Windows, but the JupyterHub defaults will not. Bugs reported on Windows will not
+be accepted, and the test suite will not run on Windows. Small patches that fix
+minor Windows compatibility issues (such as basic installation) **may** be accepted,
+however. For Windows-based systems, we would recommend running JupyterHub in a
+docker container or Linux VM.
+
+[Additional Reference:](http://www.tornadoweb.org/en/stable/#installation) Tornado's documentation on Windows platform support
+
+## License
+
+We use a shared copyright model that enables all contributors to maintain the
+copyright on their contributions.
+
+All code is licensed under the terms of the revised BSD license.
+
+## Help and resources
+
+We encourage you to ask questions on the [Jupyter mailing list](https://groups.google.com/forum/#!forum/jupyter).
+To participate in development discussions or get help, talk with us on
+our JupyterHub [Gitter](https://gitter.im/jupyterhub/jupyterhub) channel.
+
+- [Reporting Issues](https://github.com/jupyterhub/jupyterhub/issues)
+- [JupyterHub tutorial](https://github.com/jupyterhub/jupyterhub-tutorial)
+- [Documentation for JupyterHub](https://jupyterhub.readthedocs.io/en/latest/) | [PDF (latest)](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf) | [PDF (stable)](https://media.readthedocs.org/pdf/jupyterhub/stable/jupyterhub.pdf)
+- [Documentation for JupyterHub's REST API](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default)
+- [Documentation for Project Jupyter](http://jupyter.readthedocs.io/en/latest/index.html) | [PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)
 - [Project Jupyter website](https://jupyter.org)
-- [Documentation for JupyterHub](http://jupyterhub.readthedocs.org/en/latest/) [[PDF](https://media.readthedocs.org/pdf/jupyterhub/latest/jupyterhub.pdf)]
-- [Documentation for Project Jupyter](http://jupyter.readthedocs.org/en/latest/index.html) [[PDF](https://media.readthedocs.org/pdf/jupyter/latest/jupyter.pdf)]
-- [Issues](https://github.com/jupyter/jupyterhub/issues)
-- [Technical support - Jupyter Google Group](https://groups.google.com/forum/#!forum/jupyter)
+
+JupyterHub follows the Jupyter [Community Guides](https://jupyter.readthedocs.io/en/latest/community/content-community.html).
+
+---
+
+**[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,33 @@
+#!/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
+import shutil
+from os.path import join
+
+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,59 @@
+#!/usr/bin/env bash
+# source this file to setup postgres and mysql
+# for local testing (as similar as possible to docker)
+
+set -eu
+
+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
+
+case "$DB" in
+"mysql")
+  ;;
+"postgres")
+  # create the user
+  psql --user postgres -c "CREATE USER $PGUSER WITH PASSWORD '$PGPASSWORD';"
+  ;;
+*)
+esac
+
+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 -eu
+
+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 _upgrade_094; do
+    $SQL "DROP DATABASE jupyterhub${SUFFIX};" 2>/dev/null || true
+    $SQL "CREATE DATABASE jupyterhub${SUFFIX} ${EXTRA_CREATE:-};"
+done

circle.yml

@@ -1,19 +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:${CIRCLE_TAG:-latest}

dev-requirements.txt

@@ -1,5 +1,17 @@
 -r requirements.txt
+# temporary pin of attrs for jsonschema 0.3.0a1
+# seems to be a pip bug
+attrs>=17.4.0
+beautifulsoup4
 codecov
-pytest-cov
-pytest>=2.8
+coverage
+cryptography
+html5lib  # needed for beautifulsoup
+mock
 notebook
+pre-commit
+pytest-asyncio
+pytest-cov
+pytest>=3.3
+requests-mock
+virtualenv

dockerfiles/Dockerfile.alpine

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

docs/Makefile

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

docs/environment.yml

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

docs/package.json

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

docs/requirements.txt

@@ -1,3 +1,7 @@
+# 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
-recommonmark==0.4.0
+alabaster_jupyterhub
+recommonmark==0.5.0
+sphinx-copybutton
+sphinx>=1.7

docs/rest-api.yml

@@ -3,9 +3,11 @@ swagger: '2.0'
 info:
   title: JupyterHub
   description: The REST API for JupyterHub
-  version: 0.4.0
+  version: 0.9.0dev
+  license:
+    name: BSD-3-Clause
 schemes:
-  - http
+  - [http, https]
 securityDefinitions:
   token:
     type: apiKey
@@ -13,18 +15,73 @@ securityDefinitions:
     in: header
 security:
   - token: []
-basePath: /hub/api/
+basePath: /hub/api
 produces:
   - application/json
 consumes:
   - application/json
 paths:
+  /:
+    get:
+      summary: Get JupyterHub version
+      description: |
+        This endpoint is not authenticated for the purpose of clients and user
+        to identify the JupyterHub version before setting up authentication.
+      responses:
+        '200':
+          description: The JupyterHub version
+          schema:
+            type: object
+            properties:
+              version:
+                type: string
+                description: The version of JupyterHub itself
+  /info:
+    get:
+      summary: Get detailed info about JupyterHub
+      description: |
+        Detailed JupyterHub information, including Python version,
+        JupyterHub's version and executable path,
+        and which Authenticator and Spawner are active.
+      responses:
+        '200':
+          description: Detailed JupyterHub info
+          schema:
+            type: object
+            properties:
+              version:
+                type: string
+                description: The version of JupyterHub itself
+              python:
+                type: string
+                description: The Python version, as returned by sys.version
+              sys_executable:
+                type: string
+                description: The path to sys.executable running JupyterHub
+              authenticator:
+                type: object
+                properties:
+                  class:
+                    type: string
+                    description: The Python class currently active for JupyterHub Authentication
+                  version:
+                    type: string
+                    description: The version of the currently active Authenticator
+              spawner:
+                type: object
+                properties:
+                  class:
+                    type: string
+                    description: The Python class currently active for spawning single-user notebook servers
+                  version:
+                    type: string
+                    description: The version of the currently active Spawner
   /users:
     get:
       summary: List users
       responses:
         '200':
-          description: The user list
+          description: The Hub's user list
           schema:
             type: array
             items:
@@ -32,7 +89,7 @@ paths:
     post:
       summary: Create multiple users
       parameters:
-        - name: data
+        - name: body
           in: body
           required: true
           schema:
@@ -40,7 +97,7 @@ paths:
             properties:
               usernames:
                 type: array
-                description: list of usernames to create
+                description: list of usernames to create on the Hub
                 items:
                   type: string
               admin:
@@ -81,6 +138,33 @@ paths:
           description: The user has been created
           schema:
             $ref: '#/definitions/User'
+    patch:
+      summary: Modify a user
+      description: Change a user's name or admin status
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+        - name: body
+          in: body
+          required: true
+          description: Updated user info. At least one key to be updated (name or admin) is required.
+          schema:
+            type: object
+            properties:
+              name:
+                type: string
+                description: the new name (optional, if another key is updated i.e. admin)
+              admin:
+                type: boolean
+                description: update admin (optional, if another key is updated i.e. name)
+      responses:
+        '200':
+          description: The updated user info
+          schema:
+            $ref: '#/definitions/User'
     delete:
       summary: Delete a user
       parameters:
@@ -92,47 +176,83 @@ paths:
       responses:
         '204':
           description: The user has been deleted
-    patch:
-      summary: Modify a user
-      description: Change a user's name or admin status
+  /users/{name}/activity:
+    post:
+      summary:
+        Notify Hub of activity for a given user.
+      description:
+        Notify the Hub of activity by the user,
+        e.g. accessing a service or (more likely)
+        actively using a server.
       parameters:
         - name: name
           description: username
           in: path
           required: true
           type: string
-        - name: data
+        - body:
           in: body
-          required: true
-          description: Updated user info. At least one of name and admin is required.
           schema:
             type: object
             properties:
-              name:
+              last_activity:
                 type: string
-                description: the new name (optional)
-              admin:
-                type: boolean
-                description: update admin (optional)
-      responses:
-        '200':
-          description: The updated user info
-          schema:
-            $ref: '#/definitions/User'
+                format: date-time
+                description: |
+                  Timestamp of last-seen activity for this user.
+                  Only needed if this is not activity associated
+                  with using a given server.
+                required: false
+              servers:
+                description: |
+                  Register activity for specific servers by name.
+                  The keys of this dict are the names of servers.
+                  The default server has an empty name ('').
+                required: false
+                type: object
+                properties:
+                  '<server name>':
+                    description: |
+                      Activity for a single server.
+                    type: object
+                    properties:
+                      last_activity:
+                        required: true
+                        type: string
+                        format: date-time
+                        description: |
+                          Timestamp of last-seen activity on this server.
+          example:
+            last_activity: '2019-02-06T12:54:14Z'
+            servers:
+              '':
+                last_activity: '2019-02-06T12:54:14Z'
+              gpu:
+                last_activity: '2019-02-06T12:54:14Z'
+
   /users/{name}/server:
     post:
-      summary: Start a user's server
+      summary: Start a user's single-user notebook server
       parameters:
         - name: name
           description: username
           in: path
           required: true
           type: string
+        - options:
+          description: |
+            Spawn options can be passed as a JSON body
+            when spawning via the API instead of spawn form.
+            The structure of the options
+            will depend on the Spawner's configuration.
+          in: body
+          required: false
+          type: object
       responses:
         '201':
-          description: The server has started
+          description: The user's notebook server has started
         '202':
-          description: The server has been requested, but has not yet started
+          description: The user's notebook server has not yet started, but has been requested
     delete:
       summary: Stop a user's server
       parameters:
@@ -143,41 +263,251 @@ paths:
           type: string
       responses:
         '204':
-          description: The server has stopped
+          description: The user's notebook server has stopped
         '202':
-          description: The server has been asked to stop, but is taking a while
-  /users/{name}/admin-access:
+          description: The user's notebook server has not yet stopped as it is taking a while to stop
+  /users/{name}/servers/{server_name}:
     post:
-      summary: Grant an admin access to this user's server
+      summary: Start a user's single-user named-server notebook server
       parameters:
         - name: name
           description: username
           in: path
           required: true
           type: string
+        - name: server_name
+          description: name given to a named-server
+          in: path
+          required: true
+          type: string
+        - options:
+          description: |
+            Spawn options can be passed as a JSON body
+            when spawning via the API instead of spawn form.
+            The structure of the options
+            will depend on the Spawner's configuration.
+          in: body
+          required: false
+          type: object
+      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
+        - name: remove
+          description: |
+            Whether to fully remove the server, rather than just stop it.
+            Removing a server deletes things like the state of the stopped server.
+          in: body
+          required: false
+          type: boolean
+      responses:
+        '204':
+          description: The user's notebook named-server has stopped
+        '202':
+          description: The user's notebook named-server has not yet stopped as it is taking a while to stop
+  /users/{name}/tokens:
+    get:
+      summary: List tokens for the user
       responses:
         '200':
-          description: Sets a cookie granting the requesting admin access to the user's server
+          description: The list of tokens
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Token'
+    post:
+      summary: Create a new token for the user
+      parameters:
+        - name: expires_in
+          type: number
+          required: false
+          in: body
+          description: lifetime (in seconds) after which the requested token will expire.
+        - name: note
+          type: string
+          required: false
+          in: body
+          description: A note attached to the token for future bookkeeping
+      responses:
+        '201':
+          description: The newly created token
+          schema:
+            $ref: '#/definitions/Token'
+  /users/{name}/tokens/{token_id}:
+    get:
+      summary: Get the model for a token by id
+      responses:
+        '200':
+          description: The info for the new token
+          schema:
+            $ref: '#/definitions/Token'
+    delete:
+      summary: Delete (revoke) a token by id
+      responses:
+        '204':
+          description: The token has been deleted
+  /user:
+    summary: Return authenticated user's model
+    description:
+    parameters:
+    responses:
+      '200':
+        description: The authenticated user's model is returned.
+  /groups:
+    get:
+      summary: List groups
+      responses:
+        '200':
+          description: The list of groups
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Group'
+  /groups/{name}:
+    get:
+      summary: Get a group by name
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: The group model
+          schema:
+            $ref: '#/definitions/Group'
+    post:
+      summary: Create a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '201':
+          description: The group has been created
+          schema:
+            $ref: '#/definitions/Group'
+    delete:
+      summary: Delete a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The group has been deleted
+  /groups/{name}/users:
+    post:
+      summary: Add users to a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+        - name: body
+          in: body
+          required: true
+          description: The users to add to the group
+          schema:
+            type: object
+            properties:
+              users:
+                type: array
+                description: List of usernames to add to the group
+                items:
+                  type: string
+      responses:
+        '200':
+          description: The users have been added to the group
+          schema:
+            $ref: '#/definitions/Group'
+    delete:
+      summary: Remove users from a group
+      parameters:
+        - name: name
+          description: group name
+          in: path
+          required: true
+          type: string
+        - name: body
+          in: body
+          required: true
+          description: The users to remove from the group
+          schema:
+            type: object
+            properties:
+              users:
+                type: array
+                description: List of usernames to remove from the group
+                items:
+                  type: string
+      responses:
+        '200':
+          description: The users have been removed from the group
+  /services:
+    get:
+      summary: List services
+      responses:
+        '200':
+          description: The service list
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Service'
+  /services/{name}:
+    get:
+      summary: Get a service by name
+      parameters:
+        - name: name
+          description: service name
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: The Service model
+          schema:
+            $ref: '#/definitions/Service'
   /proxy:
     get:
       summary: Get the proxy's routing table
-      description: A convenience alias for getting the info directly from the proxy
+      description: A convenience alias for getting the routing table directly from the proxy
       responses:
         '200':
           description: Routing table
           schema:
             type: object
-            description: configurable-http-proxy routing table (see CHP docs for details)
+            description: configurable-http-proxy routing table (see configurable-http-proxy docs for details)
     post:
       summary: Force the Hub to sync with the proxy
       responses:
         '200':
           description: Success
     patch:
-      summary: Tell the Hub about a new proxy
-      description: If you have started a new proxy and would like the Hub to switch over to it, this allows you to notify the Hub of the new proxy.
+      summary: Notify the Hub about a new proxy
+      description: Notifies the Hub of a new proxy to use.
       parameters:
-        - name: data
+        - name: body
           in: body
           required: true
           description: Any values that have changed for the new proxy. All keys are optional.
@@ -199,9 +529,38 @@ paths:
       responses:
         '200':
           description: Success
+  /authorizations/token:
+    post:
+      summary: Request a new API token
+      description: |
+        Request a new API token to use with the JupyterHub REST API.
+        If not already authenticated, username and password can be sent
+        in the JSON request body.
+        Logging in via this method is only available when the active Authenticator
+        accepts passwords (e.g. not OAuth).
+      parameters:
+        - name: username
+          in: body
+          required: false
+          type: string
+        - name: password
+          in: body
+          required: false
+          type: string
+      responses:
+        '200':
+          description: The new API token
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+                description: The new API token.
+        '403':
+          description: The user can not be authenticated.
   /authorizations/token/{token}:
     get:
-      summary: Identify a user from an API token
+      summary: Identify a user or service from an API token
       parameters:
       - name: token
         in: path
@@ -209,13 +568,13 @@ paths:
         type: string
       responses:
         '200':
-          description: The user identified by the API token
-          schema:
-            $ref: '#!/definitions/User'
+          description: The user or service identified by the API token
+        '404':
+          description: A user or service is not found.
   /authorizations/cookie/{cookie_name}/{cookie_value}:
     get:
       summary: Identify a user from a cookie
-      description: Used by single-user servers to hand off cookie authentication to the Hub
+      description: Used by single-user notebook servers to hand off cookie authentication to the Hub
       parameters:
       - name: cookie_name
         in: path
@@ -229,13 +588,94 @@ paths:
         '200':
           description: The user identified by the cookie
           schema:
-            $ref: '#!/definitions/User'
+            $ref: '#/definitions/User'
+        '404':
+          description: A user is not found.
+  /oauth2/authorize:
+    get:
+      summary: 'OAuth 2.0 authorize endpoint'
+      description: |
+        Redirect users to this URL to begin the OAuth process.
+        It is not an API endpoint.
+      parameters:
+        - name: client_id
+          description: The client id
+          in: query
+          required: true
+          type: string
+        - name: response_type
+          description: The response type (always 'code')
+          in: query
+          required: true
+          type: string
+        - name: state
+          description: A state string
+          in: query
+          required: false
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: query
+          required: true
+          type: string
+  /oauth2/token:
+    post:
+      summary: Request an OAuth2 token
+      description: |
+        Request an OAuth2 token from an authorization code.
+        This request completes the OAuth process.
+      consumes:
+        - application/x-www-form-urlencoded
+      parameters:
+        - name: client_id
+          description: The client id
+          in: form
+          required: true
+          type: string
+        - name: client_secret
+          description: The client secret
+          in: form
+          required: true
+          type: string
+        - name: grant_type
+          description: The grant type (always 'authorization_code')
+          in: form
+          required: true
+          type: string
+        - name: code
+          description: The code provided by the authorization redirect
+          in: form
+          required: true
+          type: string
+        - name: redirect_uri
+          description: The redirect url
+          in: form
+          required: true
+          type: string
+      responses:
+        '200':
+          description: JSON response including the token
+          schema:
+            type: object
+            properties:
+              access_token:
+                type: string
+                description: The new API token for the user
+              token_type:
+                type: string
+                description: Will always be 'Bearer'
   /shutdown:
     post:
       summary: Shutdown the Hub
-      responses:
-        '200':
-          description: Hub has shutdown
+      parameters:
+        - name: proxy
+          in: body
+          type: boolean
+          description: Whether the proxy should be shutdown as well (default from Hub config)
+        - name: servers
+          in: body
+          type: boolean
+          description: Whether users' notebook servers should be shutdown as well (default from Hub config)
 definitions:
   User:
     type: object
@@ -246,14 +686,133 @@ definitions:
       admin:
         type: boolean
         description: Whether the user is an admin
+      groups:
+        type: array
+        description: The names of groups where this user is a member
+        items:
+          type: string
       server:
         type: string
-        description: The user's server's base URL, if running; null if not.
+        description: The user's notebook server's base URL, if running; null if not.
       pending:
         type: string
-        enum: ["spawn", "stop"]
+        enum: ["spawn", "stop", null]
         description: The currently pending action, if any
       last_activity:
         type: string
-        format: ISO8601 Timestamp
+        format: date-time
         description: Timestamp of last-seen activity from the user
+      servers:
+        type: object
+        description: The active servers for this user.
+        items:
+          schema:
+            $ref: '#/definitions/Server'
+  Server:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The server's name. The user's default server has an empty name ('')
+      ready:
+        type: boolean
+        description: |
+          Whether the server is ready for traffic.
+          Will always be false when any transition is pending.
+      pending:
+        type: string
+        enum: ["spawn", "stop", null]
+        description: |
+          The currently pending action, if any.
+          A server is not ready if an action is pending.
+      url:
+        type: string
+        description: |
+          The URL where the server can be accessed
+          (typically /user/:name/:server.name/).
+      progress_url:
+        type: string
+        description: |
+          The URL for an event-stream to retrieve events during a spawn.
+      started:
+        type: string
+        format: date-time
+        description: UTC timestamp when the server was last started.
+      last_activity:
+        type: string
+        format: date-time
+        description: UTC timestamp last-seen activity on this server.
+      state:
+        type: object
+        description: Arbitrary internal state from this server's spawner.  Only available on the hub's users list or get-user-by-name method, and only if a hub admin.  None otherwise.
+  Group:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The group's name
+      users:
+        type: array
+        description: The names of users who are members of this group
+        items:
+          type: string
+  Service:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The service's name
+      admin:
+        type: boolean
+        description: Whether the service is an admin
+      url:
+        type: string
+        description: The internal url where the service is running
+      prefix:
+        type: string
+        description: The proxied URL prefix to the service's url
+      pid:
+        type: number
+        description: The PID of the service process (if managed)
+      command:
+        type: array
+        description: The command used to start the service (if managed)
+        items:
+          type: string
+      info:
+        type: object
+        description: |
+          Additional information a deployment can attach to a service.
+          JupyterHub does not use this field.
+  Token:
+    type: object
+    properties:
+      token:
+        type: string
+        description: The token itself. Only present in responses to requests for a new token.
+      id:
+        type: string
+        description: The id of the API token. Used for modifying or deleting the token.
+      user:
+        type: string
+        description: The user that owns a token (undefined if owned by a service)
+      service:
+        type: string
+        description: The service that owns the token (undefined of owned by a user)
+      note:
+        type: string
+        description: A note about the token, typically describing what it was created for.
+      created:
+        type: string
+        format: date-time
+        description: Timestamp when this token was created
+      expires_at:
+        type: string
+        format: date-time
+        description: Timestamp when this token expires. Null if there is no expiry.
+      last_activity:
+        type: string
+        format: date-time
+        description: |
+          Timestamp of last-seen activity using this token.
+          Can be null if token has never been used.

docs/source/_static/custom.css

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

docs/source/_templates/navigation.html

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

docs/source/_templates/page.html

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

docs/source/_templates/relations.html

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

docs/source/admin/upgrading.rst

@@ -0,0 +1,159 @@
+.. _admin/upgrading:
+
+====================
+Upgrading JupyterHub
+====================
+
+JupyterHub offers easy upgrade pathways between minor versions. This
+document describes how to do these upgrades.
+
+If you are using :ref:`a JupyterHub distribution <index/distributions>`, you
+should consult the distribution's documentation on how to upgrade. This
+document is if you have set up your own JupyterHub without using a
+distribution.
+
+It is long because is pretty detailed! Most likely, upgrading
+JupyterHub is painless, quick and with minimal user interruption.
+
+Read the Changelog
+==================
+
+The `changelog <changelog.html>`_ contains information on what has
+changed with the new JupyterHub release, and any deprecation warnings.
+Read these notes to familiarize yourself with the coming changes. There
+might be new releases of authenticators & spawners you are using, so
+read the changelogs for those too!
+
+Notify your users
+=================
+
+If you are using the default configuration where ``configurable-http-proxy``
+is managed by JupyterHub, your users will see service disruption during
+the upgrade process. You should notify them, and pick a time to do the
+upgrade where they will be least disrupted.
+
+If you are using a different proxy, or running ``configurable-http-proxy``
+independent of JupyterHub, your users will be able to continue using notebook
+servers they had already launched, but will not be able to launch new servers
+nor sign in.
+
+
+Backup database & config
+========================
+
+Before doing an upgrade, it is critical to back up:
+
+#. Your JupyterHub database (sqlite by default, or MySQL / Postgres
+   if you used those). If you are using sqlite (the default), you
+   should backup the ``jupyterhub.sqlite`` file.
+#. Your ``jupyterhub_config.py`` file.
+#. Your user's home directories. This is unlikely to be affected directly by
+   a JupyterHub upgrade, but we recommend a backup since user data is very
+   critical.
+
+
+Shutdown JupyterHub
+===================
+
+Shutdown the JupyterHub process. This would vary depending on how you
+have set up JupyterHub to run. Most likely, it is using a process
+supervisor of some sort (``systemd`` or ``supervisord`` or even ``docker``).
+Use the supervisor specific command to stop the JupyterHub process.
+
+Upgrade JupyterHub packages
+===========================
+
+There are two environments where the ``jupyterhub`` package is installed:
+
+#. The *hub environment*, which is where the JupyterHub server process
+   runs. This is started with the ``jupyterhub`` command, and is what
+   people generally think of as JupyterHub.
+
+#. The *notebook user environments*. This is where the user notebook
+   servers are launched from, and is probably custom to your own
+   installation. This could be just one environment (different from the
+   hub environment) that is shared by all users, one environment
+   per user, or same environment as the hub environment. The hub
+   launched the ``jupyterhub-singleuser`` command in this environment,
+   which in turn starts the notebook server.
+
+You need to make sure the version of the ``jupyterhub`` package matches
+in both these environments. If you installed ``jupyterhub`` with pip,
+you can upgrade it with:
+
+.. code-block:: bash
+
+   python3 -m pip install --upgrade jupyterhub==<version>
+
+Where ``<version>`` is the version of JupyterHub you are upgrading to.
+
+If you used ``conda`` to install ``jupyterhub``, you should upgrade it
+with:
+
+.. code-block:: bash
+
+   conda install -c conda-forge jupyterhub==<version>
+
+Where ``<version>`` is the version of JupyterHub you are upgrading to.
+
+You should also check for new releases of the authenticator & spawner you
+are using. You might wish to upgrade those packages too along with JupyterHub,
+or upgrade them separately.
+
+Upgrade JupyterHub database
+===========================
+
+Once new packages are installed, you need to upgrade the JupyterHub
+database. From the hub environment, in the same directory as your
+``jupyterhub_config.py`` file, you should run:
+
+.. code-block:: bash
+
+   jupyterhub upgrade-db
+
+This should find the location of your database, and run necessary upgrades
+for it.
+
+SQLite database disadvantages
+-----------------------------
+
+SQLite has some disadvantages when it comes to upgrading JupyterHub. These
+are:
+
+-  ``upgrade-db`` may not work, and you may need delete your database
+   and start with a fresh one.
+-  ``downgrade-db`` **will not** work if you want to rollback to an
+   earlier version, so backup the ``jupyterhub.sqlite`` file before
+   upgrading
+
+What happens if I delete my database?
+-------------------------------------
+
+Losing the Hub database is often not a big deal. Information that
+resides only in the Hub database includes:
+
+-  active login tokens (user cookies, service tokens)
+-  users added via JupyterHub 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, or login using an external
+   authentication provider (Google, GitHub, LDAP, etc)
+-  user servers are stopped during upgrade
+-  don't mind causing users to login again after upgrade
+
+Start JupyterHub
+================
+
+Once the database upgrade is completed, start the ``jupyterhub``
+process again.
+
+#. Log-in and start the server to make sure things work as
+   expected.
+#. Check the logs for any errors or deprecation warnings. You
+   might have to update your ``jupyterhub_config.py`` file to
+   deal with any deprecated options.
+
+Congratulations, your JupyterHub has been upgraded!

docs/source/api/app.rst

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

docs/source/api/auth.rst

@@ -9,13 +9,24 @@ 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
+
+:class:`DummyAuthenticator`
+---------------------------
+
+.. autoconfigurable:: DummyAuthenticator

docs/source/api/index.rst

@@ -1,14 +1,38 @@
 .. _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 <../reference/rest.html>`_ provides
+information on:
+
+- what you can do with the API
+- creating an API token
+- adding API tokens to the config files
+- making an API request programmatically using the requests library
+- learning more about JupyterHub's API
+
+The same JupyterHub API spec, as found here, is available in an interactive form
+`here (on swagger's petstore) <http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default>`__.
+The `OpenAPI Initiative`_ (fka Swagger™) is a project used to describe
+and document RESTful APIs.
+
+JupyterHub API Reference:
+
 .. toctree::
 
+    app
     auth
     spawner
+    proxy
     user
+    service
+    services.auth
+
+
+.. _OpenAPI Initiative: https://www.openapis.org/

docs/source/api/proxy.rst

@@ -0,0 +1,22 @@
+=======
+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,16 @@
+========
+Services
+========
+
+Module: :mod:`jupyterhub.services.service`
+==========================================
+
+.. automodule:: jupyterhub.services.service
+
+.. currentmodule:: jupyterhub.services.service
+
+:class:`Service`
+----------------
+
+.. autoconfigurable:: Service
+    :members: name, admin, url, api_token, managed, kind, command, cwd, environment, user, oauth_client_id, server, prefix, proxy_spec

docs/source/api/services.auth.rst

@@ -0,0 +1,40 @@
+=======================
+Services Authentication
+=======================
+
+Module: :mod:`jupyterhub.services.auth`
+=======================================
+
+.. automodule:: jupyterhub.services.auth
+
+.. currentmodule:: jupyterhub.services.auth
+
+
+:class:`HubAuth`
+----------------
+
+.. autoconfigurable:: HubAuth
+    :members:
+
+:class:`HubOAuth`
+-----------------
+
+.. autoconfigurable:: HubOAuth
+    :members:
+
+
+:class:`HubAuthenticated`
+-------------------------
+
+.. autoclass:: HubAuthenticated
+    :members:
+
+:class:`HubOAuthenticated`
+--------------------------
+
+.. autoclass:: HubOAuthenticated
+
+:class:`HubOAuthCallbackHandler`
+--------------------------------
+
+.. autoclass:: HubOAuthCallbackHandler

docs/source/api/spawner.rst

@@ -1,6 +1,6 @@
-==============
+========
 Spawners
-==============
+========
 
 Module: :mod:`jupyterhub.spawner`
 =================================
@@ -12,7 +12,10 @@ Module: :mod:`jupyterhub.spawner`
 :class:`Spawner`
 ----------------
 
-.. autoclass:: Spawner
-    :members: options_from_form, poll, start, stop, get_args, get_env, get_state
+.. autoconfigurable:: Spawner
+    :members: options_from_form, poll, start, stop, get_args, get_env, get_state, template_namespace, format_string, create_certs, move_certs
 
-.. 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
     

docs/source/authenticators.md

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

docs/source/changelog.md

@@ -1,9 +1,521 @@
-# Summary of changes in JupyterHub
+# Changelog
 
-See `git log` for a more detailed summary.
+For detailed changes from the prior release, click on the version number, and
+its link will bring up a GitHub listing of changes. Use `git log` on the
+command line for details.
+
+
+## [Unreleased]
+
+## 1.0
+
+### [1.0.0] 2019-05-03
+
+JupyterHub 1.0 is a major milestone for JupyterHub.
+Huge thanks to the many people who have contributed to this release,
+whether it was through discussion, testing, documentation, or development.
+
+#### Major new features
+
+- Support TLS encryption and authentication of all internal communication.
+  Spawners must implement `.move_certs` method to make certificates available
+  to the notebook server if it is not local to the Hub.
+- There is now full UI support for managing named servers.
+  With named servers, each jupyterhub user may have access to more than one named server. For example, a professor may access a server named `research` and another named `teaching`.
+
+  ![named servers on the home page](./images/named-servers-home.png)
+- Authenticators can now expire and refresh authentication data by implementing
+  `Authenticator.refresh_user(user)`.
+  This allows things like OAuth data and access tokens to be refreshed.
+  When used together with `Authenticator.refresh_pre_spawn = True`,
+  auth refresh can be forced prior to Spawn,
+  allowing the Authenticator to *require* that authentication data is fresh
+  immediately before the user's server is launched.
+
+```eval_rst
+.. seealso::
+
+  - :meth:`.Authenticator.refresh_user`
+  - :meth:`.Spawner.create_certs`
+  - :meth:`.Spawner.move_certs`
+```
+
+#### New features
+
+- allow custom spawners, authenticators, and proxies to register themselves via 'entry points', enabling more convenient configuration such as:
+
+  ```python
+  c.JupyterHub.authenticator_class = 'github'
+  c.JupyterHub.spawner_class = 'docker'
+  c.JupyterHub.proxy_class = 'traefik_etcd'
+  ```
+- Spawners are passed the tornado Handler object that requested their spawn (as `self.handler`),
+  so they can do things like make decisions based on query arguments in the request.
+- SimpleSpawner and DummyAuthenticator, which are useful for testing, have been merged into JupyterHub itself:
+
+  ```python
+  # For testing purposes only. Should not be used in production.
+  c.JupyterHub.authenticator_class = 'dummy'
+  c.JupyterHub.spawner_class = 'simple'
+  ```
+
+  These classes are **not** appropriate for production use. Only testing.
+- Add health check endpoint at `/hub/health`
+- Several prometheus metrics have been added (thanks to [Outreachy](https://www.outreachy.org/) applicants!)
+- A new API for registering user activity.
+  To prepare for the addition of [alternate proxy implementations](https://github.com/jupyterhub/traefik-proxy),
+  responsibility for tracking activity is taken away from the proxy
+  and moved to the notebook server (which already has activity tracking features).
+  Activity is now tracked by pushing it to the Hub from user servers instead of polling the
+  proxy API.
+- Dynamic `options_form` callables may now return an empty string
+  which will result in no options form being rendered.
+- `Spawner.user_options` is persisted to the database to be re-used,
+  so that a server spawned once via the form can be re-spawned via the API
+  with the same options.
+- Added `c.PAMAuthenticator.pam_normalize_username` option for round-tripping
+  usernames through PAM to retrieve the normalized form.
+- Added `c.JupyterHub.named_server_limit_per_user` configuration to limit
+  the number of named servers each user can have.
+  The default is 0, for no limit.
+- API requests to HubAuthenticated services (e.g. single-user servers)
+  may pass a token in the `Authorization` header,
+  matching authentication with the Hub API itself.
+- Added `Authenticator.is_admin(handler, authentication)` method
+  and `Authenticator.admin_groups` configuration for automatically
+  determining that a member of a group should be considered an admin.
+- New `c.Authenticator.post_auth_hook` configuration
+  that can be any callable of the form `async def hook(authenticator, handler, authentication=None):`.
+  This hook may transform the return value of `Authenticator.authenticate()`
+  and return a new authentication dictionary,
+  e.g. specifying admin privileges, group membership,
+  or custom white/blacklisting logic.
+  This hook is called *after* existing normalization and whitelist checking.
+- `Spawner.options_from_form` may now be async
+- Added `JupyterHub.shutdown_on_logout` option to trigger shutdown of a user's
+  servers when they log out.
+- When `Spawner.start` raises an Exception,
+  a message can be passed on to the user if the exception has a `.jupyterhub_message` attribute.
+
+
+#### Changes
+
+- Authentication methods such as `check_whitelist` should now take an additional
+  `authentication` argument
+  that will be a dictionary (default: None) of authentication data,
+  as returned by `Authenticator.authenticate()`:
+
+  ```python
+  def check_whitelist(self, username, authentication=None):
+      ...
+  ```
+
+  `authentication` should have a default value of None
+  for backward-compatibility with jupyterhub < 1.0.
+- Prometheus metrics page is now authenticated.
+  Any authenticated user may see the prometheus metrics.
+  To disable prometheus authentication,
+  set `JupyterHub.authenticate_prometheus = False`.
+- Visits to `/user/:name` no longer trigger an implicit launch of the user's server.
+  Instead, a page is shown indicating that the server is not running
+  with a link to request the spawn.
+- API requests to `/user/:name` for a not-running server will have status 503 instead of 404.
+- OAuth includes a confirmation page when attempting to visit another user's server,
+  so that users can choose to cancel authentication with the single-user server.
+  Confirmation is still skipped when accessing your own server.
+
+
+#### Fixed
+
+- Various fixes to improve Windows compatibility
+  (default Authenticator and Spawner still do not support Windows, but other Spawners may)
+- Fixed compatibility with Oracle db
+- Fewer redirects following a visit to the default `/` url
+- Error when progress is requested before progress is ready
+- Error when API requests are made to a not-running server without authentication
+- Avoid logging database password on connect if password is specified in `JupyterHub.db_url`.
+
+#### Development changes
+
+There have been several changes to the development process that shouldn't
+generally affect users of JupyterHub, but may affect contributors.
+In general, see `CONTRIBUTING.md` for contribution info or ask if you have questions.
+
+- JupyterHub has adopted `black` as a code autoformatter and `pre-commit`
+  as a tool for automatically running code formatting on commit.
+  This is meant to make it *easier* to contribute to JupyterHub,
+  so let us know if it's having the opposite effect.
+- JupyterHub has switched its test suite to using `pytest-asyncio` from `pytest-tornado`.
+- OAuth is now implemented internally using `oauthlib` instead of `python-oauth2`. This should have no effect on behavior.
+
+
+## 0.9
+
+### [0.9.6] 2019-04-01
+
+JupyterHub 0.9.6 is a security release.
+
+- Fixes an Open Redirect vulnerability (CVE-2019-10255).
+
+JupyterHub 0.9.5 included a partial fix for this issue.
+
+### [0.9.4] 2018-09-24
+
+JupyterHub 0.9.4 is a small bugfix release.
+
+- Fixes an  issue that required all running user servers to be restarted
+  when performing an upgrade from 0.8 to 0.9.
+- Fixes content-type for API endpoints back to `application/json`.
+  It was `text/html` in 0.9.0-0.9.3.
+
+### [0.9.3] 2018-09-12
+
+JupyterHub 0.9.3 contains small bugfixes and improvements
+
+- Fix token page and model handling of `expires_at`.
+  This field was missing from the REST API model for tokens
+  and could cause the token page to not render
+- Add keep-alive to progress event stream to avoid proxies dropping
+  the connection due to inactivity
+- Documentation and example improvements
+- Disable quit button when using notebook 5.6
+- Prototype new feature (may change prior to 1.0):
+  pass requesting Handler to Spawners during start,
+  accessible as `self.handler`
+
+### [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 additional tornado RequestHandlers attached to the Hub.
+- API tokens may now expire.
+  Expiry is available in the REST model as `expires_at`,
+  and settable when creating API tokens by specifying `expires_in`.
+
+
+#### Fixed
+
+- Remove green from theme to improve accessibility
+- Fix error when proxy deletion fails due to route already being deleted
+- clear `?redirects` from URL on successful launch
+- disable send2trash by default, which is rarely desirable for jupyterhub
+- Put PAM calls in a thread so they don't block the main application
+  in cases where PAM is slow (e.g. LDAP).
+- Remove implicit spawn from login handler,
+  instead relying on subsequent request for `/user/:name` to trigger spawn.
+- Fixed several inconsistencies for initial redirects,
+  depending on whether server is running or not and whether the user is logged in or not.
+- Admin requests for  `/user/:name` (when admin-access is enabled) launch the right server if it's not running instead of redirecting to their own.
+- Major performance improvement starting up JupyterHub with many users,
+  especially when most are inactive.
+- Various fixes in race conditions and performance improvements with the default proxy.
+- Fixes for CORS headers
+- Stop setting `.form-control` on spawner form inputs unconditionally.
+- Better recovery from database errors and database connection issues
+  without having to restart the Hub.
+- Fix handling of `~` character in usernames.
+- Fix jupyterhub startup when `getpass.getuser()` would fail,
+  e.g. due to missing entry in passwd file in containers.
+
+
+## 0.8
+
+### [0.8.1] 2017-11-07
+
+JupyterHub 0.8.1 is a collection of bugfixes and small improvements on 0.8.
+
+#### Added
+
+- Run tornado with AsyncIO by default
+- Add `jupyterhub --upgrade-db` flag for automatically upgrading the database as part of startup.
+  This is useful for cases where manually running `jupyterhub upgrade-db`
+  as a separate step is unwieldy.
+- Avoid creating backups of the database when no changes are to be made by
+  `jupyterhub upgrade-db`.
+
+#### Fixed
+
+- Add some further validation to usernames - `/` is not allowed in usernames.
+- Fix empty logout page when using auto_login
+- Fix autofill of username field in default login form.
+- Fix listing of users on the admin page who have not yet started their server.
+- Fix ever-growing traceback when re-raising Exceptions from spawn failures.
+- Remove use of deprecated `bower` for javascript client dependencies.
+
+
+### [0.8.0] 2017-10-03
+
+JupyterHub 0.8 is a big release!
+
+Perhaps the biggest change is the use of OAuth to negotiate authentication
+between the Hub and single-user services.
+Due to this change, it is important that the single-user server
+and Hub are both running the same version of JupyterHub.
+If you are using containers (e.g. via DockerSpawner or KubeSpawner),
+this means upgrading jupyterhub in your user images at the same time as the Hub.
+In most cases, a
+
+    pip install jupyterhub==version
+
+in your Dockerfile is sufficient.
+
+#### Added
+
+- JupyterHub now defined a `Proxy` API for custom
+  proxy implementations other than the default.
+  The defaults are unchanged,
+  but configuration of the proxy is now done on the `ConfigurableHTTPProxy` class instead of the top-level JupyterHub.
+  TODO: docs for writing a custom proxy.
+- Single-user servers and services
+  (anything that uses HubAuth)
+  can now accept token-authenticated requests via the Authentication header.
+- Authenticators can now store state in the Hub's database.
+  To do so, the `authenticate` method should return a dict of the form
+
+  ```python
+  {
+      'username': 'name',
+      'state': {}
+  }
+  ```
+
+  This data will be encrypted and requires `JUPYTERHUB_CRYPT_KEY` environment variable to be set
+  and the `Authenticator.enable_auth_state` flag to be True.
+  If these are not set, auth_state returned by the Authenticator will not be stored.
+- There is preliminary support for multiple (named) servers per user in the REST API.
+  Named servers can be created via API requests, but there is currently no UI for managing them.
+- Add `LocalProcessSpawner.popen_kwargs` and `LocalProcessSpawner.shell_cmd`
+  for customizing how user server processes are launched.
+- Add `Authenticator.auto_login` flag for skipping the "Login with..." page explicitly.
+- Add `JupyterHub.hub_connect_ip` configuration
+  for the ip that should be used when connecting to the Hub.
+  This is promoting (and deprecating) `DockerSpawner.hub_ip_connect`
+  for use by all Spawners.
+- Add `Spawner.pre_spawn_hook(spawner)` hook for customizing
+  pre-spawn events.
+- Add `JupyterHub.active_server_limit` and `JupyterHub.concurrent_spawn_limit`
+  for limiting the total number of running user servers and the number of pending spawns, respectively.
+
+
+#### Changed
+
+- more arguments to spawners are now passed via environment variables (`.get_env()`)
+  rather than CLI arguments (`.get_args()`)
+- internally generated tokens no longer get extra hash rounds,
+  significantly speeding up authentication.
+  The hash rounds were deemed unnecessary because the tokens were already
+  generated with high entropy.
+- `JUPYTERHUB_API_TOKEN` env is available at all times,
+  rather than being removed during single-user start.
+  The token is now accessible to kernel processes,
+  enabling user kernels to make authenticated API requests to Hub-authenticated services.
+- Cookie secrets should be 32B hex instead of large base64 secrets.
+- pycurl is used by default, if available.
+
+#### Fixed
+
+So many things fixed!
+
+- Collisions are checked when users are renamed
+- Fix bug where OAuth authenticators could not logout users
+  due to being redirected right back through the login process.
+- If there are errors loading your config files,
+  JupyterHub will refuse to start with an informative error.
+  Previously, the bad config would be ignored and JupyterHub would launch with default configuration.
+- Raise 403 error on unauthorized user rather than redirect to login,
+  which could cause redirect loop.
+- Set `httponly` on cookies because it's prudent.
+- Improve support for MySQL as the database backend
+- Many race conditions and performance problems under heavy load have been fixed.
+- Fix alembic tagging of database schema versions.
+
+#### Removed
+
+- End support for Python 3.3 
+
+## 0.7
+
+### [0.7.2] - 2017-01-09
+
+#### Added
+
+- Support service environment variables and defaults in `jupyterhub-singleuser`
+  for easier deployment of notebook servers as a Service.
+- Add `--group` parameter for deploying `jupyterhub-singleuser` as a Service with group authentication.
+- Include URL parameters when redirecting through `/user-redirect/`
+
+### Fixed
+
+- Fix group authentication for HubAuthenticated services
+
+### [0.7.1] - 2017-01-02
+
+#### Added
+
+- `Spawner.will_resume` for signaling that a single-user server is paused instead of stopped.
+  This is needed for cases like `DockerSpawner.remove_containers = False`,
+  where the first API token is re-used for subsequent spawns.
+- Warning on startup about single-character usernames,
+   caused by common `set('string')` typo in config.
+
+#### Fixed
+
+- Removed spurious warning about empty `next_url`, which is AOK.
+
+### [0.7.0] - 2016-12-2
+
+#### Added
+
+- Implement Services API [\#705](https://github.com/jupyterhub/jupyterhub/pull/705)
+- Add `/api/` and `/api/info` endpoints [\#675](https://github.com/jupyterhub/jupyterhub/pull/675)
+- Add documentation for JupyterLab, pySpark configuration, troubleshooting,
+  and more.
+- Add logging of error if adding users already in database.  [\#689](https://github.com/jupyterhub/jupyterhub/pull/689)
+- Add HubAuth class for authenticating with JupyterHub. This class can
+  be used by any application, even outside tornado.
+- Add user groups.
+- Add `/hub/user-redirect/...` URL for redirecting users to a file on their own server.
+
+
+#### Changed
+
+- Always install with setuptools but not eggs (effectively require
+  `pip install .`) [\#722](https://github.com/jupyterhub/jupyterhub/pull/722)
+- Updated formatting of changelog. [\#711](https://github.com/jupyterhub/jupyterhub/pull/711)
+- Single-user server is provided by JupyterHub package, so single-user servers depend on JupyterHub now.
+
+#### Fixed
+
+- Fix docker repository location [\#719](https://github.com/jupyterhub/jupyterhub/pull/719)
+- Fix swagger spec conformance and timestamp type in API spec
+- Various redirect-loop-causing bugs have been fixed.
+
+
+#### Removed
+
+- Deprecate `--no-ssl` command line option. It has no meaning and warns if
+  used. [\#789](https://github.com/jupyterhub/jupyterhub/pull/789)
+- Deprecate `%U` username substitution in favor of `{username}`. [\#748](https://github.com/jupyterhub/jupyterhub/pull/748)
+- Removed deprecated SwarmSpawner link.  [\#699](https://github.com/jupyterhub/jupyterhub/pull/699)
 
 ## 0.6
 
+### [0.6.1] - 2016-05-04
+
+Bugfixes on 0.6:
+
+- statsd is an optional dependency, only needed if in use
+- Notice more quickly when servers have crashed
+- Better error pages for proxy errors
+- Add Stop All button to admin panel for stopping all servers at once
+
+### [0.6.0] - 2016-04-25
+
 - JupyterHub has moved to a new `jupyterhub` namespace on GitHub and Docker. What was `juptyer/jupyterhub` is now `jupyterhub/jupyterhub`, etc.
 - `jupyterhub/jupyterhub` image on DockerHub no longer loads the jupyterhub_config.py in an ONBUILD step. A new `jupyterhub/jupyterhub-onbuild` image does this
 - Add statsd support, via `c.JupyterHub.statsd_{host,port,prefix}`
@@ -16,7 +528,7 @@ See `git log` for a more detailed summary.
 - Various fixes for user URLs and redirects
 
 
-## 0.5
+## [0.5] - 2016-03-07
 
 
 - Single-user server must be run with Jupyter Notebook ≥ 4.0
@@ -30,11 +542,11 @@ See `git log` for a more detailed summary.
 
 ## 0.4
 
-### 0.4.1
+### [0.4.1] - 2016-02-03
 
 Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 
-### 0.4.0
+### [0.4.0] - 2016-02-01
 
 - Add `Spawner.user_options_form` for specifying an HTML form to present to users,
   allowing users to influence the spawning of their own servers.
@@ -45,7 +557,7 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
 - 0.4 will be the last JupyterHub release where single-user servers running IPython 3 is supported instead of Notebook ≥ 4.0.
 
 
-## 0.3
+## [0.3] - 2015-11-04
 
 - No longer make the user starting the Hub an admin
 - start PAM sessions on login
@@ -53,13 +565,34 @@ Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
   allowing deeper interaction between Spawner/Authenticator pairs.
 - login redirect fixes
 
-## 0.2
+## [0.2] - 2015-07-12
 
 - Based on standalone traitlets instead of IPython.utils.traitlets
 - multiple users in admin panel
 - Fixes for usernames that require escaping
 
-## 0.1
+## 0.1 - 2015-03-07
 
 First preview release
 
+
+[Unreleased]: https://github.com/jupyterhub/jupyterhub/compare/1.0.0...HEAD
+[1.0.0]: https://github.com/jupyterhub/jupyterhub/compare/0.9.6...1.0.0
+[0.9.6]: https://github.com/jupyterhub/jupyterhub/compare/0.9.4...0.9.6
+[0.9.4]: https://github.com/jupyterhub/jupyterhub/compare/0.9.3...0.9.4
+[0.9.3]: https://github.com/jupyterhub/jupyterhub/compare/0.9.2...0.9.3
+[0.9.2]: https://github.com/jupyterhub/jupyterhub/compare/0.9.1...0.9.2
+[0.9.1]: https://github.com/jupyterhub/jupyterhub/compare/0.9.0...0.9.1
+[0.9.0]: https://github.com/jupyterhub/jupyterhub/compare/0.8.1...0.9.0
+[0.8.1]: https://github.com/jupyterhub/jupyterhub/compare/0.8.0...0.8.1
+[0.8.0]: https://github.com/jupyterhub/jupyterhub/compare/0.7.2...0.8.0
+[0.7.2]: https://github.com/jupyterhub/jupyterhub/compare/0.7.1...0.7.2
+[0.7.1]: https://github.com/jupyterhub/jupyterhub/compare/0.7.0...0.7.1
+[0.7.0]: https://github.com/jupyterhub/jupyterhub/compare/0.6.1...0.7.0
+[0.6.1]: https://github.com/jupyterhub/jupyterhub/compare/0.6.0...0.6.1
+[0.6.0]: https://github.com/jupyterhub/jupyterhub/compare/0.5.0...0.6.0
+[0.5]: https://github.com/jupyterhub/jupyterhub/compare/0.4.1...0.5.0
+[0.4.1]: https://github.com/jupyterhub/jupyterhub/compare/0.4.0...0.4.1
+[0.4.0]: https://github.com/jupyterhub/jupyterhub/compare/0.3.0...0.4.0
+[0.3]: https://github.com/jupyterhub/jupyterhub/compare/0.2.0...0.3.0
+[0.2]: https://github.com/jupyterhub/jupyterhub/compare/0.1.0...0.2.0

docs/source/conf.py

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

docs/source/contributing/community.rst

@@ -0,0 +1,30 @@
+.. _contributing/community:
+
+================================
+Community communication channels
+================================
+
+We use `Discourse <https://discourse.jupyter.org>` for online discussion.
+Everyone in the Jupyter community is welcome to bring ideas and questions there.
+In addition, we use `Gitter <https://gitter.im>`_ for online, real-time text chat,
+a place for more ephemeral discussions.
+The primary Gitter channel for JupyterHub is `jupyterhub/jupyterhub <https://gitter.im/jupyterhub/jupyterhub>`_.
+Gitter isn't archived or searchable, so we recommend going to discourse first
+to make sure that discussions are most useful and accessible to the community.
+Remember that our community is distributed across the world in various
+timezones, so be patient if you do not get an answer immediately!
+
+GitHub issues are used for most long-form project discussions, bug reports
+and feature requests. Issues related to a specific authenticator or
+spawner should be directed to the appropriate repository for the
+authenticator or spawner. If you are using a specific JupyterHub
+distribution (such as `Zero to JupyterHub on Kubernetes <http://github.com/jupyterhub/zero-to-jupyterhub-k8s>`_
+or `The Littlest JupyterHub <http://github.com/jupyterhub/the-littlest-jupyterhub/>`_),
+you should open issues directly in their repository. If you can not
+find a repository to open your issue in, do not worry! Create it in the `main
+JupyterHub repository <https://github.com/jupyterhub/jupyterhub/>`_ and our
+community will help you figure it out.
+
+A `mailing list <https://groups.google.com/forum/#!forum/jupyter>`_ for all
+of Project Jupyter exists, along with one for `teaching with Jupyter
+<https://groups.google.com/forum/#!forum/jupyter-education>`_. 

docs/source/contributing/docs.rst

@@ -0,0 +1,78 @@
+.. _contributing/docs:
+
+==========================
+Contributing Documentation
+==========================
+
+Documentation is often more important than code. This page helps
+you get set up on how to contribute documentation to JupyterHub.
+
+Building documentation locally
+==============================
+
+We use `sphinx <http://sphinx-doc.org>`_ to build our documentation. It takes
+our documentation source files (written in `markdown
+<https://daringfireball.net/projects/markdown/>`_ or `reStructuredText
+<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ &
+stored under the ``docs/source`` directory) and converts it into various
+formats for people to read. To make sure the documentation you write or
+change renders correctly, it is good practice to test it locally.
+
+#. Make sure you have successfuly completed :ref:`contributing/setup`.
+
+#. Install the packages required to build the docs.
+
+   .. code-block:: bash
+
+      python3 -m pip install -r docs/requirements.txt
+
+#. Build the html version of the docs. This is the most commonly used
+   output format, so verifying it renders as you should is usually good
+   enough.
+
+   .. code-block:: bash
+
+      cd docs
+      make html
+
+   This step will display any syntax or formatting errors in the documentation,
+   along with the filename / line number in which they occurred. Fix them,
+   and re-run the ``make html`` command to re-render the documentation.
+
+#. View the rendered documentation by opening ``build/html/index.html`` in 
+   a web browser. 
+
+   .. tip::
+
+      On macOS, you can open a file from the terminal with ``open <path-to-file>``.
+      On Linux, you can do the same with ``xdg-open <path-to-file>``.
+
+
+.. _contributing/docs/conventions:
+
+Documentation conventions
+=========================
+
+This section lists various conventions we use in our documentation. This is a
+living document that grows over time, so feel free to add to it / change it!
+
+Our entire documentation does not yet fully conform to these conventions yet,
+so help in making it so would be appreciated!
+
+``pip`` invocation
+------------------
+
+There are many ways to invoke a ``pip`` command, we recommend the following
+approach:
+
+.. code-block:: bash
+
+   python3 -m pip
+
+This invokes pip explicitly using the python3 binary that you are
+currently using. This is the **recommended way** to invoke pip
+in our documentation, since it is least likely to cause problems
+with python3 and pip being from different environments.
+
+For more information on how to invoke ``pip`` commands, see
+`the pip documentation <https://pip.pypa.io/en/stable/>`_.

docs/source/contributing/roadmap.md

@@ -0,0 +1,98 @@
+# The JupyterHub roadmap
+
+This roadmap collects "next steps" for JupyterHub. It is about creating a
+shared understanding of the project's vision and direction amongst
+the community of users, contributors, and maintainers.
+The goal is to communicate priorities and upcoming release plans.
+It is not a aimed at limiting contributions to what is listed here.
+
+
+## Using the roadmap
+### Sharing Feedback on the Roadmap
+
+All of the community is encouraged to provide feedback as well as share new
+ideas with the community. Please do so by submitting an issue. If you want to
+have an informal conversation first use one of the other communication channels.
+After submitting the issue, others from the community will probably
+respond with questions or comments they have to clarify the issue. The
+maintainers will help identify what a good next step is for the issue.
+
+### What do we mean by "next step"?
+
+When submitting an issue, think about what "next step" category best describes
+your issue:
+
+* **now**, concrete/actionable step that is ready for someone to start work on.
+These might be items that have a link to an issue or more abstract like
+"decrease typos and dead links in the documentation"
+* **soon**, less concrete/actionable step that is going to happen soon,
+discussions around the topic are coming close to an end at which point it can
+move into the "now" category
+* **later**, abstract ideas or tasks, need a lot of discussion or
+experimentation to shape the idea so that it can be executed. Can also
+contain concrete/actionable steps that have been postponed on purpose
+(these are steps that could be in "now" but the decision was taken to work on
+them later)
+
+### Reviewing and Updating the Roadmap
+
+The roadmap will get updated as time passes (next review by 1st December) based
+on discussions and ideas captured as issues.
+This means this list should not be exhaustive, it should only represent
+the "top of the stack" of ideas. It should
+not function as a wish list, collection of feature requests or todo list.
+For those please create a
+[new issue](https://github.com/jupyterhub/jupyterhub/issues/new).
+
+The roadmap should give the reader an idea of what is happening next, what needs
+input and discussion before it can happen and what has been postponed.
+
+
+## The roadmap proper
+### Project vision
+
+JupyterHub is a dependable tool used by humans that reduces the complexity of
+creating the environment in which a piece of software can be executed.
+
+### Now
+
+These "Now" items are considered active areas of focus for the project:
+
+* HubShare - a sharing service for use with JupyterHub.
+    * Users should be able to:
+        - Push a project to other users.
+        - Get a checkout of a project from other users.
+        - Push updates to a published project.
+        - Pull updates from a published project.
+        - Manage conflicts/merges by simply picking a version (our/theirs)
+        - Get a checkout of a project from the internet. These steps are completely different from saving notebooks/files.
+        - Have directories that are managed by git completely separately from our stuff.
+        - Look at pushed content that they have access to without an explicit pull.
+        - Define and manage teams of users.
+            - Adding/removing a user to/from a team gives/removes them access to all projects that team has access to.
+        - Build other services, such as static HTML publishing and dashboarding on top of these things.
+
+
+### Soon
+
+These "Soon" items are under discussion. Once an item reaches the point of an
+actionable plan, the item will be moved to the "Now" section. Typically,
+these will be moved at a future review of the roadmap.
+
+* resource monitoring and management:
+    - (prometheus?) API for resource monitoring
+    - tracking activity on single-user servers instead of the proxy
+    - notes and activity tracking per API token
+    - UI for managing named servers
+
+
+### Later
+
+The "Later" items are things that are at the back of the project's mind. At this
+time there is no active plan for an item. The project would like to find the
+resources and time to discuss these ideas.
+
+- real-time collaboration
+    - Enter into real-time collaboration mode for a project that starts a shared execution context.
+    - Once the single-user notebook package supports realtime collaboration,
+      implement sharing mechanism integrated into the Hub.

docs/source/contributing/security.rst

@@ -0,0 +1,10 @@
+Reporting security issues in Jupyter or JupyterHub
+==================================================
+
+If you find a security vulnerability in Jupyter or JupyterHub,
+whether it is a failure of the security model described in :doc:`../reference/websecurity`
+or a failure in implementation,
+please report it to security@ipython.org.
+
+If you prefer to encrypt your security reports,
+you can use :download:`this PGP public key </ipython_security.asc>`.

docs/source/contributing/setup.rst

@@ -0,0 +1,177 @@
+.. _contributing/setup:
+
+================================
+Setting up a development install
+================================
+
+System requirements
+===================
+
+JupyterHub can only run on MacOS or Linux operating systems. If you are
+using Windows, we recommend using `VirtualBox <https://virtualbox.org>`_ 
+or a similar system to run `Ubuntu Linux <https://ubuntu.com>`_ for
+development.
+
+Install Python
+--------------
+
+JupyterHub is written in the `Python <https://python.org>`_ programming language, and
+requires you have at least version 3.5 installed locally. If you haven’t
+installed Python before, the recommended way to install it is to use
+`miniconda <https://conda.io/miniconda.html>`_. Remember to get the ‘Python 3’ version, 
+and **not** the ‘Python 2’ version!
+
+Install nodejs
+--------------
+
+``configurable-http-proxy``, the default proxy implementation for
+JupyterHub, is written in Javascript to run on `NodeJS
+<https://nodejs.org/en/>`_. If you have not installed nodejs before, we
+recommend installing it in the ``miniconda`` environment you set up for
+Python. You can do so with ``conda install nodejs``.
+
+Install git
+-----------
+
+JupyterHub uses `git <https://git-scm.com>`_ & `GitHub <https://github.com>`_
+for development & collaboration. You need to `install git
+<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_ to work on
+JupyterHub. We also recommend getting a free account on GitHub.com.
+
+Setting up a development install
+================================
+
+When developing JupyterHub, you need to make changes to the code & see
+their effects quickly. You need to do a developer install to make that
+happen.
+
+1. Clone the `JupyterHub git repository <https://github.com/jupyterhub/jupyterhub>`_ 
+   to your computer.
+
+   .. code:: bash
+
+      git clone https://github.com/jupyterhub/jupyterhub
+      cd jupyterhub
+
+2. Make sure the ``python`` you installed and the ``npm`` you installed
+   are available to you on the command line.
+
+   .. code:: bash
+
+      python -V
+
+   This should return a version number greater than or equal to 3.5.
+
+   .. code:: bash
+
+      npm -v
+
+   This should return a version number greater than or equal to 5.0.
+
+3. Install ``configurable-http-proxy``. This is required to run
+   JupyterHub.
+
+   .. code:: bash
+
+      npm install -g configurable-http-proxy
+
+   If you get an error that says ``Error: EACCES: permission denied``,
+   you might need to prefix the command with ``sudo``. If you do not
+   have access to sudo, you may instead run the following commands:
+
+   .. code:: bash
+
+      npm install configurable-http-proxy
+      export PATH=$PATH:$(pwd)/node_modules/.bin
+
+   The second line needs to be run every time you open a new terminal.
+
+4. Install the python packages required for JupyterHub development.
+
+   .. code:: bash
+
+      python3 -m pip install -r dev-requirements.txt
+      python3 -m pip install -r requirements.txt
+
+5. Install the development version of JupyterHub. This lets you edit
+   JupyterHub code in a text editor & restart the JupyterHub process to
+   see your code changes immediately.
+
+   .. code:: bash
+
+      python3 -m pip install --editable .
+
+6. You are now ready to start JupyterHub!
+
+   .. code:: bash
+
+      jupyterhub
+
+7. You can access JupyterHub from your browser at
+   ``http://localhost:8000`` now.
+
+Happy developing!
+
+Using DummyAuthenticator & SimpleSpawner
+========================================
+
+To simplify testing of JupyterHub, it’s helpful to use
+:class:`~jupyterhub.auth.DummyAuthenticator` instead of the default JupyterHub
+authenticator and `SimpleSpawner <https://github.com/jupyterhub/simplespawner>`_ 
+instead of the default spawner.
+
+There is a sample configuration file that does this in
+``testing/jupyterhub_config.py``. To launch jupyterhub with this
+configuration:
+
+.. code:: bash
+
+   pip install jupyterhub-simplespawner
+   jupyterhub -f testing/jupyterhub_config.py
+
+The default JupyterHub `authenticator
+<https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#the-default-pam-authenticator>`_
+& `spawner
+<https://jupyterhub.readthedocs.io/en/stable/api/spawner.html#localprocessspawner>`_
+require your system to have user accounts for each user you want to log in to
+JupyterHub as.
+
+DummyAuthenticator allows you to log in with any username & password,
+while SimpleSpawner allows you to start servers without having to
+create a unix user for each JupyterHub user. Together, these make it
+much easier to test JupyterHub.
+
+Tip: If you are working on parts of JupyterHub that are common to all
+authenticators & spawners, we recommend using both DummyAuthenticator &
+SimpleSpawner. If you are working on just authenticator related parts,
+use only SimpleSpawner. Similarly, if you are working on just spawner
+related parts, use only DummyAuthenticator.
+
+Troubleshooting
+===============
+
+This section lists common ways setting up your development environment may
+fail, and how to fix them. Please add to the list if you encounter yet
+another way it can fail!
+
+``lessc`` not found
+-------------------
+
+If the ``python3 -m pip install --editable .`` command fails and complains about
+``lessc`` being unavailable, you may need to explicitly install some
+additional JavaScript dependencies:
+
+.. code:: bash
+
+   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:
+
+.. code:: bash
+
+   python3 setup.py js    # fetch updated client-side js
+   python3 setup.py css   # recompile CSS from LESS sources

docs/source/contributing/tests.rst

@@ -0,0 +1,78 @@
+.. _contributing/tests:
+
+==================
+Testing JupyterHub
+==================
+
+Unit test help validate that JupyterHub works the way we think it does,
+and continues to do so when changes occur. They also help communicate
+precisely what we expect our code to do. 
+
+JupyterHub uses `pytest <https://pytest.org>`_ for all our tests. You
+can find them under ``jupyterhub/tests`` directory in the git repository.
+
+Running the tests
+==================
+
+#. Make sure you have completed :ref:`contributing/setup`. You should be able
+   to start ``jupyterhub`` from the commandline & access it from your
+   web browser. This ensures that the dev environment is properly set
+   up for tests to run.
+
+#. You can run all tests in JupyterHub 
+
+   .. code-block:: bash
+
+      pytest --async-test-timeout 15 -v jupyterhub/tests
+
+   This should display progress as it runs all the tests, printing
+   information about any test failures as they occur.
+
+   The ``--async-test-timeout`` parameter is used by `pytest-tornado
+   <https://github.com/eugeniy/pytest-tornado#markers>`_ to set the
+   asynchronous test timeout to 15 seconds rather than the default 5,
+   since some of our tests take longer than 5s to execute.
+
+#. You can also run tests in just a specific file:
+
+   .. code-block:: bash
+
+      pytest --async-test-timeout 15 -v jupyterhub/tests/<test-file-name>
+
+#. To run a specific test only, you can do:
+
+   .. code-block:: bash
+
+      pytest --async-test-timeout 15 -v jupyterhub/tests/<test-file-name>::<test-name>
+
+   This runs the test with function name ``<test-name>`` defined in
+   ``<test-file-name>``. This is very useful when you are iteratively
+   developing a single test.
+
+   For example, to run the test ``test_shutdown`` in the file ``test_api.py``,
+   you would run:
+
+   .. code-block:: bash
+      
+      pytest -v jupyterhub/tests/test_api.py::test_shutdown
+
+
+Troubleshooting Test Failures
+=============================
+
+All the tests are failing
+-------------------------
+
+Make sure you have completed all the steps in :ref:`contributing/setup` sucessfully, and
+can launch ``jupyterhub`` from the terminal.
+
+Tests are timing out
+--------------------
+
+The ``--async-test-timeout`` parameter to ``pytest`` is used by
+`pytest-tornado <https://github.com/eugeniy/pytest-tornado#markers>`_ to set
+the asynchronous test timeout to a higher value than the default of 5s,
+since some of our tests take longer than 5s to execute. If the tests
+are still timing out, try increasing that value even more. You can
+also set an environment variable ``ASYNC_TEST_TIMEOUT`` instead of
+passing ``--async-test-timeout`` to each invocation of pytest.

docs/source/contributor-list.md

@@ -0,0 +1,122 @@
+# Contributors
+
+Project Jupyter thanks the following people for their help and
+contribution on JupyterHub:
+
+- adelcast
+- Analect
+- anderbubble
+- anikitml
+- ankitksharma
+- apetresc
+- athornton
+- barrachri
+- BerserkerTroll
+- betatim
+- Carreau
+- cfournie
+- charnpreetsingh
+- chicovenancio
+- cikao
+- ckald
+- cmoscardi
+- consideRatio
+- cqzlxl
+- CRegenschein
+- cwaldbieser
+- danielballen
+- danoventa
+- daradib
+- darky2004
+- datapolitan
+- dblockow-d2dcrc
+- DeepHorizons
+- DerekHeldtWerle
+- dhirschfeld
+- dietmarw
+- dingc3
+- dmartzol
+- DominicFollettSmith
+- dsblank
+- dtaniwaki
+- echarles
+- ellisonbg
+- emmanuel
+- evanlinde
+- Fokko
+- fperez
+- franga2000
+- GladysNalvarte
+- glenak1911
+- gweis
+- iamed18
+- jamescurtin
+- JamiesHQ
+- JasonJWilliamsNY
+- jbweston
+- jdavidheiser
+- jencabral
+- jhamrick
+- jkinkead
+- johnkpark
+- josephtate
+- jzf2101
+- karfai
+- kinuax
+- KrishnaPG
+- kroq-gar78
+- ksolan
+- mbmilligan
+- mgeplf
+- minrk
+- mistercrunch
+- Mistobaan
+- mpacer
+- mwmarkland
+- ndly
+- nthiery
+- nxg
+- ObiWahn
+- ozancaglayan
+- paccorsi
+- parente
+- PeterDaveHello
+- peterruppel
+- phill84
+- pjamason
+- prasadkatti
+- rafael-ladislau
+- rcthomas
+- rgbkrk
+- rkdarst
+- robnagler
+- rschroll
+- ryanlovett
+- sangramga
+- Scrypy
+- schon
+- shreddd
+- Siecje
+- smiller5678
+- spoorthyv
+- ssanderson
+- summerswallow
+- syutbai
+- takluyver
+- temogen
+- ThomasMChen
+- Thoralf Gutierrez
+- timfreund
+- TimShawver
+- tklever
+- Todd-Z-Li
+- toobaz
+- tsaeger
+- tschaume
+- vilhelmen
+- whitead
+- willingc
+- YannBrrd
+- yuvipanda
+- zoltan-fedor
+- zonca

docs/source/gallery-jhub-deployments.md

@@ -0,0 +1,188 @@
+# 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/)
+
+### George Washington University
+
+- [Jupyter Hub](http://go.gwu.edu/jupyter) with university single-sign-on. Deployed early 2017.
+
+### 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 (currently down; checked 04/26/19)
+
+### IllustrisTNG Simulation Project
+
+- [JupyterHub/Lab-based analysis platform, part of the TNG public data release](http://www.tng-project.org/data/)
+
+### MIT and Lincoln Labs
+
+- https://supercloud.mit.edu/
+
+### 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/
+
+### Paderborn University
+
+- [Data Science (DICE) group](https://dice.cs.uni-paderborn.de/)
+    - [nbgraderutils](https://github.com/dice-group/nbgraderutils): Use JupyterHub + nbgrader + iJava kernel for online Java exercises. Used in lecture Statistical Natural Language Processing.
+
+### Penn State University
+
+- [Press release](https://news.psu.edu/story/523093/2018/05/24/new-open-source-web-apps-available-students-and-faculty): "New open-source web apps available for students and faculty" (but Hub is currently down; checked 04/26/19)
+
+### 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/#/
+
+### Hadoop
+
+- [Deploying JupyterHub on Hadoop](https://jcrist.github.io/jupyterhub-on-hadoop/)
+
+
+## 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,439 +0,0 @@
-# Getting started with JupyterHub
-
-This document describes some of the basics of configuring JupyterHub to do what you want.
-JupyterHub is highly customizable, so there's a lot to cover.
-
-
-## Installation
-
-See [the readme](https://github.com/jupyter/jupyterhub/blob/master/README.md) for help installing JupyterHub.
-
-
-## Overview
-
-JupyterHub is a set of processes that together provide a multiuser Jupyter Notebook server.
-There are three main categories of processes run by the `jupyterhub` command line program:
-
-- **Single User Server**: a dedicated, single-user, Jupyter Notebook is started for each user on the system
-  when they log in. The object that starts these processes is called a Spawner.
-- **Proxy**: the public facing part of the server that uses a dynamic proxy to route HTTP requests
-  to the Hub and Single User Servers.
-- **Hub**: manages user accounts and authentication and coordinates Single Users Servers using a Spawner.
-
-## JupyterHub's default behavior
-
-**IMPORTANT:** In its default configuration, JupyterHub requires SSL encryption (HTTPS) to run.
-**You should not run JupyterHub without SSL encryption on a public network.**
-See [Security documentation](#Security) for how to configure JupyterHub to use SSL, and in
-certain cases, e.g. behind SSL termination in nginx, allowing the hub to run with no SSL
-by requiring `--no-ssl` (as of [version 0.5](./changelog.html)).
-
-To start JupyterHub in its default configuration, type the following at the command line:
-
-    sudo jupyterhub
-
-The default Authenticator that ships with JupyterHub authenticates users
-with their system name and password (via [PAM][]).
-Any user on the system with a password will be allowed to start a single-user notebook server.
-
-The default Spawner starts servers locally as each user, one dedicated server per user.
-These servers listen on localhost, and start in the given user's home directory.
-
-By default, the **Proxy** listens on all public interfaces on port 8000.
-Thus you can reach JupyterHub through either:
-
-    http://localhost:8000
-
-or any other public IP or domain pointing to your system.
-
-In their default configuration, the other services, the **Hub** and **Single-User Servers**,
-all communicate with each other on localhost only.
-
-By default, starting JupyterHub will write two files to disk in the current working directory:
-
-- `jupyterhub.sqlite` is the sqlite database containing all of the state of the **Hub**.
-  This file allows the **Hub** to remember what users are running and where,
-  as well as other information enabling you to restart parts of JupyterHub separately.
-- `jupyterhub_cookie_secret` is the encryption key used for securing cookies.
-  This file needs to persist in order for restarting the Hub server to avoid invalidating cookies.
-  Conversely, deleting this file and restarting the server effectively invalidates all login cookies.
-  The cookie secret file is discussed in the [Cookie Secret documentation](#Cookie secret).
-
-The location of these files can be specified via configuration, discussed below.
-
-
-## How to configure JupyterHub
-
-JupyterHub is configured in two ways:
-
-1. 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:
-
-    jupyterhub --generate-config
-
-This empty configuration file has descriptions of all configuration variables and their default
-values. You can load a specific config file with:
-
-    jupyterhub -f /path/to/jupyterhub_config.py
-
-See also: [general docs](http://ipython.org/ipython-doc/dev/development/config.html)
-on the config system Jupyter uses.
-
-### Command-line arguments
-Type the following for brief information about the command-line arguments:
-
-    jupyterhub -h
-
-or:
-
-    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
-c.Spawner.notebook_dir = '~/assignments' from the command-line:
-
-    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:
-
-    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:** In its default configuration, JupyterHub requires SSL encryption (HTTPS) to run.
-**You should not run JupyterHub without SSL encryption on a public network.**
-
-Security is the most important aspect of configuring Jupyter. There are three main aspects of the
-security configuration:
-
-1. SSL encryption (to enable HTTPS)
-2. Cookie secret (a key for encrypting browser cookies)
-3. Proxy authentication token (used for the Hub and other services to authenticate to the Proxy)
-
-## SSL encryption
-
-Since JupyterHub includes authentication and allows arbitrary code execution, you should not run
-it without SSL (HTTPS). This will require you to obtain an official, trusted SSL certificate or
-create a self-signed certificate. Once you have obtained and installed a key and certificate you
-need to specify their locations in the configuration file as follows:
-
-```python
-c.JupyterHub.ssl_key = '/path/to/my.key'
-c.JupyterHub.ssl_cert = '/path/to/my.cert'
-```
-
-It is also possible to use letsencrypt (https://letsencrypt.org/) to obtain a free, trusted SSL
-certificate. If you run letsencrypt using the default options, the needed configuration is (replace `your.domain.com` by your fully qualified domain name):
-
-```python
-c.JupyterHub.ssl_key = '/etc/letsencrypt/live/your.domain.com/privkey.pem'
-c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/your.domain.com/fullchain.pem'
-```
-
-Some cert files also contain the key, in which case only the cert is needed. It is important that
-these files be put in a secure location on your server, where they are not readable by regular
-users.
-
-Note: In certain cases, e.g. behind SSL termination in nginx, allowing no SSL
-running on the hub may be desired. To run the Hub without SSL, you must opt
-in by configuring and confirming the `--no-ssl` option, added as of [version 0.5](./changelog.html).
-
-## 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 secret in the configuration file itself 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:
-
-```python
-c.JupyterHub.proxy_auth_token = '0bc02bede919e99a26de1e2a7a5aadfaf6228de836ec39a05a6c6942831d8fe5'
-```
-
-If you don't set the Proxy authentication token, the Hub will generate a random key itself, which
-means that any time you restart the Hub you **must also restart the Proxy**. If the proxy is a
-subprocess of the Hub, this should happen automatically (this is the default configuration).
-
-Another time you must set the Proxy authentication token yourself is if you want other services, such as [nbgrader](https://github.com/jupyter/nbgrader) to also be able to connect to the Proxy.
-
-## Configuring authentication
-
-The default Authenticator uses [PAM][] to authenticate system users with their username and password.
-The default behavior of this Authenticator is to allow any user with an account and password on the system to login.
-You can restrict which users are allowed to login with `Authenticator.whitelist`:
-
-
-```python
-c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}
-```
-
-Admin users of JupyterHub have the ability to take actions on users' behalf,
-such as stopping and restarting their servers,
-and adding and removing new users from the whitelist.
-Any users in the admin list are automatically added to the whitelist,
-if they are not already present.
-The set of initial Admin users can configured as follows:
-
-```python
-c.Authenticator.admin_users = {'mal', 'zoe'}
-```
-
-If `JupyterHub.admin_access` is True (not default),
-then admin users have permission to log in *as other users* on their respective machines, for debugging.
-**You should make sure your users know if admin_access is enabled.**
-
-### Adding and removing users
-
-Users can be added and removed to the Hub via the admin panel or REST API. These users will be
-added to the whitelist and database. Restarting the Hub will not require manually updating the
-whitelist in your config file, as the users will be loaded from the database. This means that
-after starting the Hub once, it is not sufficient to remove users from the whitelist in your
-config file. You must also remove them from the database, either by discarding the database file,
-or via the admin UI.
-
-The default `PAMAuthenticator` is one case of a special kind of authenticator, called a
-`LocalAuthenticator`, indicating that it manages users on the local system. When you add a user to
-the Hub, a `LocalAuthenticator` checks if that user already exists. Normally, there will be an
-error telling you that the user doesn't exist. If you set the configuration value
-
-```python
-c.LocalAuthenticator.create_system_users = True
-```
-
-however, adding a user to the Hub that doesn't already exist on the system will result in the Hub
-creating that user via the system `adduser` command line tool. This option is typically used on
-hosted deployments of JupyterHub, to avoid the need to manually create all your users before
-launching the service. It is not recommended when running JupyterHub in situations where
-JupyterHub users maps directly onto UNIX users.
-
-## Configuring single-user servers
-
-Since the single-user server is an instance of `jupyter notebook`, an entire separate
-multi-process application, there are many aspect of that server can configure, and a lot of ways
-to express that configuration.
-
-At the JupyterHub level, you can set some values on the Spawner. The simplest of these is
-`Spawner.notebook_dir`, which lets you set the root directory for a user's server. This root
-notebook directory is the highest level directory users will be able to access in the notebook
-dashboard. In this example, the root notebook directory is set to `~/notebooks`, where `~` is
-expanded to the user's home directory.
-
-```python
-c.Spawner.notebook_dir = '~/notebooks'
-```
-
-You can also specify extra command-line arguments to the notebook server with:
-
-```python
-c.Spawner.args = ['--debug', '--profile=PHYS131']
-```
-
-This could be used to set the users default page for the single user server:
-
-```python
-c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
-```
-
-Since the single-user server extends the notebook server application,
-it still loads configuration from the `ipython_notebook_config.py` config file.
-Each user may have one of these files in `$HOME/.ipython/profile_default/`.
-IPython also supports loading system-wide config files from `/etc/ipython/`,
-which is the place to put configuration that you want to affect all of your users.
-
-## External services
-
-JupyterHub has a REST API that can be used to run external services.
-More detail on this API will be added in the future.
-
-## File locations
-
-It is recommended to put all of the files used by JupyterHub into standard UNIX filesystem locations.
-
-* `/srv/jupyterhub` for all security and runtime files
-* `/etc/jupyterhub` for all configuration files
-* `/var/log` for log files
-
-## Example
-
-In the following example, we show a configuration files for a fairly standard JupyterHub deployment with the following assumptions:
-
-* JupyterHub is running on a single cloud server
-* Using SSL on the standard HTTPS port 443
-* You want to use [GitHub OAuth][oauthenticator] for login
-* You need the users to exist locally on the server
-* You want users' notebooks to be served from `~/assignments` to allow users to browse for notebooks within
-  other users home directories
-* You want the landing page for each user to be a Welcome.ipynb notebook in their assignments directory.
-* All runtime files are put into `/srv/jupyterhub` and log files in `/var/log`.
-
-Let's start out with `jupyterhub_config.py`:
-
-```python
-# jupyterhub_config.py
-c = get_config()
-
-import os
-pjoin = os.path.join
-
-runtime_dir = os.path.join('/srv/jupyterhub')
-ssl_dir = pjoin(runtime_dir, 'ssl')
-if not os.path.exists(ssl_dir):
-    os.makedirs(ssl_dir)
-
-
-# https on :443
-c.JupyterHub.port = 443
-c.JupyterHub.ssl_key = pjoin(ssl_dir, 'ssl.key')
-c.JupyterHub.ssl_cert = pjoin(ssl_dir, 'ssl.cert')
-
-# put the JupyterHub cookie secret and state db
-# in /var/run/jupyterhub
-c.JupyterHub.cookie_secret_file = pjoin(runtime_dir, 'cookie_secret')
-c.JupyterHub.db_url = pjoin(runtime_dir, 'jupyterhub.sqlite')
-# or `--db=/path/to/jupyterhub.sqlite` on the command-line
-
-# put the log file in /var/log
-c.JupyterHub.log_file = '/var/log/jupyterhub.log'
-
-# use GitHub OAuthenticator for local users
-
-c.JupyterHub.authenticator_class = 'oauthenticator.LocalGitHubOAuthenticator'
-c.GitHubOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL']
-# create system users that don't exist yet
-c.LocalAuthenticator.create_system_users = True
-
-# specify users and admin
-c.Authenticator.whitelist = {'rgbkrk', 'minrk', 'jhamrick'}
-c.Authenticator.admin_users = {'jhamrick', 'rgbkrk'}
-
-# start single-user notebook servers in ~/assignments,
-# with ~/assignments/Welcome.ipynb as the default landing page
-# this config could also be put in
-# /etc/ipython/ipython_notebook_config.py
-c.Spawner.notebook_dir = '~/assignments'
-c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb']
-```
-
-Using the GitHub Authenticator [requires a few additional env variables][oauth-setup],
-which we will need to set when we launch the server:
-
-```bash
-export GITHUB_CLIENT_ID=github_id
-export GITHUB_CLIENT_SECRET=github_secret
-export OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback
-export CONFIGPROXY_AUTH_TOKEN=super-secret
-jupyterhub -f /path/to/aboveconfig.py
-```
-
-# Further reading
-
-- [Custom Authenticators](./authenticators.html)
-- [Custom Spawners](./spawners.html)
-- [Troubleshooting](./troubleshooting.html)
-
-
-[oauth-setup]: https://github.com/jupyter/oauthenticator#setup
-[oauthenticator]: https://github.com/jupyter/oauthenticator
-[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module

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

@@ -0,0 +1,119 @@
+# 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.
+
+Each authenticator may have different ways of determining whether a user is an
+administrator. By default JupyterHub use the PAMAuthenticator which provide the
+`admin_groups` option and can determine administrator status base on a user
+groups. For example we can let any users in the `wheel` group be admin:
+
+```python
+c.PAMAuthenticator.admin_groups = {'wheel'}
+```
+
+## 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.
+
+## Use DummyAuthenticator for testing
+
+The :class:`~jupyterhub.auth.DummyAuthenticator` is a simple authenticator that
+allows for any username/password unless if a global password has been set. If
+set, it will allow for any username as long as the correct password is provided.
+To set a global password, add this to the config file:
+
+```python
+c.DummyAuthenticator.password = "some_password"
+```
+
+[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,100 @@
+# Configuration Basics
+
+The section contains basic information about configuring settings for a JupyterHub
+deployment. The [Technical Reference](../reference/index)
+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)
+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) and
+[spawners](./spawners-basics) 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),
+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)
+
+## Run the proxy separately
+
+This is *not* strictly necessary, but useful in many cases.  If you
+use a custom proxy (e.g. Traefik), this also not needed.
+
+Connections to user servers go through the proxy, and *not* the hub
+itself.  If the proxy stays running when the hub restarts (for
+maintenance, re-configuration, etc.), then use connections are not
+interrupted.  For simplicity, by default the hub starts the proxy
+automatically, so if the hub restarts, the proxy restarts, and user
+connections are interrupted.  It is easy to run the proxy separately,
+for information see [the separate proxy page](../reference/separate-proxy).

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.html>`_.
+
+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)
+- 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), the preferred way of doing
+this is to first generate an API token:
+
+```bash
+openssl rand -hex 32
+```
+
+In [version 0.8.0](../changelog), 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': [sys.executable, 'cull_idle_servers.py', '--timeout=3600'],
+    }
+]
+```
+
+where:
+
+- `'admin': True` indicates that the Service has 'admin' permissions, and
+- `'command'` indicates that the Service will be launched as a
+  subprocess, managed by the Hub.
+
+## Run `cull-idle` manually as a standalone script
+
+Now you can run your script, i.e. `cull_idle_servers`, by providing it
+the API token and it will authenticate through the REST API to
+interact with it.
+
+This will run `cull-idle` manually. `cull-idle` can be run as a standalone
+script anywhere with access to the Hub, and will periodically check for idle
+servers and shut them down via the Hub's REST API. In order to shutdown the
+servers, the token given to cull-idle must have admin privileges.
+
+Generate an API token and store it in the `JUPYTERHUB_API_TOKEN` environment
+variable. Run `cull_idle_servers.py` manually.
+
+```bash
+    export JUPYTERHUB_API_TOKEN='token'
+    python3 cull_idle_servers.py [--timeout=900] [--url=http://127.0.0.1:8081/hub/api]
+```
+
+[cull_idle_servers]: https://github.com/jupyterhub/jupyterhub/blob/master/examples/cull-idle/cull_idle_servers.py

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

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

docs/source/howitworks.md

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

docs/source/index.rst

@@ -1,94 +1,207 @@
+==========
 JupyterHub
 ==========
 
-JupyterHub is a server that gives multiple users access to Jupyter notebooks,
-running an independent Jupyter notebook server for each user.
+`JupyterHub`_ is the best way to serve `Jupyter notebook`_ for multiple users. 
+It can be used in a classes of students, a corporate data science group or scientific 
+research group. It is a multi-user **Hub** that spawns, manages, and proxies multiple
+instances of the single-user `Jupyter notebook`_ 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 organisation, or it can run on the public
-internet (in which case, take care with `security <getting-started.html#security>`__).
-Users access JupyterHub in a web browser, by going to the IP address or
-domain name of the server.
+To make life easier, JupyterHub have distributions. Be sure to 
+take a look at them before continuing with the configuration of the broad 
+original system of `JupyterHub`_. Today, you can find two main cases: 
 
-Different :doc:`authenticators <authenticators>` 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 organisation has.
-
-Next, :doc:`spawners <spawners>` 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.
-
-JupyterHub runs as three separate parts:
-
-* The multi-user Hub (Python & Tornado)
-* A `configurable http proxy <https://github.com/jupyter/configurable-http-proxy>`_ (NodeJS)
-* Multiple single-user Jupyter notebook servers (Python & Tornado)
-
-Basic principles:
-
-* Hub spawns proxy
-* Proxy forwards ~all requests to hub by default
-* Hub handles login, and spawns single-user servers on demand
-* Hub configures proxy to forward url prefixes to single-user servers
+1. If you need a simple case for a small amount of users (0-100) and single server 
+   take a look at 
+   `The Littlest JupyterHub <https://github.com/jupyterhub/the-littlest-jupyterhub>`__ distribution. 
+2. If you need to allow for even more users, a dynamic amount of servers can be used on a cloud,
+   take a look at the `Zero to JupyterHub with Kubernetes <https://github.com/jupyterhub/zero-to-jupyterhub-k8s>`__ .
 
 
-Contents:
+Four subsystems make up JupyterHub:
 
-.. toctree::
-   :maxdepth: 2
-   :caption: User Documentation
+* a **Hub** (tornado process) that is the heart of JupyterHub
+* a **configurable http proxy** (node-http-proxy) that receives the requests from the client's browser
+* multiple **single-user Jupyter notebook servers** (Python/IPython/tornado) that are monitored by Spawners
+* an **authentication class** that manages how users can access the system
 
-   getting-started
-   howitworks
-   websecurity
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Configuration
+Besides these central pieces, you can add optional configurations through a `config.py` file and manage users kernels on an admin panel. A simplification of the whole system can be seen in the figure below:
 
-   authenticators
-   spawners
-   troubleshooting
+.. image:: images/jhub-fluxogram.jpeg
+   :alt: JupyterHub subsystems
+   :width: 80%
+   :align: center
+
+
+JupyterHub performs the following functions:
+
+- The Hub launches a proxy
+- The proxy forwards all requests to the Hub by default
+- The Hub handles user login and spawns single-user servers on demand
+- The Hub configures the proxy to forward URL prefixes to the single-user
+  notebook servers
+
+For convenient administration of the Hub, its users, and services,
+JupyterHub also provides a `REST API`_.
+
+The JupyterHub team and Project Jupyter value our community, and JupyterHub
+follows the Jupyter `Community Guides <https://jupyter.readthedocs.io/en/latest/community/content-community.html>`_.
+
+Contents
+========
+
+.. _index/distributions:
+
+Distributions
+-------------
+
+A JupyterHub **distribution** is tailored towards a particular set of
+use cases. These are generally easier to set up than setting up
+JupyterHub from scratch, assuming they fit your use case.
+
+The two popular ones are:
+
+* `Zero to JupyterHub on Kubernetes <http://z2jh.jupyter.org>`_, for
+  running JupyterHub on top of `Kubernetes <https://k8s.io>`_. This
+  can scale to large number of machines & users.
+* `The Littlest JupyterHub <http://tljh.jupyter.org>`_, for an easy
+  to set up & run JupyterHub supporting 1-100 users on a single machine.
+
+Installation Guide
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   installation-guide
+   quickstart
+   quickstart-docker
+   installation-basics
+
+Getting Started
+---------------
+
+.. toctree::
+   :maxdepth: 1
+
+   getting-started/index
+   getting-started/config-basics
+   getting-started/networking-basics
+   getting-started/security-basics
+   getting-started/authenticators-users-basics
+   getting-started/spawners-basics
+   getting-started/services-basics
+
+Technical Reference
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   reference/index
+   reference/technical-overview
+   reference/websecurity
+   reference/authenticators
+   reference/spawners
+   reference/services
+   reference/rest
+   reference/templates
+   reference/config-user-env
+   reference/config-examples
+   reference/config-ghoauth
+   reference/config-proxy
+   reference/config-sudo
+
+Contributing
+------------
+
+We want you to contribute to JupyterHub in ways that are most exciting
+& useful to you. We value documentation, testing, bug reporting & code equally,
+and are glad to have your contributions in whatever form you wish :)
+
+Our `Code of Conduct <https://github.com/jupyter/governance/blob/master/conduct/code_of_conduct.md>`_
+(`reporting guidelines <https://github.com/jupyter/governance/blob/master/conduct/reporting_online.md>`_)
+helps keep our community welcoming to as many people as possible.
+
+.. toctree::
+   :maxdepth: 1
+
+   contributing/community
+   contributing/setup
+   contributing/docs
+   contributing/tests
+   contributing/roadmap
+   contributing/security
+
+Upgrading JupyterHub
+--------------------
+
+We try to make upgrades between minor versions as painless as possible.
+
+.. toctree::
+   :maxdepth: 1
+
+   admin/upgrading
+   changelog
+
+API Reference
+-------------
 
 .. toctree::
    :maxdepth: 1
-   :caption: Developer Documentation
 
    api/index
 
+Troubleshooting
+---------------
 
 .. toctree::
    :maxdepth: 1
-   :caption: Community documentation
 
+   troubleshooting
 
+About JupyterHub
+----------------
 
 .. toctree::
-   :maxdepth: 2
-   :caption: About JupyterHub
+   :maxdepth: 1
 
+   contributor-list
    changelog
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Questions? Suggestions?
-
-   Jupyter mailing list <https://groups.google.com/forum/#!forum/jupyter>
-   Jupyter website <https://jupyter.org>
-   Stack Overflow - Jupyter <https://stackoverflow.com/questions/tagged/jupyter>
-   Stack Overflow - Jupyter-notebook <https://stackoverflow.com/questions/tagged/jupyter-notebook>
-
+   gallery-jhub-deployments
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
 
+
+Questions? Suggestions?
+=======================
+
+- `Jupyter mailing list <https://groups.google.com/forum/#!forum/jupyter>`_
+- `Jupyter website <https://jupyter.org>`_
+
+.. _contents:
+
+Full Table of Contents
+======================
+
+.. toctree::
+   :maxdepth: 2
+
+   installation-guide
+   getting-started/index
+   reference/index
+   api/index
+   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](./getting-started/security-basics)).
+
+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/ipython_security.asc

@@ -0,0 +1,52 @@
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+Version: GnuPG v2.0.22 (GNU/Linux)
+
+mQINBFMx2LoBEAC9xU8JiKI1VlCJ4PT9zqhU5nChQZ06/bj1BBftiMJG07fdGVO0
+ibOn4TrCoRYaeRlet0UpHzxT4zDa5h3/usJaJNTSRwtWePw2o7Lik8J+F3LionRf
+8Jz81WpJ+81Klg4UWKErXjBHsu/50aoQm6ZNYG4S2nwOmMVEC4nc44IAA0bb+6kW
+saFKKzEDsASGyuvyutdyUHiCfvvh5GOC2h9mXYvl4FaMW7K+d2UgCYERcXDNy7C1
+Bw+uepQ9ELKdG4ZpvonO6BNr1BWLln3wk93AQfD5qhfsYRJIyj0hJlaRLtBU3i6c
+xs+gQNF4mPmybpPSGuOyUr4FYC7NfoG7IUMLj+DYa6d8LcMJO+9px4IbdhQvzGtC
+qz5av1TX7/+gnS4L8C9i1g8xgI+MtvogngPmPY4repOlK6y3l/WtxUPkGkyYkn3s
+RzYyE/GJgTwuxFXzMQs91s+/iELFQq/QwmEJf+g/QYfSAuM+lVGajEDNBYVAQkxf
+gau4s8Gm0GzTZmINilk+7TxpXtKbFc/Yr4A/fMIHmaQ7KmJB84zKwONsQdVv7Jjj
+0dpwu8EIQdHxX3k7/Q+KKubEivgoSkVwuoQTG15X9xrOsDZNwfOVQh+JKazPvJtd
+SNfep96r9t/8gnXv9JI95CGCQ8lNhXBUSBM3BDPTbudc4b6lFUyMXN0mKQARAQAB
+tCxJUHl0aG9uIFNlY3VyaXR5IFRlYW0gPHNlY3VyaXR5QGlweXRob24ub3JnPokC
+OAQTAQIAIgUCUzHYugIbAwYLCQgHAwIGFQgCCQoLBBYCAwECHgECF4AACgkQEwJc
+LcmZYkjuXg//R/t6nMNQmf9W1h52IVfUbRAVmvZ5d063hQHKV2dssxtnA2dRm/x5
+JZu8Wz7ZrEZpyqwRJO14sxN1/lC3v+zs9XzYXr2lBTZuKCPIBypYVGIynCuWJBQJ
+rWnfG4+u1RHahnjqlTWTY1C/le6v7SjAvCb6GbdA6k4ZL2EJjQlRaHDmzw3rV/+l
+LLx6/tYzIsotuflm/bFumyOMmpQQpJjnCkWIVjnRICZvuAn97jLgtTI0+0Rzf4Zb
+k2BwmHwDRqWCTTcRI9QvTl8AzjW+dNImN22TpGOBPfYj8BCZ9twrpKUbf+jNqJ1K
+THQzFtpdJ6SzqiFVm74xW4TKqCLkbCQ/HtVjTGMGGz/y7KTtaLpGutQ6XE8SSy6P
+EffSb5u+kKlQOWaH7Mc3B0yAojz6T3j5RSI8ts6pFi6pZhDg9hBfPK2dT0v/7Mkv
+E1Z7q2IdjZnhhtGWjDAMtDDn2NbY2wuGoa5jAWAR0WvIbEZ3kOxuLE5/ZOG1FyYm
+noJRliBz7038nT92EoD5g1pdzuxgXtGCpYyyjRZwaLmmi4CvA+oThKmnqWNY5lyY
+ricdNHDiyEXK0YafJL1oZgM86MSb0jKJMp5U11nUkUGzkroFfpGDmzBwAzEPgeiF
+40+qgsKB9lqwb3G7PxvfSi3XwxfXgpm1cTyEaPSzsVzve3d1xeqb7Yq5Ag0EUzHY
+ugEQALQ5FtLdNoxTxMsgvrRr1ejLiUeRNUfXtN1TYttOfvAhfBVnszjtkpIW8DCB
+JF/bA7ETiH8OYYn/Fm6MPI5H64IHEncpzxjf57jgpXd9CA9U2OMk/P1nve5zYchP
+QmP2fJxeAWr0aRH0Mse5JS5nCkh8Xv4nAjsBYeLTJEVOb1gPQFXOiFcVp3gaKAzX
+GWOZ/mtG/uaNsabH/3TkcQQEgJefd11DWgMB7575GU+eME7c6hn3FPITA5TC5HUX
+azvjv/PsWGTTVAJluJ3fUDvhpbGwYOh1uV0rB68lPpqVIro18IIJhNDnccM/xqko
+4fpJdokdg4L1wih+B04OEXnwgjWG8OIphR/oL/+M37VV2U7Om/GE6LGefaYccC9c
+tIaacRQJmZpG/8RsimFIY2wJ07z8xYBITmhMmOt0bLBv0mU0ym5KH9Dnru1m9QDO
+AHwcKrDgL85f9MCn+YYw0d1lYxjOXjf+moaeW3izXCJ5brM+MqVtixY6aos3YO29
+J7SzQ4aEDv3h/oKdDfZny21jcVPQxGDui8sqaZCi8usCcyqWsKvFHcr6vkwaufcm
+3Knr2HKVotOUF5CDZybopIz1sJvY/5Dx9yfRmtivJtglrxoDKsLi1rQTlEQcFhCS
+ACjf7txLtv03vWHxmp4YKQFkkOlbyhIcvfPVLTvqGerdT2FHABEBAAGJAh8EGAEC
+AAkFAlMx2LoCGwwACgkQEwJcLcmZYkgK0BAAny0YUugpZldiHzYNf8I6p2OpiDWv
+ZHaguTTPg2LJSKaTd+5UHZwRFIWjcSiFu+qTGLNtZAdcr0D5f991CPvyDSLYgOwb
+Jm2p3GM2KxfECWzFbB/n/PjbZ5iky3+5sPlOdBR4TkfG4fcu5GwUgCkVe5u3USAk
+C6W5lpeaspDz39HAPRSIOFEX70+xV+6FZ17B7nixFGN+giTpGYOEdGFxtUNmHmf+
+waJoPECyImDwJvmlMTeP9jfahlB6Pzaxt6TBZYHetI/JR9FU69EmA+XfCSGt5S+0
+Eoc330gpsSzo2VlxwRCVNrcuKmG7PsFFANok05ssFq1/Djv5rJ++3lYb88b8HSP2
+3pQJPrM7cQNU8iPku9yLXkY5qsoZOH+3yAia554Dgc8WBhp6fWh58R0dIONQxbbo
+apNdwvlI8hKFB7TiUL6PNShE1yL+XD201iNkGAJXbLMIC1ImGLirUfU267A3Cop5
+hoGs179HGBcyj/sKA3uUIFdNtP+NndaP3v4iYhCitdVCvBJMm6K3tW88qkyRGzOk
+4PW422oyWKwbAPeMk5PubvEFuFAIoBAFn1zecrcOg85RzRnEeXaiemmmH8GOe1Xu
+Kh+7h8XXyG6RPFy8tCcLOTk+miTqX+4VWy+kVqoS2cQ5IV8WsJ3S7aeIy0H89Z8n
+5vmLc+Ibz+eT+rM=
+=XVDe
+-----END PGP PUBLIC KEY BLOCK-----

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 -p 8000:8000 --name jupyterhub jupyterhub/jupyterhub jupyterhub
+
+This command will create a container named ``jupyterhub`` that you can
+**stop and resume** with ``docker stop/start``.
+
+The Hub service will be listening on all interfaces at port 8000, which makes
+this a good choice for **testing JupyterHub on your desktop or laptop**.
+
+If you want to run docker on a computer that has a public IP then you should
+(as in MUST) **secure it with ssl** by adding ssl options to your docker
+configuration or using a ssl enabled proxy.
+
+`Mounting volumes <https://docs.docker.com/engine/admin/volumes/volumes/>`_
+will allow you to store data outside the docker image (host system) so it will
+be persistent, even when you start a new image.
+
+The command ``docker exec -it jupyterhub bash`` will spawn a root shell in your
+docker container. You can use the root shell to **create system users in the container**.
+These accounts will be used for authentication in JupyterHub's default
+configuration.
+
+.. _Zero to JupyterHub: https://zero-to-jupyterhub.readthedocs.io/en/latest/

docs/source/quickstart.md

@@ -0,0 +1,85 @@
+# Quickstart
+
+## Prerequisites
+
+Before installing JupyterHub, you will need:
+
+- a Linux/Unix based system
+- [Python](https://www.python.org/downloads/) 3.5 or greater. An understanding
+  of using [`pip`](https://pip.pypa.io/en/stable/) or
+  [`conda`](https://conda.io/docs/get-started.html) for
+  installing Python packages is helpful.
+- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
+  using your operating system's package manager.
+
+  * If you are using **`conda`**, the nodejs and npm dependencies will be installed for
+    you by conda.
+
+  * If you are using **`pip`**, install a recent version of
+    [nodejs/npm](https://docs.npmjs.com/getting-started/installing-node).
+    For example, install it on Linux (Debian/Ubuntu) using:
+
+    ```
+    sudo apt-get install npm nodejs-legacy
+    ```
+          
+    The `nodejs-legacy` package installs the `node` executable and is currently
+    required for npm to work on Debian/Ubuntu.
+
+- TLS certificate and key for HTTPS communication
+- Domain name
+
+Before running the single-user notebook servers (which may be on the same
+system as the Hub or not), you will need:
+
+- [Jupyter Notebook](https://jupyter.readthedocs.io/en/latest/install.html)
+  version 4 or greater
+
+## Installation
+
+JupyterHub can be installed with `pip` (and the proxy with `npm`) or `conda`:
+
+**pip, npm:**
+
+```bash
+python3 -m pip install jupyterhub
+npm install -g configurable-http-proxy
+python3 -m pip install notebook  # needed if running the notebook servers locally
+```
+
+**conda** (one command installs jupyterhub and proxy):
+
+```bash
+conda install -c conda-forge jupyterhub  # installs jupyterhub and proxy
+conda install notebook  # needed if running the notebook servers locally
+```
+
+Test your installation. If installed, these commands should return the packages'
+help contents:
+
+```bash
+jupyterhub -h
+configurable-http-proxy -h
+```
+
+## Start the Hub server
+
+To start the Hub server, run the command:
+
+```bash
+jupyterhub
+```
+
+Visit `https://localhost:8000` in your browser, and sign in with your unix
+credentials.
+
+To **allow multiple users to sign in** to the Hub server, you must start
+`jupyterhub` as a *privileged user*, such as root:
+
+```bash
+sudo jupyterhub
+```
+
+The [wiki](https://github.com/jupyterhub/jupyterhub/wiki/Using-sudo-to-run-JupyterHub-without-root-privileges)
+describes how to run the server as a *less privileged user*. This requires
+additional configuration of the system.

docs/source/reference/authenticators.md

@@ -0,0 +1,278 @@
+# Authenticators
+
+The [Authenticator][] is the mechanism for authorizing users to use the
+Hub and single user notebook servers.
+
+## The default PAM Authenticator
+
+JupyterHub ships 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.
+
+## The Dummy Authenticator
+
+When testing, it may be helpful to use the
+:class:`~jupyterhub.auth.DummyAuthenticator`. This allows for any username and
+password unless if a global password has been set. Once set, any username will
+still be accepted but the correct password will need to be provided.
+
+## Additional Authenticators
+
+A partial list of other authenticators is available on the
+[JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+
+## 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 IPython.utils.traitlets import Dict
+from jupyterhub.auth import Authenticator
+
+class DictionaryAuthenticator(Authenticator):
+
+    passwords = Dict(config=True,
+        help="""dict of username:password for authentication"""
+    )
+
+    async 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'
+}
+```
+
+When using `PAMAuthenticator`, you can set
+`c.PAMAuthenticator.pam_normalize_username = True`, which will
+normalize usernames using PAM (basically round-tripping them: username
+to uid to username), which is useful in case you use some external
+service that allows multiple usernames mapping to the same user (such
+as ActiveDirectory, yes, this really happens).  When
+`pam_normalize_username` is on, usernames are *not* normalized to
+lowercase.
+
+
+#### 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).
+
+### Registering custom Authenticators via entry points
+
+As of JupyterHub 1.0, custom authenticators can register themselves via
+the `jupyterhub.authenticators` entry point metadata.
+To do this, in your `setup.py` add:
+
+```python
+setup(
+  ...
+  entry_points={
+    'jupyterhub.authenticators': [
+        'myservice = mypackage:MyAuthenticator',
+    ],
+  },
+)
+```
+
+If you have added this metadata to your package,
+users can select your authenticator with the configuration:
+
+```python
+c.JupyterHub.authenticator_class = 'myservice'
+```
+
+instead of the full
+
+```python
+c.JupyterHub.authenticator_class = 'mypackage:MyAuthenticator'
+```
+
+previously required.
+Additionally, configurable attributes for your authenticator will
+appear in jupyterhub help output and auto-generated configuration files
+via `jupyterhub --generate-config`.
+
+
+### 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,212 @@
+# 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>
+```
+
+ 
+In case of the need to run the jupyterhub under /jhub/ or other location please use the below configurations:
+- JupyterHub running locally at http://127.0.0.1:8000/jhub/ or other location
+
+httpd.conf amendments:
+```bash
+ RewriteRule /jhub/(.*) ws://127.0.0.1:8000/jhub/$1 [P,L]
+ RewriteRule /jhub/(.*) http://127.0.0.1:8000/jhub/$1 [P,L]
+ 
+ ProxyPass /jhub/ http://127.0.0.1:8000/jhub/
+ ProxyPassReverse /jhub/  http://127.0.0.1:8000/jhub/
+ ```
+ 
+jupyterhub_config.py amendments:
+ ```bash
+  --The public facing URL of the whole JupyterHub application.
+  --This is the address on which the proxy will bind. Sets protocol, ip, base_url
+  c.JupyterHub.bind_url = 'http://127.0.0.1:8000/jhub/'
+  ```

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 python3 -m 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 modify `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  named `sudo_exec_selinux.te`:
+
+```bash
+module sudo_exec_selinux 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 a more recent version
+of jupyterhub and disabling the opening of PAM sessions with
+`c.PAMAuthenticator.open_sessions=False`.

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

@@ -0,0 +1,181 @@
+# 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 system)
+- 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.
+
+## Named servers
+
+By default, in a JupyterHub deployment each user has exactly one server.
+
+JupyterHub can, however, have multiple servers per user.
+This is most useful in deployments where users can configure the environment
+in which their server will start (e.g. resource requests on an HPC cluster),
+so that a given user can have multiple configurations running at the same time,
+without having to stop and restart their one server.
+
+To allow named servers:
+
+```python
+c.JupyterHub.allow_named_servers = True
+```
+
+Named servers were implemented in the REST API in JupyterHub 0.8,
+and JupyterHub 1.0 introduces UI for managing named servers via the user home page:
+
+![named servers on the home page](../images/named-servers-home.png)
+
+as well as the admin page:
+
+![named servers on the admin page](../images/named-servers-admin.png)
+
+Named servers can be accessed, created, started, stopped, and deleted
+from these pages. Activity tracking is now per-server as well.
+
+The number of named servers per user can be limited by setting
+
+```python
+c.JupyterHub.named_server_limit_per_user = 5
+```

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,22 @@
+Technical Reference
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   technical-overview
+   urls
+   websecurity
+   authenticators
+   spawners
+   services
+   proxy
+   separate-proxy
+   rest
+   database
+   templates
+   config-user-env
+   config-examples
+   config-ghoauth
+   config-proxy
+   config-sudo

docs/source/reference/proxy.md

@@ -0,0 +1,222 @@
+# 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
+class MyProxy(Proxy):
+    ...
+    async def start(self):
+        """Start the proxy"""
+
+    async 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.
+
+## Encryption
+
+When using `internal_ssl` to encrypt traffic behind the proxy, at minimum,
+your `Proxy` will need client ssl certificates which the `Hub` must be made 
+aware of. These can be generated with the command `jupyterhub --generate-certs`
+which will write them to the `internal_certs_location` in folders named
+`proxy_api` and `proxy_client`. Alternatively, these can be provided to the
+hub via the `jupyterhub_config.py` file by providing a `dict` of named paths
+to the `external_authorities` option. The hub will include all certificates
+provided in that `dict` in the trust bundle utilized by all internal
+components.
+
+### 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
+async 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
+await 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
+async 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
+async 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.
+
+### Registering custom Proxies via entry points
+
+As of JupyterHub 1.0, custom proxy implementations can register themselves via
+the `jupyterhub.proxies` entry point metadata.
+To do this, in your `setup.py` add:
+
+```python
+setup(
+  ...
+  entry_points={
+    'jupyterhub.proxies': [
+        'mything = mypackage:MyProxy',
+    ],
+  },
+)
+```
+
+If you have added this metadata to your package,
+users can select your authenticator with the configuration:
+
+```python
+c.JupyterHub.proxy_class = 'mything'
+```
+
+instead of the full
+
+```python
+c.JupyterHub.proxy_class = 'mypackage:MyProxy'
+```
+
+previously required.
+Additionally, configurable attributes for your proxy will
+appear in jupyterhub help output and auto-generated configuration files
+via `jupyterhub --generate-config`.

docs/source/reference/rest-api.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+===================
+JupyterHub REST API
+===================
+
+.. this doc exists as a resolvable link target
+.. which _static files are not
+
+.. meta::
+    :http-equiv=refresh: 0;url=../_static/rest-api/index.html
+
+The rest API docs are `here <../_static/rest-api/index.html>`_
+if you are not redirected automatically.

docs/source/reference/rest.md

@@ -0,0 +1,177 @@
+# 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.md), 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.md), 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
+
+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]: ./rest-api
+[Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml

docs/source/reference/separate-proxy.md

@@ -0,0 +1,80 @@
+# Running proxy separately from the hub
+
+
+## Background
+
+The thing which users directly connect to is the proxy, by default
+`configurable-http-proxy`.  The proxy either redirects users to the
+hub (for login and managing servers), or to their own single-user
+servers.  Thus, as long as the proxy stays running, access to existing
+servers continues, even if the hub itself restarts or goes down.
+
+When you first configure the hub, you may not even realize this
+because the proxy is automatically managed by the hub.  This is great
+for getting started and even most use, but everytime you restart the
+hub, all user connections also get restarted.  But it's also simple to
+run the proxy as a service separate from the hub, so that you are free
+to reconfigure the hub while only interrupting users who are currently
+actively starting the hub.
+
+The default JupyterHub proxy is
+[configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy),
+and that page has some docs.  If you are using a different proxy, such
+as Traefik, these instructions are probably not relevant to you.
+
+
+## Configuration options
+
+`c.JupyterHub.cleanup_servers = False` should be set, which tells the
+hub to not stop servers when the hub restarts (this is useful even if
+you don't run the proxy separately).
+
+`c.ConfigurableHTTPProxy.should_start = False` should be set, which
+tells the hub that the proxy should not be started (because you start
+it yourself).
+
+`c.ConfigurableHTTPProxy.auth_token = "CONFIGPROXY_AUTH_TOKEN"` should be set to a
+token for authenticating communication with the proxy.
+
+`c.ConfigurableHTTPProxy.api_url = 'http://localhost:8001'` should be
+set to the URL which the hub uses to connect *to the proxy's API*.
+
+
+## Proxy configuration
+
+You need to configure a service to start the proxy.  An example
+command line for this is `configurable-http-proxy --ip=127.0.0.1
+--port=8000 --api-ip=127.0.0.1 --api-port=8001
+--default-target=http://localhost:8081
+--error-target=http://localhost:8081/hub/error`.  (Details for how to
+do this is out of scope for this tutorial - for example it might be a
+systemd service on within another docker cotainer).  The proxy has no
+configuration files, all configuration is via the command line and
+environment variables.
+
+`--api-ip` and `--api-port` (which tells the proxy where to listen) should match the hub's `ConfigurableHTTPProxy.api_url`.
+
+`--ip`, `-port`, and other options configure the *user* connections to the proxy.
+
+`--default-target` and `--error-target` should point to the hub, and used when users navigate to the proxy originally.
+
+You must define the environment variable `CONFIGPROXY_AUTH_TOKEN` to
+match the token given to `c.ConfigurableHTTPProxy.auth_token`.
+
+You should check the [configurable-http-proxy
+options](https://github.com/jupyterhub/configurable-http-proxy) to see
+what other options are needed, for example SSL options.  Note that
+these are configured in the hub if the hub is starting the proxy - you
+need to move the options to here.
+
+
+## Docker image
+
+You can use [jupyterhub configurable-http-proxy docker
+image](https://hub.docker.com/r/jupyterhub/configurable-http-proxy/)
+to run the proxy.
+
+
+## See also
+
+* [jupyterhub configurable-http-proxy](https://github.com/jupyterhub/configurable-http-proxy)

docs/source/reference/services.md

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