release 0.4.1

Restore /login handler

.dockerignore

@@ -3,3 +3,4 @@ bench
 jupyterhub_cookie_secret
 jupyterhub.sqlite
 jupyterhub_config.py
+node_modules

.gitignore

@@ -4,6 +4,8 @@ node_modules
 .DS_Store
 build
 dist
+docs/_build
+.ipynb_checkpoints
 # ignore config file at the top-level of the repo
 # but not sub-dirs
 /jupyterhub_config.py

.travis.yml

@@ -11,8 +11,7 @@ before_install:
     - git clone --quiet --depth 1 https://github.com/minrk/travis-wheels travis-wheels
 install:
     - pip install -f travis-wheels/wheelhouse -r dev-requirements.txt .
-    - pip install -f travis-wheels/wheelhouse notebook
 script:
     - py.test --cov jupyterhub jupyterhub/tests -v
 after_success:
-    - coveralls
+    - codecov

Dockerfile

@@ -5,24 +5,39 @@
 # FROM jupyter/jupyterhub:latest
 #
 
-FROM jupyter/notebook
+FROM debian:jessie
 
 MAINTAINER Jupyter Project <jupyter@googlegroups.com>
 
+# install nodejs, utf8 locale
+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 clean && \
+    rm -rf /var/lib/apt/lists/*
+ENV LANG C.UTF-8
+
+# install Python with conda
+RUN wget -q https://repo.continuum.io/miniconda/Miniconda3-3.9.1-Linux-x86_64.sh -O /tmp/miniconda.sh  && \
+    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/pip install --upgrade pip && \
+    rm /tmp/miniconda.sh
+ENV PATH=/opt/conda/bin:$PATH
+
 # install js dependencies
-RUN npm install -g configurable-http-proxy
-
-RUN mkdir -p /srv/
-
-# install jupyterhub
-ADD requirements.txt /tmp/requirements.txt
-RUN pip3 install -r /tmp/requirements.txt
+RUN npm install -g configurable-http-proxy && rm -rf ~/.npm
 
 WORKDIR /srv/
 ADD . /srv/jupyterhub
 WORKDIR /srv/jupyterhub/
 
-RUN pip3 install .
+RUN python setup.py js && pip install . && \
+    rm -rf node_modules ~/.cache ~/.npm
 
 WORKDIR /srv/jupyterhub/
 

README.md

@@ -3,8 +3,11 @@
 Questions, comments? Visit our Google Group:
 
 [![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
+[![Build Status](https://travis-ci.org/jupyter/jupyterhub.svg?branch=master)](https://travis-ci.org/jupyter/jupyterhub)
+[![Circle CI](https://circleci.com/gh/jupyter/jupyterhub.svg?style=shield&circle-token=b5b65862eb2617b9a8d39e79340b0a6b816da8cc)](https://circleci.com/gh/jupyter/jupyterhub)
+[![Documentation Status](https://readthedocs.org/projects/jupyterhub/badge/?version=latest)](http://jupyterhub.readthedocs.org/en/latest/?badge=latest)
 
-JupyterHub is a multi-user server that manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
+JupyterHub, a multi-user server, manages and proxies multiple instances of the single-user <del>IPython</del> Jupyter notebook server.
 
 Three actors:
 
@@ -22,26 +25,25 @@ Basic principles:
 
 ## Dependencies
 
-JupyterHub requires IPython >= 3.0 (current master) and Python >= 3.3.
+JupyterHub requires [IPython](https://ipython.org/install.html) >= 3.0 (current master) and [Python](https://www.python.org/downloads/) >= 3.3.
 
-You will need nodejs/npm, which you can get from your package manager:
+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,
-which is required for npm to work on Debian/Ubuntu at this point)
+(The `nodejs-legacy` package installs the `node` executable and is currently
+required for npm to work on Debian/Ubuntu.)
 
-Then install javascript dependencies:
+Next, install JavaScript dependencies:
 
     sudo npm install -g configurable-http-proxy
 
-### Optional
+### (Optional) Installation Prerequisite (pip)
 
-- Notes on `pip` command used in the below installation sections:
-  - `sudo` may be needed for `pip install`, depending on filesystem permissions.
-  - JupyterHub requires Python >= 3.3, so it may be required on some machines to use `pip3` instead
-    of `pip` (especially when you have both Python 2 and Python 3 installed on your machine).
-    If `pip3` is not found on your machine, you can get it by doing:
+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
 
@@ -52,17 +54,10 @@ JupyterHub can be installed with pip:
 
     pip3 install jupyterhub
 
-If the `pip3 install .` command fails and complains about `lessc` being unavailable, you may need to explicitly install some additional javascript dependencies:
+If you plan to run notebook servers locally, you may also need to install the
+Jupyter ~~IPython~~ notebook:
 
-    npm install
-
-If you plan to run notebook servers locally, you may also need to install the IPython notebook:
-
-    pip3 install "ipython[notebook]"
-
-This will fetch client-side javascript dependencies and compile CSS,
-and install these files to `sys.prefix`/share/jupyter, as well as
-install any Python dependencies.
+    pip3 install notebook
 
 
 ### Development install
@@ -73,7 +68,13 @@ For a development install, clone the repository and then install from source:
     cd jupyterhub
     pip3 install -r dev-requirements.txt -e .
 
-In which case you may need to manually update javascript and css after some updates, with:
+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
@@ -87,22 +88,24 @@ To start the server, run the command:
 
 and then visit `http://localhost:8000`, and sign in with your unix credentials.
 
-If you want multiple users to be able 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.
+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.
 
 ## Getting started
 
-see the [getting started doc](docs/getting-started.md) for some of the basics of configuring your JupyterHub deployment.
+See the [getting started document](docs/source/getting-started.md) for the
+basics of configuring your JupyterHub deployment.
 
 ### Some examples
 
-generate a default config file:
+Generate a default config file:
 
     jupyterhub --generate-config
 
-spawn the server on 10.0.1.2:443 with https:
+Spawn the server on ``10.0.1.2:443`` with **https**:
 
     jupyterhub --ip 10.0.1.2 --port 443 --ssl-key my_ssl.key --ssl-cert my_ssl.cert
 
@@ -111,7 +114,7 @@ which should allow plugging into a variety of authentication or process control
 Some examples, meant as illustration and testing of this concept:
 
 - 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)
+- Spawning single-user servers with Docker, using the [DockerSpawner](https://github.com/jupyter/dockerspawner)
 
 # Getting help
 
@@ -119,6 +122,13 @@ We encourage you to ask questions on the mailing list:
 
 [![Google Group](https://img.shields.io/badge/-Google%20Group-lightgrey.svg)](https://groups.google.com/forum/#!forum/jupyter)
 
-but you can participate in development discussions or get live help on Gitter:
+and you may participate in development discussions or get live help on Gitter:
 
 [![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/jupyter/jupyterhub?utm_source=badge&utm_medium=badge)
+
+## Resources
+- [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)

circle.yml

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

dev-requirements.txt

@@ -1,4 +1,5 @@
 -r requirements.txt
-coveralls
+codecov
 pytest-cov
 pytest>=2.8
+notebook

docs/Makefile

@@ -0,0 +1,192 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@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)"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/JupyterHub.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/JupyterHub.qhc"
+
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/JupyterHub"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/JupyterHub"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/changelog.md

@@ -1,22 +0,0 @@
-# Summary of changes in JupyterHub
-
-See `git log` for a more detailed summary.
-
-## 0.3.0
-
-- No longer make the user starting the Hub an admin
-- start PAM sessions on login
-- hooks for Authenticators to fire before spawners start and after they stop,
-  allowing deeper interaction between Spawner/Authenticator pairs.
-- login redirect fixes
-
-## 0.2.0
-
-- Based on standalone traitlets instead of IPython.utils.traitlets
-- multiple users in admin panel
-- Fixes for usernames that require escaping
-
-## 0.1.0
-
-First preview release
-

docs/make.bat

@@ -0,0 +1,263 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source
+set I18NSPHINXOPTS=%SPHINXOPTS% source
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
+	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
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 1>NUL 2>NUL
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\JupyterHub.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\JupyterHub.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %~dp0
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+if "%1" == "coverage" (
+	%SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of coverage in the sources finished, look at the ^
+results in %BUILDDIR%/coverage/python.txt.
+	goto end
+)
+
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
+:end

docs/requirements.txt

@@ -0,0 +1,3 @@
+-r ../requirements.txt
+sphinx
+recommonmark==0.4.0

docs/rest-api.yml

@@ -0,0 +1,259 @@
+# see me at: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyterhub/master/docs/rest-api.yml#/default
+swagger: '2.0'
+info:
+  title: JupyterHub
+  description: The REST API for JupyterHub
+  version: 0.4.0
+schemes:
+  - http
+securityDefinitions:
+  token:
+    type: apiKey
+    name: Authorization
+    in: header
+security:
+  - token: []
+basePath: /hub/api/
+produces:
+  - application/json
+consumes:
+  - application/json
+paths:
+  /users:
+    get:
+      summary: List users
+      responses:
+        '200':
+          description: The user list
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/User'
+    post:
+      summary: Create multiple users
+      parameters:
+        - name: data
+          in: body
+          required: true
+          schema:
+            type: object
+            properties:
+              usernames:
+                type: array
+                description: list of usernames to create
+                items:
+                  type: string
+              admin:
+                description: whether the created users should be admins
+                type: boolean
+      responses:
+        '201':
+          description: The users have been created
+          schema:
+            type: array
+            description: The created users
+            items:
+              $ref: '#/definitions/User'
+  /users/{name}:
+    get:
+      summary: Get a user by name
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: The User model
+          schema:
+            $ref: '#/definitions/User'
+    post:
+      summary: Create a single user
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '201':
+          description: The user has been created
+          schema:
+            $ref: '#/definitions/User'
+    delete:
+      summary: Delete a user
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The user has been deleted
+    patch:
+      summary: Modify a user
+      description: Change a user's name or admin status
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+        - name: data
+          in: body
+          required: true
+          description: Updated user info. At least one of name and admin is required.
+          schema:
+            type: object
+            properties:
+              name:
+                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'
+  /users/{name}/server:
+    post:
+      summary: Start a user's server
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '201':
+          description: The server has started
+        '202':
+          description: The server has been requested, but has not yet started
+    delete:
+      summary: Stop a user's server
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '204':
+          description: The server has stopped
+        '202':
+          description: The server has been asked to stop, but is taking a while
+  /users/{name}/admin-access:
+    post:
+      summary: Grant an admin access to this user's server
+      parameters:
+        - name: name
+          description: username
+          in: path
+          required: true
+          type: string
+      responses:
+        '200':
+          description: Sets a cookie granting the requesting admin access to the user's server
+  /proxy:
+    get:
+      summary: Get the proxy's routing table
+      description: A convenience alias for getting the info directly from the proxy
+      responses:
+        '200':
+          description: Routing table
+          schema:
+            type: object
+            description: configurable-http-proxy routing table (see CHP 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.
+      parameters:
+        - name: data
+          in: body
+          required: true
+          description: Any values that have changed for the new proxy. All keys are optional.
+          schema:
+            type: object
+            properties:
+              ip:
+                type: string
+                description: IP address of the new proxy
+              port:
+                type: string
+                description: Port of the new proxy
+              protocol:
+                type: string
+                description: Protocol of new proxy, if changed
+              auth_token:
+                type: string
+                description: CONFIGPROXY_AUTH_TOKEN for the new proxy
+      responses:
+        '200':
+          description: Success
+  /authorizations/token/{token}:
+    get:
+      summary: Identify a user from an API token
+      parameters:
+      - name: token
+        in: path
+        required: true
+        type: string
+      responses:
+        '200':
+          description: The user identified by the API token
+          schema:
+            $ref: '#!/definitions/User'
+  /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
+      parameters:
+      - name: cookie_name
+        in: path
+        required: true
+        type: string
+      - name: cookie_value
+        in: path
+        required: true
+        type: string
+      responses:
+        '200':
+          description: The user identified by the cookie
+          schema:
+            $ref: '#!/definitions/User'
+  /shutdown:
+    post:
+      summary: Shutdown the Hub
+      responses:
+        '200':
+          description: Hub has shutdown
+definitions:
+  User:
+    type: object
+    properties:
+      name:
+        type: string
+        description: The user's name
+      admin:
+        type: boolean
+        description: Whether the user is an admin
+      server:
+        type: string
+        description: The user's server's base URL, if running; null if not.
+      pending:
+        type: string
+        enum: ["spawn", "stop"]
+        description: The currently pending action, if any
+      last_activity:
+        type: string
+        format: ISO8601 Timestamp
+        description: Timestamp of last-seen activity from the user

docs/source/api/auth.rst

@@ -0,0 +1,21 @@
+==============
+Authenticators
+==============
+
+Module: :mod:`jupyterhub.auth`
+==============================
+
+.. automodule:: jupyterhub.auth
+
+.. currentmodule:: jupyterhub.auth
+
+
+
+.. autoclass:: Authenticator
+    :members:
+
+.. autoclass:: LocalAuthenticator
+    :members:
+
+.. autoclass:: PAMAuthenticator
+

docs/source/api/index.rst

@@ -0,0 +1,14 @@
+.. _api-index:
+
+####################
+ The JupyterHub API
+####################
+
+:Release: |release|
+:Date: |today|
+
+.. toctree::
+
+    auth
+    spawner
+    user

docs/source/api/spawner.rst

@@ -0,0 +1,18 @@
+==============
+   Spawners
+==============
+
+Module: :mod:`jupyterhub.spawner`
+=================================
+
+.. automodule:: jupyterhub.spawner
+
+.. currentmodule:: jupyterhub.spawner
+
+:class:`Spawner`
+----------------
+
+.. autoclass:: Spawner
+    :members: options_from_form, poll, start, stop, get_args, get_env, get_state
+
+.. autoclass:: LocalProcessSpawner

docs/source/api/user.rst

@@ -0,0 +1,31 @@
+=============
+   Users
+=============
+
+Module: :mod:`jupyterhub.user`
+==============================
+
+.. automodule:: jupyterhub.user
+
+.. currentmodule:: jupyterhub.user
+
+:class:`User`
+-------------
+
+.. class:: Server
+
+.. autoclass:: User
+    :members: escaped_name
+    
+    .. attribute:: name
+    
+      The user's name
+    
+    .. attribute:: server
+    
+        The user's Server data object if running, None otherwise.
+        Has ``ip``, ``port`` attributes.
+
+    .. attribute:: spawner
+    
+        The user's :class:`~.Spawner` instance.

docs/source/authenticators.md

@@ -63,6 +63,36 @@ 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.
@@ -72,9 +102,9 @@ You can see an example implementation of an Authenticator that uses [GitHub OAut
 at [OAuthenticator][].
 
 
-[Authenticator]: ../jupyterhub/auth.py
-[PAM]: http://en.wikipedia.org/wiki/Pluggable_authentication_module
-[OAuth]: http://en.wikipedia.org/wiki/OAuth 
+[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

@@ -0,0 +1,39 @@
+# Summary of changes in JupyterHub
+
+See `git log` for a more detailed summary.
+
+## 0.4
+
+### 0.4.1
+
+Fix removal of `/login` page in 0.4.0, breaking some OAuth providers.
+
+### 0.4.0
+
+- Add `Spawner.user_options_form` for specifying an HTML form to present to users,
+  allowing users to influence the spawning of their own servers.
+- Add `Authenticator.pre_spawn_start` and `Authenticator.post_spawn_stop` hooks,
+  so that Authenticators can do setup or teardown (e.g. passing credentials to Spawner,
+  mounting data sources, etc.).
+  These methods are typically used with custom Authenticator+Spawner pairs.
+- 0.4 will be the last JupyterHub release where single-user servers running IPython 3 is supported instead of Notebook ≥ 4.0.
+
+
+## 0.3
+
+- No longer make the user starting the Hub an admin
+- start PAM sessions on login
+- hooks for Authenticators to fire before spawners start and after they stop,
+  allowing deeper interaction between Spawner/Authenticator pairs.
+- login redirect fixes
+
+## 0.2
+
+- Based on standalone traitlets instead of IPython.utils.traitlets
+- multiple users in admin panel
+- Fixes for usernames that require escaping
+
+## 0.1
+
+First preview release
+

docs/source/conf.py

@@ -0,0 +1,386 @@
+# -*- coding: utf-8 -*-
+#
+# JupyterHub documentation build configuration file, created by
+# sphinx-quickstart on Mon Jan  4 16:31:09 2016.
+#
+# This file is execfile()d with the current directory set to its
+# containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys
+import os
+import shlex
+
+# Needed for conversion from markdown to html
+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('.'))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+needs_sphinx = '1.3'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.napoleon',
+]
+
+# 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'
+
+# General information about the project.
+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
+from os.path import dirname
+root = dirname(dirname(dirname(__file__)))
+sys.path.insert(0, root)
+
+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
+
+
+# -- 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'
+
+# 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 = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+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 = []
+
+# 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'
+
+# 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',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+  (master_doc, 'JupyterHub.tex', u'JupyterHub Documentation',
+   u'Project Jupyter team', 'manual'),
+]
+
+# 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 ---------------------------------------
+
+# 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)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for 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'),
+]
+
+# 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 ----------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+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
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# 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:  # 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()]
+
+# otherwise, readthedocs.org uses their theme by default, so no need to specify it

docs/source/getting-started.md

@@ -6,7 +6,7 @@ JupyterHub is highly customizable, so there's a lot to cover.
 
 ## Installation
 
-See [the readme](../README.md) for help installing JupyterHub.
+See [the readme](https://github.com/jupyter/jupyterhub/blob/master/README.md) for help installing JupyterHub.
 
 
 ## Overview
@@ -14,11 +14,11 @@ See [the readme](../README.md) for help installing JupyterHub.
 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*.
+- **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
 
@@ -34,29 +34,29 @@ Any user on the system with a password will be allowed to start a single-user no
 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:
+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*,
+In their default configuration, the other services, the **Hub** and **Single-User Servers**,
 all communicate with each other on localhost only.
 
 **NOTE:** In its default configuration, JupyterHub runs without SSL encryption (HTTPS).
 You should not run JupyterHub without SSL encryption on a public network.
-See [below](#Security) for how to configure JupyterHub to use SSL.
+See [Security documentation](#Security) for how to configure JupyterHub to use SSL.
 
 By default, starting JupyterHub will write two files to disk in the current working directory:
 
-- `jupyterhub.sqlite` is the sqlite database containing all of the state of the *Hub*.
-  This file allows the *Hub* to remember what users are running and where,
+- `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 [below](#Security).
+  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.
 
@@ -85,9 +85,8 @@ 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:
-
+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
 
@@ -97,32 +96,37 @@ on the config system Jupyter uses.
 
 ## Networking
 
-In most situations you will want to change the main IP address and port of the Proxy.
-This address determines where JupyterHub is available to your users.
-The default is all network interfaces (`''`) on port 8000.
+### 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.
 
-This can be done with the following command line arguments:
+Changing the IP address and port can be done with the following command line
+arguments:
 
     jupyterhub --ip=192.168.1.2 --port=443
 
-Or you can put the following lines in a configuration file:
+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 in these examples as it is the default port for SSL/HTTPS.
+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, for more customized scenarios,
-you can configure the following additional networking details.
+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 you want to run the Proxy separate from the Hub,
-you may need to configure this IP and port with:
+
+If running the Proxy separate from the Hub,
+configure the REST API communication IP address and port with:
 
 ```python
 # ideally a private network address
@@ -130,11 +134,12 @@ 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 localhost is fine,
-but 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.
+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'
@@ -143,63 +148,92 @@ c.JupyterHub.hub_port = 54321
 
 ## Security
 
-First of all, 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 SSL certificate or create a self-signed certificate.
-Once you have obtained and installed a key and certificate
-you need to pass their locations to JupyterHub's configuration as follows:
+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'
 ```
 
-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.
-
-There are two other aspects of JupyterHub network security.
-
-The cookie secret is an encryption key, used to encrypt the 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 the file `jupyterhub_cookie_secret`,
-which can be specified with:
+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.cookie_secret_file = '/path/to/jupyterhub_cookie_secret'
+c.JupyterHub.ssl_key = '/etc/letsencrypt/live/your.domain.com/privkey.pem'
+c.JupyterHub.ssl_cert = '/etc/letsencrypt/live/your.domain.com/fullchain.pem'
 ```
 
-In most deployments of JupyterHub, you should point this to a secure location on the file system.
-If the cookie secret file doesn't exist when the Hub starts,
-a new cookie secret is generated and stored in the file.
+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 would like to avoid the need for files,
-the value can be loaded in the Hub process from the `JPY_COOKIE_SECRET` env variable:
+## Cookie secret
+
+The cookie secret is an encryption key, used to encrypt the browser cookies used for
+authentication. If this value changes for the Hub, all single-user servers must also be restarted.
+Normally, this value is stored in a file, the location of which can be specified in a config file
+as follows:
+
+```python
+c.JupyterHub.cookie_secret_file = '/srv/jupyterhub/cookie_secret'
+```
+
+The content of this file should be a long random string. An example would be to generate this
+file as:
+
+```bash
+openssl rand -hex 1024 > /srv/jupyterhub/cookie_secret
+```
+
+In most deployments of JupyterHub, you should point this to a secure location on the file
+system, such as `/srv/jupyterhub/cookie_secret`. If the cookie secret file doesn't exist when
+the Hub starts, a new cookie secret is generated and stored in the file. The recommended
+permissions for the cookie secret file should be 600 (owner-only rw).
+
+If you would like to avoid the need for files, the value can be loaded in the Hub process from
+the `JPY_COOKIE_SECRET` environment variable:
 
 ```bash
 export JPY_COOKIE_SECRET=`openssl rand -hex 1024`
 ```
 
-For security reasons, this env variable should only be visible to the Hub.
+For security reasons, this environment variable should only be visible to the Hub.
 
-The Hub authenticates its requests to the Proxy via an environment variable, `CONFIGPROXY_AUTH_TOKEN`.
-If you want to be able to start or restart the proxy or Hub independently of each other (not always necessary),
-you must set this environment variable before starting the server (for both the Hub and Proxy):
+## 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 env variable needs to be visible to the Hub and Proxy.
-If you don't set this, 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).
+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'
+```
 
-## Configuring Authentication
+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.
@@ -227,47 +261,39 @@ then admin users have permission to log in *as other users* on their respective
 
 ### 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,
+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
-
+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 `useradd` mechanism.
-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.
-
+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 `ipython 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.
+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.
+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'
@@ -376,14 +402,13 @@ export CONFIGPROXY_AUTH_TOKEN=super-secret
 jupyterhub -f /path/to/aboveconfig.py
 ```
 
-
 # Further reading
 
-- TODO: troubleshooting
-- [Custom Authenticators](authenticators.md)
-- [Custom Spawners](spawners.md)
+- [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]: http://en.wikipedia.org/wiki/Pluggable_authentication_module
+[PAM]: https://en.wikipedia.org/wiki/Pluggable_authentication_module

docs/source/howitworks.md

@@ -5,7 +5,7 @@ JupyterHub is a multi-user server that manages and proxies multiple instances of
 There are three basic processes involved:
 
 - multi-user Hub (Python/Tornado)
-- configurable http proxy (nodejs)
+- [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.
@@ -51,7 +51,7 @@ Authentication is customizable via the Authenticator class.
 Authentication can be replaced by any mechanism,
 such as OAuth, Kerberos, etc.
 
-JupyterHub only ships with [PAM](http://en.wikipedia.org/wiki/Pluggable_authentication_module) authentication,
+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

docs/source/index.rst

@@ -0,0 +1,81 @@
+.. JupyterHub documentation master file, created by
+   sphinx-quickstart on Mon Jan  4 16:31:09 2016.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+JupyterHub
+==========
+
+.. note:: This is the official documentation for JupyterHub. This project is
+          under active development.
+
+JupyterHub is a multi-user server that manages and proxies multiple instances
+of the single-user Jupyter notebook server.
+
+Three actors:
+
+* multi-user Hub (tornado process)
+* `configurable http proxy <https://github.com/jupyter/configurable-http-proxy>`_ (node-http-proxy)
+* multiple single-user IPython notebook servers (Python/IPython/tornado)
+
+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
+
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Documentation
+
+   getting-started
+   howitworks
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Configuration
+
+   authenticators
+   spawners
+   troubleshooting
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Developer Documentation
+   
+   api/index
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Community documentation
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: About JupyterHub
+
+   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>
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

docs/source/spawners.md

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

docs/source/troubleshooting.md

@@ -0,0 +1,11 @@
+# Troubleshooting
+
+This document is under active development.
+
+## Networking
+
+If JupyterHub proxy fails to start:
+
+- check if the JupyterHub IP configuration setting is
+  ``c.JupyterHub.ip = '*'``; if it is, try ``c.JupyterHub.ip = ''``
+- Try starting with ``jupyterhub --ip=0.0.0.0``

docs/spawners.md

@@ -1,89 +0,0 @@
-# Writing a custom Spawner
-
-Each single-user server is started by a [Spawner][].
-The Spawner represents an abstract interface to a process,
-and a custom Spawner needs to be able to take three actions:
-
-1. start the process
-2. poll whether the process is still running
-3. stop the process
-
-See a list of custom Spawners [on the wiki](https://github.com/jupyter/jupyterhub/wiki/Spawners).
-
-
-## Spawner.start
-
-`Spawner.start` should start the single-user server for a single user.
-Information about the user can be retrieved from `self.user`,
-an object encapsulating the user's name, authentication, and server info.
-
-When `Spawner.start` returns, it should have stored the IP and port
-of the single-user server in `self.user.server`.
-
-**NOTE:** when writing coroutines, *never* `yield` in between a db change and a commit.
-Most `Spawner.start`s should have something looking like:
-
-```python
-def start(self):
-    self.user.server.ip = 'localhost' # or other host or IP address, as seen by the Hub
-    self.user.server.port = 1234 # port selected somehow
-    self.db.commit() # always commit before yield, if modifying db values
-    yield self._actually_start_server_somehow()
-```
-
-When `Spawner.start` returns, the single-user server process should actually be running,
-not just requested. JupyterHub can handle `Spawner.start` being very slow
-(such as PBS-style batch queues, or instantiating whole AWS instances)
-via relaxing the `Spawner.start_timeout` config value.
-
-
-## Spawner.poll
-
-`Spawner.poll` should check if the spawner is still running.
-It should return `None` if it is still running,
-and an integer exit status, otherwise.
-
-For the local process case, this uses `os.kill(PID, 0)`
-to check if the process is still around.
-
-
-## Spawner.stop
-
-`Spawner.stop` should stop the process. It must be a tornado coroutine,
-and should return when the process has finished exiting.
-
-
-## Spawner state
-
-JupyterHub should be able to stop and restart without having to teardown
-single-user servers. This means that a Spawner may need to persist
-some information that it can be restored.
-A dictionary of JSON-able state can be used to store this information.
-
-Unlike start/stop/poll, the state methods must not be coroutines.
-
-In the single-process case, this is only the process ID of the server:
-
-```python
-def get_state(self):
-    """get the current state"""
-    state = super().get_state()
-    if self.pid:
-        state['pid'] = self.pid
-    return state
-
-def load_state(self, state):
-    """load state from the database"""
-    super().load_state(state)
-    if 'pid' in state:
-        self.pid = state['pid']
-
-def clear_state(self):
-    """clear any state (called after shutdown)"""
-    super().clear_state()
-    self.pid = 0
-```
-
-
-
-[Spawner]: ../jupyterhub/spawner.py

examples/spawn-form/jupyterhub_config.py

@@ -0,0 +1,46 @@
+"""
+Example JuptyerHub config allowing users to specify environment variables and notebook-server args
+"""
+import shlex
+
+from jupyterhub.spawner import LocalProcessSpawner
+
+class DemoFormSpawner(LocalProcessSpawner):
+    def _options_form_default(self):
+        default_env = "YOURNAME=%s\n" % self.user.name
+        return """
+        <label for="args">Extra notebook CLI arguments</label>
+        <input name="args" placeholder="e.g. --debug"></input>
+        <label for="env">Environment variables (one per line)</label>
+        <textarea name="env">{env}</textarea>
+        """.format(env=default_env)
+    
+    def options_from_form(self, formdata):
+        options = {}
+        options['env'] = env = {}
+        
+        env_lines = formdata.get('env', [''])
+        for line in env_lines[0].splitlines():
+            if line:
+                key, value = line.split('=', 1)
+                env[key.strip()] = value.strip()
+        
+        arg_s = formdata.get('args', [''])[0].strip()
+        if arg_s:
+            options['argv'] = shlex.split(arg_s)
+        return options
+    
+    def get_args(self):
+        """Return arguments to pass to the notebook server"""
+        argv = super().get_args()
+        if self.user_options.get('argv'):
+            argv.extend(self.user_options['argv'])
+        return argv
+    
+    def get_env(self):
+        env = super().get_env()
+        if self.user_options.get('env'):
+            env.update(self.user_options['env'])
+        return env
+
+c.JupyterHub.spawner_class = DemoFormSpawner

jupyterhub/apihandlers/auth.py

@@ -18,7 +18,7 @@ class TokenAPIHandler(APIHandler):
         orm_token = orm.APIToken.find(self.db, token)
         if orm_token is None:
             raise web.HTTPError(404)
-        self.write(json.dumps(self.user_model(orm_token.user)))
+        self.write(json.dumps(self.user_model(self.users[orm_token.user])))
 
 
 class CookieAPIHandler(APIHandler):

jupyterhub/apihandlers/users.py

@@ -15,7 +15,7 @@ from .base import APIHandler
 class UserListAPIHandler(APIHandler):
     @admin_only
     def get(self):
-        users = self.db.query(orm.User)
+        users = [ self._user_from_orm(u) for u in self.db.query(orm.User) ]
         data = [ self.user_model(u) for u in users ]
         self.write(json.dumps(data))
     
@@ -33,13 +33,25 @@ class UserListAPIHandler(APIHandler):
         admin = data.get('admin', False)
         
         to_create = []
+        invalid_names = []
         for name in usernames:
+            name = self.authenticator.normalize_username(name)
+            if not self.authenticator.validate_username(name):
+                invalid_names.append(name)
+                continue
             user = self.find_user(name)
             if user is not None:
                 self.log.warn("User %s already exists" % name)
             else:
                 to_create.append(name)
         
+        if invalid_names:
+            if len(invalid_names) == 1:
+                msg = "Invalid username: %s" % invalid_names[0]
+            else:
+                msg = "Invalid usernames: %s" % ', '.join(invalid_names)
+            raise web.HTTPError(400, msg)
+        
         if not to_create:
             raise web.HTTPError(400, "All %i users already exist" % len(usernames))
         
@@ -51,11 +63,10 @@ class UserListAPIHandler(APIHandler):
                 self.db.commit()
             try:
                 yield gen.maybe_future(self.authenticator.add_user(user))
-            except Exception:
+            except Exception as e:
                 self.log.error("Failed to create user: %s" % name, exc_info=True)
-                self.db.delete(user)
-                self.db.commit()
-                raise web.HTTPError(400, "Failed to create user: %s" % name)
+                del self.users[user]
+                raise web.HTTPError(400, "Failed to create user %s: %s" % (name, str(e)))
             else:
                 created.append(user)
         
@@ -104,8 +115,8 @@ class UserAPIHandler(APIHandler):
             yield gen.maybe_future(self.authenticator.add_user(user))
         except Exception:
             self.log.error("Failed to create user: %s" % name, exc_info=True)
-            self.db.delete(user)
-            self.db.commit()
+            # remove from registry
+            del self.users[user]
             raise web.HTTPError(400, "Failed to create user: %s" % name)
         
         self.write(json.dumps(self.user_model(user)))
@@ -127,10 +138,8 @@ class UserAPIHandler(APIHandler):
                 raise web.HTTPError(400, "%s's server is in the process of stopping, please wait." % name)
         
         yield gen.maybe_future(self.authenticator.delete_user(user))
-        
-        # remove from the db
-        self.db.delete(user)
-        self.db.commit()
+        # remove from registry
+        del self.users[user]
         
         self.set_status(204)
     
@@ -157,7 +166,8 @@ class UserServerAPIHandler(APIHandler):
             if state is None:
                 raise web.HTTPError(400, "%s's server is already running" % name)
 
-        yield self.spawn_single_user(user)
+        options = self.get_json_body()
+        yield self.spawn_single_user(user, options=options)
         status = 202 if user.spawn_pending else 201
         self.set_status(status)
 

jupyterhub/app.py

@@ -45,11 +45,12 @@ from . import handlers, apihandlers
 from .handlers.static import CacheControlStaticFilesHandler
 
 from . import orm
+from .user import User, UserDict
 from ._data import DATA_FILES_PATH
 from .log import CoroutineLogFormatter, log_request
 from .traitlets import URLPrefix, Command
 from .utils import (
-    url_path_join,
+    url_path_join, localhost,
     ISO8601_ms, ISO8601_s,
 )
 # classes for config
@@ -259,7 +260,7 @@ class JupyterHub(Application):
             token = orm.new_token()
         return token
     
-    proxy_api_ip = Unicode('localhost', config=True,
+    proxy_api_ip = Unicode(localhost(), config=True,
         help="The ip for the proxy API handlers"
     )
     proxy_api_port = Integer(config=True,
@@ -271,7 +272,7 @@ class JupyterHub(Application):
     hub_port = Integer(8081, config=True,
         help="The port for this process"
     )
-    hub_ip = Unicode('localhost', config=True,
+    hub_ip = Unicode(localhost(), config=True,
         help="The ip for this process"
     )
     
@@ -349,6 +350,11 @@ class JupyterHub(Application):
     )
     session_factory = Any()
     
+    users = Instance(UserDict)
+    def _users_default(self):
+        assert self.tornado_settings
+        return UserDict(db_factory=lambda : self.db, settings=self.tornado_settings)
+    
     admin_access = Bool(False, config=True,
         help="""Grant admin users permission to access single-user servers.
         
@@ -464,13 +470,12 @@ class JupyterHub(Application):
     
     def init_handlers(self):
         h = []
-        h.extend(handlers.default_handlers)
-        h.extend(apihandlers.default_handlers)
         # load handlers from the authenticator
         h.extend(self.authenticator.get_handlers(self))
-
+        # set default handlers
+        h.extend(handlers.default_handlers)
+        h.extend(apihandlers.default_handlers)
         self.handlers = self.add_url_prefix(self.hub_prefix, h)
-
         # some extra handlers, outside hub_prefix
         self.handlers.extend([
             (r"%s" % self.hub_prefix.rstrip('/'), web.RedirectHandler,
@@ -625,7 +630,13 @@ class JupyterHub(Application):
                 "\nUse Authenticator.admin_users instead."
             )
             self.authenticator.admin_users = self.admin_users
-        admin_users = self.authenticator.admin_users
+        admin_users = [
+            self.authenticator.normalize_username(name)
+            for name in self.authenticator.admin_users
+        ]
+        for username in admin_users:
+            if not self.authenticator.validate_username(username):
+                raise ValueError("username %r is not valid" % username)
         
         if not admin_users:
             self.log.warning("No admin users, admin interface will be unavailable.")
@@ -646,7 +657,13 @@ class JupyterHub(Application):
         # the admin_users config variable will never be used after this point.
         # only the database values will be referenced.
 
-        whitelist = self.authenticator.whitelist
+        whitelist = [
+            self.authenticator.normalize_username(name)
+            for name in self.authenticator.whitelist
+        ]
+        for username in whitelist:
+            if not self.authenticator.validate_username(username):
+                raise ValueError("username %r is not valid" % username)
 
         if not whitelist:
             self.log.info("Not using whitelist. Any authenticated user will be allowed.")
@@ -666,7 +683,7 @@ class JupyterHub(Application):
             # but changes to the whitelist can occur in the database,
             # and persist across sessions.
             for user in db.query(orm.User):
-                whitelist.add(user.name)
+                self.authenticator.whitelist.add(user.name)
 
         # The whitelist set and the users in the db are now the same.
         # From this point on, any user changes should be done simultaneously
@@ -700,17 +717,15 @@ class JupyterHub(Application):
             yield self.proxy.delete_user(user)
             yield user.stop()
         
-        for user in db.query(orm.User):
+        for orm_user in db.query(orm.User):
+            self.users[orm_user.id] = user = User(orm_user, self.tornado_settings)
             if not user.state:
                 # without spawner state, server isn't valid
                 user.server = None
                 user_summaries.append(_user_summary(user))
                 continue
             self.log.debug("Loading state for %s from db", user.name)
-            user.spawner = spawner = self.spawner_class(
-                user=user, hub=self.hub, config=self.config, db=self.db,
-                authenticator=self.authenticator,
-            )
+            spawner = user.spawner
             status = yield spawner.poll()
             if status is None:
                 self.log.info("%s still running", user.name)
@@ -831,9 +846,13 @@ class JupyterHub(Application):
     def init_tornado_settings(self):
         """Set up the tornado settings dict."""
         base_url = self.hub.server.base_url
+        jinja_options = dict(
+            autoescape=True,
+        )
+        jinja_options.update(self.jinja_environment_options)
         jinja_env = Environment(
             loader=FileSystemLoader(self.template_paths),
-            **self.jinja_environment_options
+            **jinja_options
         )
         
         login_url = self.authenticator.login_url(base_url)
@@ -873,6 +892,8 @@ class JupyterHub(Application):
         # allow configured settings to have priority
         settings.update(self.tornado_settings)
         self.tornado_settings = settings
+        # constructing users requires access to tornado_settings
+        self.tornado_settings['users'] = self.users
     
     def init_tornado_application(self):
         """Instantiate the tornado Application object"""
@@ -909,9 +930,9 @@ class JupyterHub(Application):
         self.init_hub()
         self.init_proxy()
         yield self.init_users()
+        self.init_tornado_settings()
         yield self.init_spawners()
         self.init_handlers()
-        self.init_tornado_settings()
         self.init_tornado_application()
     
     @gen.coroutine
@@ -922,7 +943,7 @@ class JupyterHub(Application):
         if self.cleanup_servers:
             self.log.info("Cleaning up single-user servers...")
             # request (async) process termination
-            for user in self.db.query(orm.User):
+            for uid, user in self.users.items():
                 if user.spawner is not None:
                     futures.append(user.stop())
         else:

jupyterhub/auth.py

@@ -1,25 +1,31 @@
-"""Simple PAM authenticator"""
+"""Base Authenticator class and the default PAM Authenticator"""
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
 from grp import getgrnam
+import pipes
 import pwd
-from subprocess import check_call, check_output, CalledProcessError
+import re
+from shutil import which
+import sys
+from subprocess import Popen, PIPE, STDOUT
 
 from tornado import gen
 import pamela
 
 from traitlets.config import LoggingConfigurable
-from traitlets import Bool, Set, Unicode, Any
+from traitlets import Bool, Set, Unicode, Dict, Any
 
 from .handlers.login import LoginHandler
 from .utils import url_path_join
+from .traitlets import Command
 
 class Authenticator(LoggingConfigurable):
     """A class for authentication.
     
-    The API is one method, `authenticate`, a tornado gen.coroutine.
+    The primary API is one method, `authenticate`, a tornado coroutine
+    for authenticating users.
     """
     
     db = Any()
@@ -49,6 +55,88 @@ class Authenticator(LoggingConfigurable):
         """
     )
     
+    username_pattern = Unicode(config=True,
+        help="""Regular expression pattern for validating usernames.
+        
+        If not defined: allow any username.
+        """
+    )
+    def _username_pattern_changed(self, name, old, new):
+        if not new:
+            self.username_regex = None
+        self.username_regex = re.compile(new)
+    
+    username_regex = Any()
+    
+    def validate_username(self, username):
+        """Validate a (normalized) username.
+        
+        Return True if username is valid, False otherwise.
+        """
+        if not self.username_regex:
+            return True
+        return bool(self.username_regex.match(username))
+    
+    username_map = Dict(config=True,
+        help="""Dictionary mapping authenticator usernames to JupyterHub users.
+        
+        Can be used to map OAuth service names to local users, for instance.
+        
+        Used in normalize_username.
+        """
+    )
+    
+    def normalize_username(self, username):
+        """Normalize a username.
+        
+        Override in subclasses if usernames should have some normalization.
+        Default: cast to lowercase, lookup in username_map.
+        """
+        username = username.lower()
+        username = self.username_map.get(username, username)
+        return username
+    
+    def check_whitelist(self, username):
+        """Check a username against our whitelist.
+        
+        Return True if username is allowed, False otherwise.
+        No whitelist means any username should be allowed.
+        
+        Names are normalized *before* being checked against the whitelist.
+        """
+        if not self.whitelist:
+            # No whitelist means any name is allowed
+            return True
+        return username in self.whitelist
+    
+    @gen.coroutine
+    def get_authenticated_user(self, handler, data):
+        """This is the outer API for authenticating a user.
+        
+        This calls `authenticate`, which should be overridden in subclasses,
+        normalizes the username if any normalization should be done,
+        and then validates the name in the whitelist.
+        
+        Subclasses should not need to override this method.
+        The various stages can be overridden separately:
+        
+        - authenticate turns formdata into a username
+        - normalize_username normalizes the username
+        - check_whitelist checks against the user whitelist
+        """
+        username = yield self.authenticate(handler, data)
+        if username is None:
+            return
+        username = self.normalize_username(username)
+        if not self.validate_username(username):
+            self.log.warning("Disallowing invalid username %r.", username)
+            return
+        if self.check_whitelist(username):
+            return username
+        else:
+            self.log.warning("User %r not in whitelist.", username)
+            return
+    
     @gen.coroutine
     def authenticate(self, handler, data):
         """Authenticate a user with login form data.
@@ -56,6 +144,16 @@ class Authenticator(LoggingConfigurable):
         This must be a tornado gen.coroutine.
         It must return the username on successful authentication,
         and return None on failed authentication.
+        
+        Checking the whitelist is handled separately by the caller.
+
+        Args:
+            handler (tornado.web.RequestHandler): the current request handler
+            data (dict): The formdata of the login form.
+                         The default form has 'username' and 'password' fields.
+        Return:
+            str: the username of the authenticated user
+            None: Authentication failed
         """
 
     def pre_spawn_start(self, user, spawner):
@@ -70,21 +168,20 @@ class Authenticator(LoggingConfigurable):
         Can be used to do auth-related cleanup, e.g. closing PAM sessions.
         """
     
-    def check_whitelist(self, user):
-        """
-        Return True if the whitelist is empty or user is in the whitelist.
-        """
-        # Parens aren't necessary here, but they make this easier to parse.
-        return (not self.whitelist) or (user in self.whitelist)
-
     def add_user(self, user):
         """Add a new user
         
         By default, this just adds the user to the whitelist.
         
         Subclasses may do more extensive things,
-        such as adding actual unix users.
+        such as adding actual unix users,
+        but they should call super to ensure the whitelist is updated.
+
+        Args:
+            user (User): The User wrapper object
         """
+        if not self.validate_username(user.name):
+            raise ValueError("Invalid username: %s" % user.name)
         if self.whitelist:
             self.whitelist.add(user.name)
     
@@ -92,29 +189,60 @@ class Authenticator(LoggingConfigurable):
         """Triggered when a user is deleted.
         
         Removes the user from the whitelist.
+        Subclasses should call super to ensure the whitelist is updated.
+        
+        Args:
+            user (User): The User wrapper object
         """
         self.whitelist.discard(user.name)
     
     def login_url(self, base_url):
-        """Override to register a custom login handler"""
+        """Override to register a custom login handler
+        
+        Generally used in combination with get_handlers.
+        
+        Args:
+            base_url (str): the base URL of the Hub (e.g. /hub/)
+        
+        Returns:
+            str: The login URL, e.g. '/hub/login'
+        
+        """
         return url_path_join(base_url, 'login')
     
     def logout_url(self, base_url):
-        """Override to register a custom logout handler"""
+        """Override to register a custom logout handler.
+        
+        Generally used in combination with get_handlers.
+        
+        Args:
+            base_url (str): the base URL of the Hub (e.g. /hub/)
+        
+        Returns:
+            str: The logout URL, e.g. '/hub/logout'
+        """
         return url_path_join(base_url, 'logout')
     
     def get_handlers(self, app):
         """Return any custom handlers the authenticator needs to register
         
-        (e.g. for OAuth)
+        (e.g. for OAuth).
+        
+        Args:
+            app (JupyterHub Application):
+                the application object, in case it needs to be accessed for info.
+        Returns:
+            list: list of ``('/url', Handler)`` tuples passed to tornado.
+                The Hub prefix is added to any URLs.
+        
         """
         return [
             ('/login', LoginHandler),
         ]
 
 class LocalAuthenticator(Authenticator):
-    """Base class for Authenticators that work with local *ix users
-    
+    """Base class for Authenticators that work with local Linux/UNIX users
+
     Checks for local users, and can attempt to create them if they exist.
     """
     
@@ -123,6 +251,36 @@ class LocalAuthenticator(Authenticator):
         should I try to create the system user?
         """
     )
+    add_user_cmd = Command(config=True,
+        help="""The command to use for creating users as a list of strings.
+        
+        For each element in the list, the string USERNAME will be replaced with
+        the user's username. The username will also be appended as the final argument.
+        
+        For Linux, the default value is:
+        
+            ['adduser', '-q', '--gecos', '""', '--disabled-password']
+            
+        To specify a custom home directory, set this to:
+        
+            ['adduser', '-q', '--gecos', '""', '--home', '/customhome/USERNAME', '--disabled-password']
+
+        This will run the command:
+
+        adduser -q --gecos "" --home /customhome/river --disabled-password river
+        
+        when the user 'river' is created.
+        """
+    )
+    def _add_user_cmd_default(self):
+        if sys.platform == 'darwin':
+            raise ValueError("I don't know how to create users on OS X")
+        elif which('pw'):
+            # Probably BSD
+            return ['pw', 'useradd', '-m']
+        else:
+            # This appears to be the Linux non-interactive adduser command:
+            return ['adduser', '-q', '--gecos', '""', '--disabled-password']
 
     group_whitelist = Set(
         config=True,
@@ -158,10 +316,7 @@ class LocalAuthenticator(Authenticator):
     def add_user(self, user):
         """Add a new user
         
-        By default, this just adds the user to the whitelist.
-        
-        Subclasses may do more extensive things,
-        such as adding actual unix users.
+        If self.create_system_users, the user will attempt to be created.
         """
         user_exists = yield gen.maybe_future(self.system_user_exists(user))
         if not user_exists:
@@ -181,29 +336,21 @@ class LocalAuthenticator(Authenticator):
             return False
         else:
             return True
-    
-    @staticmethod
-    def add_system_user(user):
-        """Create a new *ix user on the system. Works on FreeBSD and Linux, at least."""
+
+    def add_system_user(self, user):
+        """Create a new Linux/UNIX user on the system. Works on FreeBSD and Linux, at least."""
         name = user.name
-        for useradd in (
-            ['pw', 'useradd', '-m'],
-            ['useradd', '-m'],
-        ):
-            try:
-                check_output(['which', useradd[0]])
-            except CalledProcessError:
-                continue
-            else:
-                break
-        else:
-            raise RuntimeError("I don't know how to add users on this system.")
-    
-        check_call(useradd + [name])
+        cmd = [ arg.replace('USERNAME', name) for arg in self.add_user_cmd ] + [name]
+        self.log.info("Creating user: %s", ' '.join(map(pipes.quote, cmd)))
+        p = Popen(cmd, stdout=PIPE, stderr=STDOUT)
+        p.wait()
+        if p.returncode:
+            err = p.stdout.read().decode('utf8', 'replace')
+            raise RuntimeError("Failed to create system user %s: %s" % (name, err))
 
 
 class PAMAuthenticator(LocalAuthenticator):
-    """Authenticate local *ix users with PAM"""
+    """Authenticate local Linux/UNIX users with PAM"""
     encoding = Unicode('utf8', config=True,
         help="""The encoding to use for PAM"""
     )
@@ -218,12 +365,13 @@ class PAMAuthenticator(LocalAuthenticator):
         Return None otherwise.
         """
         username = data['username']
-        if not self.check_whitelist(username):
-            return
         try:
             pamela.authenticate(username, data['password'], service=self.service)
         except pamela.PAMError as e:
-            self.log.warn("PAM Authentication failed: %s", e)
+            if handler is not None:
+                self.log.warn("PAM Authentication failed (@%s): %s", handler.request.remote_ip, e)
+            else:
+                self.log.warn("PAM Authentication failed: %s", e)
         else:
             return username
     

jupyterhub/handlers/base.py

@@ -4,7 +4,7 @@
 # Distributed under the terms of the Modified BSD License.
 
 import re
-from datetime import datetime, timedelta
+from datetime import timedelta
 from http.client import responses
 
 from jinja2 import TemplateNotFound
@@ -16,6 +16,7 @@ from tornado.web import RequestHandler
 from tornado import gen, web
 
 from .. import orm
+from ..user import User
 from ..spawner import LocalProcessSpawner
 from ..utils import url_path_join
 
@@ -53,7 +54,11 @@ class BaseHandler(RequestHandler):
     @property
     def db(self):
         return self.settings['db']
-
+    
+    @property
+    def users(self):
+        return self.settings.setdefault('users', {})
+    
     @property
     def hub(self):
         return self.settings['hub']
@@ -145,13 +150,20 @@ class BaseHandler(RequestHandler):
                 clear()
             return
         cookie_id = cookie_id.decode('utf8', 'replace')
-        user = self.db.query(orm.User).filter(orm.User.cookie_id==cookie_id).first()
+        u = self.db.query(orm.User).filter(orm.User.cookie_id==cookie_id).first()
+        user = self._user_from_orm(u)
         if user is None:
             self.log.warn("Invalid cookie token")
             # have cookie, but it's not valid. Clear it and start over.
             clear()
         return user
     
+    def _user_from_orm(self, orm_user):
+        """return User wrapper from orm.User object"""
+        if orm_user is None:
+            return
+        return self.users[orm_user]
+    
     def get_current_user_cookie(self):
         """get_current_user from a cookie token"""
         return self._user_for_cookie(self.hub.server.cookie_name)
@@ -168,15 +180,18 @@ class BaseHandler(RequestHandler):
         
         return None if no such user
         """
-        return orm.User.find(self.db, name)
+        orm_user = orm.User.find(db=self.db, name=name)
+        return self._user_from_orm(orm_user)
 
     def user_from_username(self, username):
-        """Get ORM User for username"""
+        """Get User for username, creating if it doesn't exist"""
         user = self.find_user(username)
         if user is None:
-            user = orm.User(name=username)
-            self.db.add(user)
+            # not found, create and register user
+            u = orm.User(name=username)
+            self.db.add(u)
             self.db.commit()
+            user = self._user_from_orm(u)
         return user
     
     def clear_login_cookie(self, name=None):
@@ -232,7 +247,7 @@ class BaseHandler(RequestHandler):
     def authenticate(self, data):
         auth = self.authenticator
         if auth is not None:
-            result = yield auth.authenticate(self, data)
+            result = yield auth.get_authenticated_user(self, data)
             return result
         else:
             self.log.error("No authentication function, login is impossible!")
@@ -253,20 +268,15 @@ class BaseHandler(RequestHandler):
     @property
     def spawner_class(self):
         return self.settings.get('spawner_class', LocalProcessSpawner)
-
+    
     @gen.coroutine
-    def spawn_single_user(self, user):
+    def spawn_single_user(self, user, options=None):
         if user.spawn_pending:
             raise RuntimeError("Spawn already pending for: %s" % user.name)
         tic = IOLoop.current().time()
-        
-        f = user.spawn(
-            spawner_class=self.spawner_class,
-            base_url=self.base_url,
-            hub=self.hub,
-            config=self.config,
-            authenticator=self.authenticator,
-        )
+
+        f = user.spawn(options)
+
         @gen.coroutine
         def finish_user_spawn(f=None):
             """Finish the user spawn by registering listeners and notifying the proxy.
@@ -286,10 +296,14 @@ class BaseHandler(RequestHandler):
             yield gen.with_timeout(timedelta(seconds=self.slow_spawn_timeout), f)
         except gen.TimeoutError:
             if user.spawn_pending:
-                # hit timeout, but spawn is still pending
-                self.log.warn("User %s server is slow to start", user.name)
-                # schedule finish for when the user finishes spawning
-                IOLoop.current().add_future(f, finish_user_spawn)
+                status = yield user.spawner.poll()
+                if status is None:
+                    # hit timeout, but spawn is still pending
+                    self.log.warn("User %s server is slow to start", user.name)
+                    # schedule finish for when the user finishes spawning
+                    IOLoop.current().add_future(f, finish_user_spawn)
+                else:
+                    raise web.HTTPError(500, "Spawner failed to start [status=%s]" % status)
             else:
                 raise
         else:
@@ -442,9 +456,11 @@ class UserSpawnHandler(BaseHandler):
                 # spawn has supposedly finished, check on the status
                 status = yield current_user.spawner.poll()
                 if status is not None:
-                    yield self.spawn_single_user(current_user)
-            else:
-                yield self.spawn_single_user(current_user)
+                    if current_user.spawner.options_form:
+                        self.redirect(url_path_join(self.hub.server.base_url, 'spawn'))
+                        return
+                    else:
+                        yield self.spawn_single_user(current_user)
             # set login cookie anew
             self.set_login_cookie(current_user)
             without_prefix = self.request.uri[len(self.hub.server.base_url):]

jupyterhub/handlers/login.py

@@ -30,10 +30,10 @@ class LoginHandler(BaseHandler):
                 next=url_escape(self.get_argument('next', default='')),
                 username=username,
                 login_error=login_error,
-                custom_login_form=self.authenticator.custom_html,
+                custom_html=self.authenticator.custom_html,
                 login_url=self.settings['login_url'],
         )
-    
+
     def get(self):
         next_url = self.get_argument('next', '')
         if not next_url.startswith('/'):
@@ -68,7 +68,7 @@ class LoginHandler(BaseHandler):
             if user.spawner:
                 status = yield user.spawner.poll()
                 already_running = (status == None)
-            if not already_running:
+            if not already_running and not user.spawner.options_form:
                 yield self.spawn_single_user(user)
             self.set_login_cookie(user)
             next_url = self.get_argument('next', default='')
@@ -86,7 +86,9 @@ class LoginHandler(BaseHandler):
             self.finish(html)
 
 
-# Only logout is a default handler.
+# /login renders the login page or the "Login with..." link,
+# so it should always be registered.
+# /logout clears cookies.
 default_handlers = [
     (r"/login", LoginHandler),
     (r"/logout", LogoutHandler),

jupyterhub/handlers/pages.py

@@ -3,7 +3,7 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from tornado import web
+from tornado import web, gen
 
 from .. import orm
 from ..utils import admin_only, url_path_join
@@ -47,6 +47,63 @@ class HomeHandler(BaseHandler):
         self.finish(html)
 
 
+class SpawnHandler(BaseHandler):
+    """Handle spawning of single-user servers via form.
+    
+    GET renders the form, POST handles form submission.
+    
+    Only enabled when Spawner.options_form is defined.
+    """
+    def _render_form(self, message=''):
+        user = self.get_current_user()
+        return self.render_template('spawn.html',
+            user=user,
+            spawner_options_form=user.spawner.options_form,
+            error_message=message,
+        )
+
+    @web.authenticated
+    def get(self):
+        """GET renders form for spawning with user-specified options"""
+        user = self.get_current_user()
+        if user.running:
+            url = user.server.base_url
+            self.log.debug("User is running: %s", url)
+            self.redirect(url)
+            return
+        if user.spawner.options_form:
+            self.finish(self._render_form())
+        else:
+            # not running, no form. Trigger spawn.
+            url = url_path_join(self.base_url, 'user', user.name)
+            self.redirect(url)
+    
+    @web.authenticated
+    @gen.coroutine
+    def post(self):
+        """POST spawns with user-specified options"""
+        user = self.get_current_user()
+        if user.running:
+            url = user.server.base_url
+            self.log.warning("User is already running: %s", url)
+            self.redirect(url)
+            return
+        form_options = {}
+        for key, byte_list in self.request.body_arguments.items():
+            form_options[key] = [ bs.decode('utf8') for bs in byte_list ]
+        for key, byte_list in self.request.files.items():
+            form_options["%s_file"%key] = byte_list
+        options = user.spawner.options_from_form(form_options)
+        try:
+            yield self.spawn_single_user(user, options=options)
+        except Exception as e:
+            self.log.error("Failed to spawn single-user server with form", exc_info=True)
+            self.finish(self._render_form(str(e)))
+            return
+        self.set_login_cookie(user)
+        url = user.server.base_url
+        self.redirect(url)
+
 class AdminHandler(BaseHandler):
     """Render the admin page."""
 
@@ -90,7 +147,8 @@ class AdminHandler(BaseHandler):
         ordered = [ getattr(c, o)() for c, o in zip(cols, orders) ]
         
         users = self.db.query(orm.User).order_by(*ordered)
-        running = users.filter(orm.User.server != None)
+        users = [ self._user_from_orm(u) for u in users ]
+        running = [ u for u in users if u.running ]
         
         html = self.render_template('admin.html',
             user=self.get_current_user(),
@@ -106,4 +164,5 @@ default_handlers = [
     (r'/', RootHandler),
     (r'/home', HomeHandler),
     (r'/admin', AdminHandler),
+    (r'/spawn', SpawnHandler),
 ]

jupyterhub/orm.py

@@ -3,15 +3,14 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from datetime import datetime, timedelta
+from datetime import datetime
 import errno
 import json
 import socket
-from urllib.parse import quote
 
 from tornado import gen
 from tornado.log import app_log
-from tornado.httpclient import HTTPRequest, AsyncHTTPClient, HTTPError
+from tornado.httpclient import HTTPRequest, AsyncHTTPClient
 
 from sqlalchemy.types import TypeDecorator, VARCHAR
 from sqlalchemy import (
@@ -27,7 +26,7 @@ from sqlalchemy import create_engine
 
 from .utils import (
     random_port, url_path_join, wait_for_server, wait_for_http_server,
-    new_token, hash_token, compare_token,
+    new_token, hash_token, compare_token, localhost,
 )
 
 
@@ -79,7 +78,7 @@ class Server(Base):
         ip = self.ip
         if ip in {'', '0.0.0.0'}:
             # when listening on all interfaces, connect to localhost
-            ip = 'localhost'
+            ip = localhost()
         return "{proto}://{ip}:{port}".format(
             proto=self.proto,
             ip=ip,
@@ -110,14 +109,24 @@ class Server(Base):
         if http:
             yield wait_for_http_server(self.url, timeout=timeout)
         else:
-            yield wait_for_server(self.ip or 'localhost', self.port, timeout=timeout)
+            yield wait_for_server(self.ip or localhost(), self.port, timeout=timeout)
     
     def is_up(self):
         """Is the server accepting connections?"""
         try:
-            socket.create_connection((self.ip or 'localhost', self.port))
+            socket.create_connection((self.ip or localhost(), self.port))
         except socket.error as e:
-            if e.errno == errno.ECONNREFUSED:
+            if e.errno == errno.ENETUNREACH:
+                try:
+                    socket.create_connection((self.ip or '127.0.0.1', self.port))
+                except socket.error as e:
+                    if e.errno == errno.ECONNREFUSED:
+                        return False
+                    else:
+                        raise
+                else:
+                    return True
+            elif e.errno == errno.ECONNREFUSED:
                 return False
             else:
                 raise
@@ -271,7 +280,7 @@ class User(Base):
     used for restoring state of a Spawner.
     """
     __tablename__ = 'users'
-    id = Column(Integer, primary_key=True)
+    id = Column(Integer, primary_key=True, autoincrement=True)
     name = Column(Unicode)
     # should we allow multiple servers per user?
     _server_id = Column(Integer, ForeignKey('servers.id'))
@@ -282,12 +291,9 @@ class User(Base):
     api_tokens = relationship("APIToken", backref="user")
     cookie_id = Column(Unicode, default=new_token)
     state = Column(JSONDict)
-    spawner = None
-    spawn_pending = False
-    stop_pending = False
 
     other_user_cookies = set([])
-    
+
     def __repr__(self):
         if self.server:
             return "<{cls}({name}@{ip}:{port})>".format(
@@ -302,20 +308,6 @@ class User(Base):
                 name=self.name,
             )
     
-    @property
-    def escaped_name(self):
-        """My name, escaped for use in URLs, cookies, etc."""
-        return quote(self.name, safe='@')
-    
-    @property
-    def running(self):
-        """property for whether a user has a running server"""
-        if self.spawner is None:
-            return False
-        if self.server is None:
-            return False
-        return True
-    
     def new_api_token(self):
         """Create a new API token"""
         assert self.id is not None
@@ -326,7 +318,7 @@ class User(Base):
         db.add(orm_token)
         db.commit()
         return token
-    
+
     @classmethod
     def find(cls, db, name):
         """Find a user by name.
@@ -334,125 +326,6 @@ class User(Base):
         Returns None if not found.
         """
         return db.query(cls).filter(cls.name==name).first()
-    
-    @gen.coroutine
-    def spawn(self, spawner_class, base_url='/', hub=None, authenticator=None, config=None):
-        """Start the user's spawner"""
-        db = inspect(self).session
-        if hub is None:
-            hub = db.query(Hub).first()
-        
-        self.server = Server(
-            cookie_name='%s-%s' % (hub.server.cookie_name, quote(self.name, safe='')),
-            base_url=url_path_join(base_url, 'user', self.escaped_name),
-        )
-        db.add(self.server)
-        db.commit()
-        
-        api_token = self.new_api_token()
-        db.commit()
-        
-        spawner = self.spawner = spawner_class(
-            config=config,
-            user=self,
-            hub=hub,
-            db=db,
-            authenticator=authenticator,
-        )
-        # we are starting a new server, make sure it doesn't restore state
-        spawner.clear_state()
-        spawner.api_token = api_token
-        
-        # trigger pre-spawn hook on authenticator
-        if (authenticator):
-            yield gen.maybe_future(authenticator.pre_spawn_start(self, spawner))
-        self.spawn_pending = True
-        # wait for spawner.start to return
-        try:
-            f = spawner.start()
-            yield gen.with_timeout(timedelta(seconds=spawner.start_timeout), f)
-        except Exception as e:
-            if isinstance(e, gen.TimeoutError):
-                self.log.warn("{user}'s server failed to start in {s} seconds, giving up".format(
-                    user=self.name, s=spawner.start_timeout,
-                ))
-                e.reason = 'timeout'
-            else:
-                self.log.error("Unhandled error starting {user}'s server: {error}".format(
-                    user=self.name, error=e,
-                ))
-                e.reason = 'error'
-            try:
-                yield self.stop()
-            except Exception:
-                self.log.error("Failed to cleanup {user}'s server that failed to start".format(
-                    user=self.name,
-                ), exc_info=True)
-            # raise original exception
-            raise e
-        spawner.start_polling()
-
-        # store state
-        self.state = spawner.get_state()
-        self.last_activity = datetime.utcnow()
-        db.commit()
-        try:
-            yield self.server.wait_up(http=True, timeout=spawner.http_timeout)
-        except Exception as e:
-            if isinstance(e, TimeoutError):
-                self.log.warn(
-                    "{user}'s server never showed up at {url} "
-                    "after {http_timeout} seconds. Giving up".format(
-                        user=self.name,
-                        url=self.server.url,
-                        http_timeout=spawner.http_timeout,
-                    )
-                )
-                e.reason = 'timeout'
-            else:
-                e.reason = 'error'
-                self.log.error("Unhandled error waiting for {user}'s server to show up at {url}: {error}".format(
-                    user=self.name, url=self.server.url, error=e,
-                ))
-            try:
-                yield self.stop()
-            except Exception:
-                self.log.error("Failed to cleanup {user}'s server that failed to start".format(
-                    user=self.name,
-                ), exc_info=True)
-            # raise original TimeoutError
-            raise e
-        self.spawn_pending = False
-        return self
-
-    @gen.coroutine
-    def stop(self):
-        """Stop the user's spawner
-        
-        and cleanup after it.
-        """
-        self.spawn_pending = False
-        spawner = self.spawner
-        if spawner is None:
-            return
-        spawner.stop_polling()
-        self.stop_pending = True
-        try:
-            status = yield spawner.poll()
-            if status is None:
-                yield self.spawner.stop()
-            spawner.clear_state()
-            self.state = spawner.get_state()
-            self.server = None
-            inspect(self).session.commit()
-        finally:
-            self.stop_pending = False
-            # trigger post-spawner hook on authenticator
-            auth = spawner.authenticator
-            if auth:
-                yield gen.maybe_future(
-                    auth.post_spawn_stop(self, spawner)
-                )
 
 class APIToken(Base):
     """An API token"""

jupyterhub/singleuser.py

@@ -1,237 +0,0 @@
-#!/usr/bin/env python3
-"""Extend regular notebook server to be aware of multiuser things."""
-
-# Copyright (c) Jupyter Development Team.
-# Distributed under the terms of the Modified BSD License.
-
-import os
-try:
-    from urllib.parse import quote
-except ImportError:
-    # PY2 Compat
-    from urllib import quote
-
-import requests
-from jinja2 import ChoiceLoader, FunctionLoader
-
-from tornado import ioloop
-from tornado.web import HTTPError
-
-
-from IPython.utils.traitlets import (
-    Integer,
-    Unicode,
-    CUnicode,
-)
-
-try:
-    import notebook
-    # 4.x
-except ImportError:
-    from IPython.html.notebookapp import NotebookApp, aliases as notebook_aliases
-    from IPython.html.auth.login import LoginHandler
-    from IPython.html.auth.logout import LogoutHandler
-
-    from IPython.html.utils import url_path_join
-
-    from distutils.version import LooseVersion as V
-
-    import IPython
-    if V(IPython.__version__) < V('3.0'):
-        raise ImportError("JupyterHub Requires IPython >= 3.0, found %s" % IPython.__version__)
-else:
-    from notebook.notebookapp import NotebookApp, aliases as notebook_aliases
-    from notebook.auth.login import LoginHandler
-    from notebook.auth.logout import LogoutHandler
-
-    from notebook.utils import url_path_join
-
-
-# Define two methods to attach to AuthenticatedHandler,
-# which authenticate via the central auth server.
-
-class JupyterHubLoginHandler(LoginHandler):
-    @staticmethod
-    def login_available(settings):
-        return True
-    
-    @staticmethod
-    def verify_token(self, cookie_name, encrypted_cookie):
-        """method for token verification"""
-        cookie_cache = self.settings['cookie_cache']
-        if encrypted_cookie in cookie_cache:
-            # we've seen this token before, don't ask upstream again
-            return cookie_cache[encrypted_cookie]
-    
-        hub_api_url = self.settings['hub_api_url']
-        hub_api_key = self.settings['hub_api_key']
-        r = requests.get(url_path_join(
-            hub_api_url, "authorizations/cookie", cookie_name, quote(encrypted_cookie, safe=''),
-        ),
-            headers = {'Authorization' : 'token %s' % hub_api_key},
-        )
-        if r.status_code == 404:
-            data = None
-        elif r.status_code == 403:
-            self.log.error("I don't have permission to verify cookies, my auth token may have expired: [%i] %s", r.status_code, r.reason)
-            raise HTTPError(500, "Permission failure checking authorization, I may need to be restarted")
-        elif r.status_code >= 500:
-            self.log.error("Upstream failure verifying auth token: [%i] %s", r.status_code, r.reason)
-            raise HTTPError(502, "Failed to check authorization (upstream problem)")
-        elif r.status_code >= 400:
-            self.log.warn("Failed to check authorization: [%i] %s", r.status_code, r.reason)
-            raise HTTPError(500, "Failed to check authorization")
-        else:
-            data = r.json()
-        cookie_cache[encrypted_cookie] = data
-        return data
-    
-    @staticmethod
-    def get_user(self):
-        """alternative get_current_user to query the central server"""
-        # only allow this to be called once per handler
-        # avoids issues if an error is raised,
-        # since this may be called again when trying to render the error page
-        if hasattr(self, '_cached_user'):
-            return self._cached_user
-        
-        self._cached_user = None
-        my_user = self.settings['user']
-        encrypted_cookie = self.get_cookie(self.cookie_name)
-        if encrypted_cookie:
-            auth_data = JupyterHubLoginHandler.verify_token(self, self.cookie_name, encrypted_cookie)
-            if not auth_data:
-                # treat invalid token the same as no token
-                return None
-            user = auth_data['name']
-            if user == my_user:
-                self._cached_user = user
-                return user
-            else:
-                return None
-        else:
-            self.log.debug("No token cookie")
-            return None
-
-
-class JupyterHubLogoutHandler(LogoutHandler):
-    def get(self):
-        self.redirect(url_path_join(self.settings['hub_prefix'], 'logout'))
-
-
-# register new hub related command-line aliases
-aliases = dict(notebook_aliases)
-aliases.update({
-    'user' : 'SingleUserNotebookApp.user',
-    'cookie-name': 'SingleUserNotebookApp.cookie_name',
-    'hub-prefix': 'SingleUserNotebookApp.hub_prefix',
-    'hub-api-url': 'SingleUserNotebookApp.hub_api_url',
-    'base-url': 'SingleUserNotebookApp.base_url',
-})
-
-page_template = """
-{% extends "templates/page.html" %}
-
-{% block header_buttons %}
-{{super()}}
-
-<a href='{{hub_control_panel_url}}'
- class='btn btn-default btn-sm navbar-btn pull-right'
- style='margin-right: 4px; margin-left: 2px;'
->
-Control Panel</a>
-{% endblock %}
-"""
-
-class SingleUserNotebookApp(NotebookApp):
-    """A Subclass of the regular NotebookApp that is aware of the parent multiuser context."""
-    user = CUnicode(config=True)
-    def _user_changed(self, name, old, new):
-        self.log.name = new
-    cookie_name = Unicode(config=True)
-    hub_prefix = Unicode(config=True)
-    hub_api_url = Unicode(config=True)
-    aliases = aliases
-    open_browser = False
-    trust_xheaders = True
-    login_handler_class = JupyterHubLoginHandler
-    logout_handler_class = JupyterHubLogoutHandler
-
-    cookie_cache_lifetime = Integer(
-        config=True,
-        default_value=300,
-        allow_none=True,
-        help="""
-        Time, in seconds, that we cache a validated cookie before requiring
-        revalidation with the hub.
-        """,
-    )
-
-    def _log_datefmt_default(self):
-        """Exclude date from default date format"""
-        return "%Y-%m-%d %H:%M:%S"
-
-    def _log_format_default(self):
-        """override default log format to include time"""
-        return "%(color)s[%(levelname)1.1s %(asctime)s.%(msecs).03d %(name)s %(module)s:%(lineno)d]%(end_color)s %(message)s"
-
-    def _confirm_exit(self):
-        # disable the exit confirmation for background notebook processes
-        ioloop.IOLoop.instance().stop()
-
-    def _clear_cookie_cache(self):
-        self.log.debug("Clearing cookie cache")
-        self.tornado_settings['cookie_cache'].clear()
-    
-    def start(self):
-        # Start a PeriodicCallback to clear cached cookies.  This forces us to
-        # revalidate our user with the Hub at least every
-        # `cookie_cache_lifetime` seconds.
-        if self.cookie_cache_lifetime:
-            ioloop.PeriodicCallback(
-                self._clear_cookie_cache,
-                self.cookie_cache_lifetime * 1e3,
-            ).start()
-        super(SingleUserNotebookApp, self).start()
-    
-    def init_webapp(self):
-        # load the hub related settings into the tornado settings dict
-        env = os.environ
-        s = self.tornado_settings
-        s['cookie_cache'] = {}
-        s['user'] = self.user
-        s['hub_api_key'] = env.pop('JPY_API_TOKEN')
-        s['hub_prefix'] = self.hub_prefix
-        s['cookie_name'] = self.cookie_name
-        s['login_url'] = self.hub_prefix
-        s['hub_api_url'] = self.hub_api_url
-        s['csp_report_uri'] = url_path_join(self.hub_prefix, 'security/csp-report')
-        
-        super(SingleUserNotebookApp, self).init_webapp()
-        self.patch_templates()
-    
-    def patch_templates(self):
-        """Patch page templates to add Hub-related buttons"""
-        env = self.web_app.settings['jinja2_env']
-        
-        env.globals['hub_control_panel_url'] = \
-            url_path_join(self.hub_prefix, 'home')
-        
-        # patch jinja env loading to modify page template
-        def get_page(name):
-            if name == 'page.html':
-                return page_template
-        
-        orig_loader = env.loader
-        env.loader = ChoiceLoader([
-            FunctionLoader(get_page),
-            orig_loader,
-        ])
-
-
-def main():
-    return SingleUserNotebookApp.launch_instance()
-
-
-if __name__ == "__main__":
-    main()

jupyterhub/spawner.py

@@ -22,7 +22,7 @@ from traitlets import (
 )
 
 from .traitlets import Command
-from .utils import random_port
+from .utils import random_port, localhost
 
 class Spawner(LoggingConfigurable):
     """Base class for spawning single-user notebook servers.
@@ -41,7 +41,7 @@ class Spawner(LoggingConfigurable):
     hub = Any()
     authenticator = Any()
     api_token = Unicode()
-    ip = Unicode('localhost', config=True,
+    ip = Unicode(localhost(), config=True,
         help="The IP address (or hostname) the single-user server should listen on"
     )
     start_timeout = Integer(60, config=True,
@@ -73,6 +73,38 @@ class Spawner(LoggingConfigurable):
         help="Enable debug-logging of the single-user server"
     )
     
+    options_form = Unicode("", config=True, help="""
+        An HTML form for options a user can specify on launching their server.
+        The surrounding `<form>` element and the submit button are already provided.
+        
+        For example:
+        
+            Set your key:
+            <input name="key" val="default_key"></input>
+            <br>
+            Choose a letter:
+            <select name="letter" multiple="true">
+              <option value="A">The letter A</option>
+              <option value="B">The letter B</option>
+            </select>
+    """)
+
+    def options_from_form(self, form_data):
+        """Interpret HTTP form data
+        
+        Form data will always arrive as a dict of lists of strings.
+        Override this function to understand single-values, numbers, etc.
+        
+        This should coerce form data into the structure expected by self.user_options,
+        which must be a dict.
+        
+        Instances will receive this data on self.user_options, after passing through this function,
+        prior to `Spawner.start`.
+        """
+        return form_data
+    
+    user_options = Dict(help="This is where form-specified options ultimately end up.")
+    
     env_keep = List([
         'PATH',
         'PYTHONPATH',
@@ -104,6 +136,7 @@ class Spawner(LoggingConfigurable):
         help="""The notebook directory for the single-user server
         
         `~` will be expanded to the user's home directory
+        `%U` will be expanded to the user's username
         """
     )
     
@@ -131,7 +164,7 @@ class Spawner(LoggingConfigurable):
         """store the state necessary for load_state
         
         A black box of extra state for custom spawners.
-        Should call `super`.
+        Subclasses should call `super`.
         
         Returns
         -------
@@ -151,6 +184,14 @@ class Spawner(LoggingConfigurable):
         """
         self.api_token = ''
     
+    def get_env(self):
+        """Return the environment we should use
+        
+        Default returns a copy of self.env.
+        Use this to access the env in Spawner.start to allow extension in subclasses.
+        """
+        return self.env.copy()
+    
     def get_args(self):
         """Return the arguments to be passed after self.cmd"""
         args = [
@@ -164,6 +205,7 @@ class Spawner(LoggingConfigurable):
         if self.ip:
             args.append('--ip=%s' % self.ip)
         if self.notebook_dir:
+            self.notebook_dir = self.notebook_dir.replace("%U",self.user.name)
             args.append('--notebook-dir=%s' % self.notebook_dir)
         if self.debug:
             args.append('--debug')
@@ -278,9 +320,6 @@ def set_user_setuid(username):
     gids = [ g.gr_gid for g in grp.getgrall() if username in g.gr_mem ]
     
     def preexec():
-        # don't forward signals
-        os.setpgrp()
-        
         # set the user and group
         os.setgid(gid)
         try:
@@ -296,7 +335,12 @@ def set_user_setuid(username):
 
 
 class LocalProcessSpawner(Spawner):
-    """A Spawner that just uses Popen to start local processes."""
+    """A Spawner that just uses Popen to start local processes as users.
+    
+    Requires users to exist on the local system.
+    
+    This is the default spawner for JupyterHub.
+    """
     
     INTERRUPT_TIMEOUT = Integer(10, config=True,
         help="Seconds to wait for process to halt after SIGINT before proceeding to SIGTERM"
@@ -344,9 +388,11 @@ class LocalProcessSpawner(Spawner):
             env['SHELL'] = shell
         return env
     
-    def _env_default(self):
-        env = super()._env_default()
-        return self.user_env(env)
+    def get_env(self):
+        """Add user environment variables"""
+        env = super().get_env()
+        env = self.user_env(env)
+        return env
     
     @gen.coroutine
     def start(self):
@@ -355,7 +401,7 @@ class LocalProcessSpawner(Spawner):
             self.user.server.ip = self.ip
         self.user.server.port = random_port()
         cmd = []
-        env = self.env.copy()
+        env = self.get_env()
         
         cmd.extend(self.cmd)
         cmd.extend(self.get_args())
@@ -363,6 +409,7 @@ class LocalProcessSpawner(Spawner):
         self.log.info("Spawning %s", ' '.join(pipes.quote(s) for s in cmd))
         self.proc = Popen(cmd, env=env,
             preexec_fn=self.make_preexec_fn(self.user.name),
+            start_new_session=True, # don't forward signals
         )
         self.pid = self.proc.pid
     

jupyterhub/tests/mocking.py

@@ -17,6 +17,7 @@ from ..spawner import LocalProcessSpawner
 from ..app import JupyterHub
 from ..auth import PAMAuthenticator
 from .. import orm
+from ..utils import localhost
 
 from pamela import PAMError
 
@@ -53,8 +54,8 @@ class SlowSpawner(MockSpawner):
     
     @gen.coroutine
     def start(self):
-        yield gen.sleep(2)
         yield super().start()
+        yield gen.sleep(2)
     
     @gen.coroutine
     def stop(self):
@@ -73,6 +74,21 @@ class NeverSpawner(MockSpawner):
         return Future()
 
 
+class FormSpawner(MockSpawner):
+    options_form = "IMAFORM"
+    
+    def options_from_form(self, form_data):
+        options = {}
+        options['notspecified'] = 5
+        if 'bounds' in form_data:
+            options['bounds'] = [int(i) for i in form_data['bounds']]
+        if 'energy' in form_data:
+            options['energy'] = form_data['energy'][0]
+        if 'hello_file' in form_data:
+            options['hello'] = form_data['hello_file'][0]
+        return options
+
+
 class MockPAMAuthenticator(PAMAuthenticator):
     def _admin_users_default(self):
         return {'admin'}
@@ -84,7 +100,9 @@ class MockPAMAuthenticator(PAMAuthenticator):
     def authenticate(self, *args, **kwargs):
         with mock.patch.multiple('pamela',
                 authenticate=mock_authenticate,
-                open_session=mock_open_session):
+                open_session=mock_open_session,
+                close_session=mock_open_session,
+                ):
             return super(MockPAMAuthenticator, self).authenticate(*args, **kwargs)
 
 class MockHub(JupyterHub):
@@ -93,7 +111,7 @@ class MockHub(JupyterHub):
     db_file = None
     
     def _ip_default(self):
-        return 'localhost'
+        return localhost()
     
     def _authenticator_class_default(self):
         return MockPAMAuthenticator

jupyterhub/tests/test_api.py

@@ -10,8 +10,9 @@ import requests
 
 from tornado import gen
 
-from ..utils import url_path_join as ujoin
 from .. import orm
+from ..user import User
+from ..utils import url_path_join as ujoin
 from . import mocking
 
 
@@ -41,11 +42,15 @@ def check_db_locks(func):
 def find_user(db, name):
     return db.query(orm.User).filter(orm.User.name==name).first()
     
-def add_user(db, **kwargs):
-    user = orm.User(**kwargs)
-    db.add(user)
+def add_user(db, app=None, **kwargs):
+    orm_user = orm.User(**kwargs)
+    db.add(orm_user)
     db.commit()
-    return user
+    if app:
+        user = app.users[orm_user.id] = User(orm_user, app.tornado_settings)
+        return user
+    else:
+        return orm_user
 
 def auth_header(db, name):
     user = find_user(db, name)
@@ -204,6 +209,17 @@ def test_add_multi_user_bad(app):
     r = api_request(app, 'users', method='post', data='[]')
     assert r.status_code == 400
 
+
+def test_add_multi_user_invalid(app):
+    app.authenticator.username_pattern = r'w.*'
+    r = api_request(app, 'users', method='post',
+        data=json.dumps({'usernames': ['Willow', 'Andrew', 'Tara']})
+    )
+    app.authenticator.username_pattern = ''
+    assert r.status_code == 400
+    assert r.json()['message'] == 'Invalid usernames: andrew, tara'
+
+
 def test_add_multi_user(app):
     db = app.db
     names = ['a', 'b']
@@ -310,21 +326,27 @@ def get_app_user(app, name):
     No ORM methods should be called on the result.
     """
     q = Queue()
-    def get_user():
+    def get_user_id():
         user = find_user(app.db, name)
-        q.put(user)
-    app.io_loop.add_callback(get_user)
-    return q.get(timeout=2)
+        q.put(user.id)
+    app.io_loop.add_callback(get_user_id)
+    user_id = q.get(timeout=2)
+    return app.users[user_id]
 
 def test_spawn(app, io_loop):
     db = app.db
     name = 'wash'
-    user = add_user(db, name=name)
-    r = api_request(app, 'users', name, 'server', method='post')
+    user = add_user(db, app=app, name=name)
+    options = {
+        's': ['value'],
+        'i': 5,
+    }
+    r = api_request(app, 'users', name, 'server', method='post', data=json.dumps(options))
     assert r.status_code == 201
     assert 'pid' in user.state
     app_user = get_app_user(app, name)
     assert app_user.spawner is not None
+    assert app_user.spawner.user_options == options
     assert not app_user.spawn_pending
     status = io_loop.run_sync(app_user.spawner.poll)
     assert status is None
@@ -348,13 +370,14 @@ def test_spawn(app, io_loop):
     assert status == 0
 
 def test_slow_spawn(app, io_loop):
-    app.tornado_application.settings['spawner_class'] = mocking.SlowSpawner
+    # app.tornado_application.settings['spawner_class'] = mocking.SlowSpawner
+    app.tornado_settings['spawner_class'] = mocking.SlowSpawner
     app.tornado_application.settings['slow_spawn_timeout'] = 0
     app.tornado_application.settings['slow_stop_timeout'] = 0
 
     db = app.db
     name = 'zoe'
-    user = add_user(db, name=name)
+    user = add_user(db, app=app, name=name)
     r = api_request(app, 'users', name, 'server', method='post')
     r.raise_for_status()
     assert r.status_code == 202
@@ -398,12 +421,12 @@ def test_slow_spawn(app, io_loop):
     
 
 def test_never_spawn(app, io_loop):
-    app.tornado_application.settings['spawner_class'] = mocking.NeverSpawner
+    app.tornado_settings['spawner_class'] = mocking.NeverSpawner
     app.tornado_application.settings['slow_spawn_timeout'] = 0
 
     db = app.db
     name = 'badger'
-    user = add_user(db, name=name)
+    user = add_user(db, app=app, name=name)
     r = api_request(app, 'users', name, 'server', method='post')
     app_user = get_app_user(app, name)
     assert app_user.spawner is not None

jupyterhub/tests/test_auth.py

@@ -3,7 +3,6 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
-from subprocess import CalledProcessError
 from unittest import mock
 
 import pytest
@@ -13,13 +12,13 @@ from jupyterhub import auth, orm
 
 def test_pam_auth(io_loop):
     authenticator = MockPAMAuthenticator()
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'match',
         'password': 'match',
     }))
     assert authorized == 'match'
     
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'match',
         'password': 'nomatch',
     }))
@@ -27,19 +26,19 @@ def test_pam_auth(io_loop):
 
 def test_pam_auth_whitelist(io_loop):
     authenticator = MockPAMAuthenticator(whitelist={'wash', 'kaylee'})
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'kaylee',
         'password': 'kaylee',
     }))
     assert authorized == 'kaylee'
     
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'wash',
         'password': 'nomatch',
     }))
     assert authorized is None
     
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'mal',
         'password': 'mal',
     }))
@@ -59,14 +58,14 @@ def test_pam_auth_group_whitelist(io_loop):
     authenticator = MockPAMAuthenticator(group_whitelist={'group'})
     
     with mock.patch.object(auth, 'getgrnam', getgrnam):
-        authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+        authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
             'username': 'kaylee',
             'password': 'kaylee',
         }))
     assert authorized == 'kaylee'
 
     with mock.patch.object(auth, 'getgrnam', getgrnam):
-        authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+        authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
             'username': 'mal',
             'password': 'mal',
         }))
@@ -75,7 +74,7 @@ def test_pam_auth_group_whitelist(io_loop):
 
 def test_pam_auth_no_such_group(io_loop):
     authenticator = MockPAMAuthenticator(group_whitelist={'nosuchcrazygroup'})
-    authorized = io_loop.run_sync(lambda : authenticator.authenticate(None, {
+    authorized = io_loop.run_sync(lambda : authenticator.get_authenticated_user(None, {
         'username': 'kaylee',
         'password': 'kaylee',
     }))
@@ -93,33 +92,47 @@ def test_wont_add_system_user(io_loop):
 def test_cant_add_system_user(io_loop):
     user = orm.User(name='lioness4321')
     authenticator = auth.PAMAuthenticator(whitelist={'mal'})
+    authenticator.add_user_cmd = ['jupyterhub-fake-command']
     authenticator.create_system_users = True
     
-    def check_output(cmd, *a, **kw):
-        raise CalledProcessError(1, cmd)
+    class DummyFile:
+        def read(self):
+            return b'dummy error'
     
-    with mock.patch.object(auth, 'check_output', check_output):
-        with pytest.raises(RuntimeError):
+    class DummyPopen:
+        def __init__(self, *args, **kwargs):
+            self.args = args
+            self.kwargs = kwargs
+            self.returncode = 1
+            self.stdout = DummyFile()
+        
+        def wait(self):
+            return
+    
+    with mock.patch.object(auth, 'Popen', DummyPopen):
+        with pytest.raises(RuntimeError) as exc:
             io_loop.run_sync(lambda : authenticator.add_user(user))
+        assert str(exc.value) == 'Failed to create system user lioness4321: dummy error'
 
 
 def test_add_system_user(io_loop):
     user = orm.User(name='lioness4321')
     authenticator = auth.PAMAuthenticator(whitelist={'mal'})
     authenticator.create_system_users = True
-    
-    def check_output(*a, **kw):
-        return
+    authenticator.add_user_cmd = ['echo', '/home/USERNAME']
     
     record = {}
-    def check_call(cmd, *a, **kw):
-        record['cmd'] = cmd
+    class DummyPopen:
+        def __init__(self, cmd, *args, **kwargs):
+            record['cmd'] = cmd
+            self.returncode = 0
+        
+        def wait(self):
+            return
     
-    with mock.patch.object(auth, 'check_output', check_output), \
-             mock.patch.object(auth, 'check_call', check_call):
+    with mock.patch.object(auth, 'Popen', DummyPopen):
         io_loop.run_sync(lambda : authenticator.add_user(user))
-    
-    assert user.name in record['cmd']
+    assert record['cmd'] == ['echo', '/home/lioness4321', 'lioness4321']
 
 
 def test_delete_user(io_loop):
@@ -147,3 +160,37 @@ def test_handlers(app):
     assert handlers[0][0] == '/login'
 
 
+def test_normalize_names(io_loop):
+    a = MockPAMAuthenticator()
+    authorized = io_loop.run_sync(lambda : a.get_authenticated_user(None, {
+        'username': 'ZOE',
+        'password': 'ZOE',
+    }))
+    assert authorized == 'zoe'
+
+
+def test_username_map(io_loop):
+    a = MockPAMAuthenticator(username_map={'wash': 'alpha'})
+    authorized = io_loop.run_sync(lambda : a.get_authenticated_user(None, {
+        'username': 'WASH',
+        'password': 'WASH',
+    }))
+
+    assert authorized == 'alpha'
+
+    authorized = io_loop.run_sync(lambda : a.get_authenticated_user(None, {
+        'username': 'Inara',
+        'password': 'Inara',
+    }))
+    assert authorized == 'inara'
+
+
+def test_validate_names(io_loop):
+    a = auth.PAMAuthenticator()
+    assert a.validate_username('willow')
+    assert a.validate_username('giles')
+    a = auth.PAMAuthenticator(username_pattern='w.*')
+    assert not a.validate_username('xander')
+    assert a.validate_username('willow')
+
+

jupyterhub/tests/test_orm.py

@@ -7,6 +7,7 @@ import pytest
 from tornado import gen
 
 from .. import orm
+from ..user import User
 from .mocking import MockSpawner
 
 
@@ -94,8 +95,8 @@ def test_tokens(db):
 
 
 def test_spawn_fails(db, io_loop):
-    user = orm.User(name='aeofel')
-    db.add(user)
+    orm_user = orm.User(name='aeofel')
+    db.add(orm_user)
     db.commit()
     
     class BadSpawner(MockSpawner):
@@ -103,8 +104,13 @@ def test_spawn_fails(db, io_loop):
         def start(self):
             raise RuntimeError("Split the party")
     
+    user = User(orm_user, {
+        'spawner_class': BadSpawner,
+        'config': None,
+    })
+    
     with pytest.raises(Exception) as exc:
-        io_loop.run_sync(lambda : user.spawn(BadSpawner))
+        io_loop.run_sync(user.spawn)
     assert user.server is None
     assert not user.running
 

jupyterhub/tests/test_pages.py

@@ -1,10 +1,16 @@
 """Tests for HTML pages"""
 
+from urllib.parse import urlparse
+
 import requests
 
 from ..utils import url_path_join as ujoin
 from .. import orm
 
+import mock
+from .mocking import FormSpawner
+from .test_api import api_request
+
 
 def get_page(path, app, **kw):
     base_url = ujoin(app.proxy.public_server.host, app.hub.server.base_url)
@@ -56,3 +62,88 @@ def test_admin(app):
     r.raise_for_status()
     assert r.url.endswith('/admin')
 
+def test_spawn_redirect(app, io_loop):
+    name = 'wash'
+    cookies = app.login_user(name)
+    u = app.users[orm.User.find(app.db, name)]
+    
+    # ensure wash's server isn't running:
+    r = api_request(app, 'users', name, 'server', method='delete', cookies=cookies)
+    r.raise_for_status()
+    status = io_loop.run_sync(u.spawner.poll)
+    assert status is not None
+    
+    # test spawn page when no server is running
+    r = get_page('spawn', app, cookies=cookies)
+    r.raise_for_status()
+    print(urlparse(r.url))
+    path = urlparse(r.url).path
+    assert path == '/user/%s' % name
+    
+    # should have started server
+    status = io_loop.run_sync(u.spawner.poll)
+    assert status is None
+    
+    # test spawn page when server is already running (just redirect)
+    r = get_page('spawn', app, cookies=cookies)
+    r.raise_for_status()
+    print(urlparse(r.url))
+    path = urlparse(r.url).path
+    assert path == '/user/%s' % name
+
+def test_spawn_page(app):
+    with mock.patch.dict(app.users.settings, {'spawner_class': FormSpawner}):
+        cookies = app.login_user('jones')
+        r = get_page('spawn', app, cookies=cookies)
+        assert r.url.endswith('/spawn')
+        assert FormSpawner.options_form in r.text
+
+def test_spawn_form(app, io_loop):
+    with mock.patch.dict(app.users.settings, {'spawner_class': FormSpawner}):
+        base_url = ujoin(app.proxy.public_server.host, app.hub.server.base_url)
+        cookies = app.login_user('jones')
+        orm_u = orm.User.find(app.db, 'jones')
+        u = app.users[orm_u]
+        io_loop.run_sync(u.stop)
+    
+        r = requests.post(ujoin(base_url, 'spawn'), cookies=cookies, data={
+            'bounds': ['-1', '1'],
+            'energy': '511keV',
+        })
+        r.raise_for_status()
+        print(u.spawner)
+        print(u.spawner.user_options)
+        assert u.spawner.user_options == {
+            'energy': '511keV',
+            'bounds': [-1, 1],
+            'notspecified': 5,
+        }
+
+def test_spawn_form_with_file(app, io_loop):
+    with mock.patch.dict(app.users.settings, {'spawner_class': FormSpawner}):
+        base_url = ujoin(app.proxy.public_server.host, app.hub.server.base_url)
+        cookies = app.login_user('jones')
+        orm_u = orm.User.find(app.db, 'jones')
+        u = app.users[orm_u]
+        io_loop.run_sync(u.stop)
+
+        r = requests.post(ujoin(base_url, 'spawn'),
+                          cookies=cookies,
+                          data={
+                              'bounds': ['-1', '1'],
+                              'energy': '511keV',
+                          },
+                          files={'hello': ('hello.txt', b'hello world\n')}
+                      )
+        r.raise_for_status()
+        print(u.spawner)
+        print(u.spawner.user_options)
+        assert u.spawner.user_options == {
+            'energy': '511keV',
+            'bounds': [-1, 1],
+            'notspecified': 5,
+            'hello': {'filename': 'hello.txt',
+                      'body': b'hello world\n',
+                      'content_type': 'application/unknown'},
+        }
+

jupyterhub/tests/test_spawner.py

@@ -57,7 +57,7 @@ def test_spawner(db, io_loop):
     assert status == 1
 
 def test_single_user_spawner(db, io_loop):
-    spawner = new_spawner(db, cmd=[sys.executable, '-m', 'jupyterhub.singleuser'])
+    spawner = new_spawner(db, cmd=['jupyterhub-singleuser'])
     io_loop.run_sync(spawner.start)
     assert spawner.user.server.ip == 'localhost'
     # wait for http server to come up,

jupyterhub/user.py

@@ -0,0 +1,265 @@
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+from datetime import datetime, timedelta
+from urllib.parse import quote
+
+from tornado import gen
+from tornado.log import app_log
+
+from sqlalchemy import inspect
+
+from .utils import url_path_join
+
+from . import orm
+from traitlets import HasTraits, Any, Dict
+from .spawner import LocalProcessSpawner
+
+
+class UserDict(dict):
+    """Like defaultdict, but for users
+    
+    Getting by a user id OR an orm.User instance returns a User wrapper around the orm user.
+    """
+    def __init__(self, db_factory, settings):
+        self.db_factory = db_factory
+        self.settings = settings
+        super().__init__()
+    
+    @property
+    def db(self):
+        return self.db_factory()
+    
+    def __contains__(self, key):
+        if isinstance(key, (User, orm.User)):
+            key = key.id
+        return dict.__contains__(self, key)
+    
+    def __getitem__(self, key):
+        if isinstance(key, User):
+            key = key.id
+        if isinstance(key, orm.User):
+            # users[orm_user] returns User(orm_user)
+            orm_user = key
+            if orm_user.id not in self:
+                user = self[orm_user.id] = User(orm_user, self.settings)
+                return user
+            user = dict.__getitem__(self, orm_user.id)
+            user.db = self.db
+            return user
+        elif isinstance(key, int):
+            id = key
+            if id not in self:
+                orm_user = self.db.query(orm.User).filter(orm.User.id==id).first()
+                if orm_user is None:
+                    raise KeyError("No such user: %s" % id)
+                user = self[id] = User(orm_user, self.settings)
+            return dict.__getitem__(self, id)
+        else:
+            raise KeyError(repr(key))
+    
+    def __delitem__(self, key):
+        user = self[key]
+        user_id = user.id
+        db = self.db
+        db.delete(user.orm_user)
+        db.commit()
+        dict.__delitem__(self, user_id)
+
+
+class User(HasTraits):
+    
+    def _log_default(self):
+        return app_log
+    
+    settings = Dict()
+    
+    db = Any(allow_none=True)
+    def _db_default(self):
+        if self.orm_user:
+            return inspect(self.orm_user).session
+    
+    def _db_changed(self, name, old, new):
+        """Changing db session reacquires ORM User object"""
+        # db session changed, re-get orm User
+        if self.orm_user:
+            id = self.orm_user.id
+            self.orm_user = new.query(orm.User).filter(orm.User.id==id).first()
+        self.spawner.db = self.db
+    
+    orm_user = None
+    spawner = None
+    spawn_pending = False
+    stop_pending = False
+    
+    @property
+    def authenticator(self):
+        return self.settings.get('authenticator', None)
+    
+    @property
+    def spawner_class(self):
+        return self.settings.get('spawner_class', LocalProcessSpawner)
+    
+    def __init__(self, orm_user, settings, **kwargs):
+        self.orm_user = orm_user
+        self.settings = settings
+        super().__init__(**kwargs)
+        
+        hub = self.db.query(orm.Hub).first()
+        
+        self.cookie_name = '%s-%s' % (hub.server.cookie_name, quote(self.name, safe=''))
+        self.base_url = url_path_join(
+            self.settings.get('base_url', '/'), 'user', self.escaped_name)
+        
+        self.spawner = self.spawner_class(
+            user=self,
+            db=self.db,
+            hub=hub,
+            authenticator=self.authenticator,
+            config=self.settings.get('config'),
+        )
+    
+    # pass get/setattr to ORM user
+    
+    def __getattr__(self, attr):
+        if hasattr(self.orm_user, attr):
+            return getattr(self.orm_user, attr)
+        else:
+            raise AttributeError(attr)
+    
+    def __setattr__(self, attr, value):
+        if self.orm_user and hasattr(self.orm_user, attr):
+            setattr(self.orm_user, attr, value)
+        else:
+            super().__setattr__(attr, value)
+    
+    def __repr__(self):
+        return repr(self.orm_user)
+    
+    @property
+    def running(self):
+        """property for whether a user has a running server"""
+        if self.server is None:
+            return False
+        return True
+    
+    @property
+    def escaped_name(self):
+        """My name, escaped for use in URLs, cookies, etc."""
+        return quote(self.name, safe='@')
+    
+    @gen.coroutine
+    def spawn(self, options=None):
+        """Start the user's spawner"""
+        db = self.db
+        
+        self.server = orm.Server(
+            cookie_name=self.cookie_name,
+            base_url=self.base_url,
+        )
+        db.add(self.server)
+        db.commit()
+        
+        api_token = self.new_api_token()
+        db.commit()
+        
+        spawner = self.spawner
+        spawner.user_options = options or {}
+        # we are starting a new server, make sure it doesn't restore state
+        spawner.clear_state()
+        spawner.api_token = api_token
+
+        # trigger pre-spawn hook on authenticator
+        authenticator = self.authenticator
+        if (authenticator):
+            yield gen.maybe_future(authenticator.pre_spawn_start(self, spawner))
+
+        self.spawn_pending = True
+        # wait for spawner.start to return
+        try:
+            f = spawner.start()
+            # commit any changes in spawner.start (always commit db changes before yield)
+            db.commit()
+            yield gen.with_timeout(timedelta(seconds=spawner.start_timeout), f)
+        except Exception as e:
+            if isinstance(e, gen.TimeoutError):
+                self.log.warn("{user}'s server failed to start in {s} seconds, giving up".format(
+                    user=self.name, s=spawner.start_timeout,
+                ))
+                e.reason = 'timeout'
+            else:
+                self.log.error("Unhandled error starting {user}'s server: {error}".format(
+                    user=self.name, error=e,
+                ))
+                e.reason = 'error'
+            try:
+                yield self.stop()
+            except Exception:
+                self.log.error("Failed to cleanup {user}'s server that failed to start".format(
+                    user=self.name,
+                ), exc_info=True)
+            # raise original exception
+            raise e
+        spawner.start_polling()
+
+        # store state
+        self.state = spawner.get_state()
+        self.last_activity = datetime.utcnow()
+        db.commit()
+        try:
+            yield self.server.wait_up(http=True, timeout=spawner.http_timeout)
+        except Exception as e:
+            if isinstance(e, TimeoutError):
+                self.log.warn(
+                    "{user}'s server never showed up at {url} "
+                    "after {http_timeout} seconds. Giving up".format(
+                        user=self.name,
+                        url=self.server.url,
+                        http_timeout=spawner.http_timeout,
+                    )
+                )
+                e.reason = 'timeout'
+            else:
+                e.reason = 'error'
+                self.log.error("Unhandled error waiting for {user}'s server to show up at {url}: {error}".format(
+                    user=self.name, url=self.server.url, error=e,
+                ))
+            try:
+                yield self.stop()
+            except Exception:
+                self.log.error("Failed to cleanup {user}'s server that failed to start".format(
+                    user=self.name,
+                ), exc_info=True)
+            # raise original TimeoutError
+            raise e
+        self.spawn_pending = False
+        return self
+
+    @gen.coroutine
+    def stop(self):
+        """Stop the user's spawner
+        
+        and cleanup after it.
+        """
+        self.spawn_pending = False
+        spawner = self.spawner
+        self.spawner.stop_polling()
+        self.stop_pending = True
+        try:
+            status = yield spawner.poll()
+            if status is None:
+                yield self.spawner.stop()
+            spawner.clear_state()
+            self.state = spawner.get_state()
+            self.last_activity = datetime.utcnow()
+            self.server = None
+            self.db.commit()
+        finally:
+            self.stop_pending = False
+            # trigger post-spawner hook on authenticator
+            auth = spawner.authenticator
+            if auth:
+                yield gen.maybe_future(
+                    auth.post_spawn_stop(self, spawner)
+                )
+

jupyterhub/utils.py

@@ -6,10 +6,12 @@
 from binascii import b2a_hex
 import errno
 import hashlib
+from hmac import compare_digest
 import os
 import socket
+from threading import Thread
 import uuid
-from hmac import compare_digest
+import warnings
 
 from tornado import web, gen, ioloop
 from tornado.httpclient import AsyncHTTPClient, HTTPError
@@ -192,3 +194,36 @@ def url_path_join(*pieces):
         result = '/'
 
     return result
+
+def localhost():
+    """Return localhost or 127.0.0.1"""
+    if hasattr(localhost, '_localhost'):
+        return localhost._localhost
+    binder = connector = None
+    try:
+        binder = socket.socket()
+        binder.bind(('localhost', 0))
+        binder.listen(1)
+        port = binder.getsockname()[1]
+        def accept():
+            try:
+                conn, addr = binder.accept()
+            except ConnectionAbortedError:
+                pass
+            else:
+                conn.close()
+        t = Thread(target=accept)
+        t.start()
+        connector = socket.create_connection(('localhost', port), timeout=10)
+        t.join(timeout=10)
+    except (socket.error, socket.gaierror) as e:
+        warnings.warn("localhost doesn't appear to work, using 127.0.0.1\n%s" % e, RuntimeWarning)
+        localhost._localhost = '127.0.0.1'
+    else:
+        localhost._localhost = 'localhost'
+    finally:
+        if binder:
+            binder.close()
+        if connector:
+            connector.close()
+    return localhost._localhost

jupyterhub/version.py

@@ -5,9 +5,8 @@
 
 version_info = (
     0,
-    3,
-    0,
-    # 'dev',
+    4,
+    1,
 )
 
 __version__ = '.'.join(map(str, version_info))

readthedocs.yml

@@ -0,0 +1,5 @@
+name: jupyterhub
+type: sphinx
+requirements_file: docs/requirements.txt
+python:
+  version: 3

requirements.txt

@@ -2,5 +2,5 @@ traitlets>=4
 tornado>=4.1
 jinja2
 pamela
-sqlalchemy
+sqlalchemy>=1.0
 requests

scripts/jupyterhub-singleuser

@@ -1,4 +1,237 @@
 #!/usr/bin/env python3
+"""Extend regular notebook server to be aware of multiuser things."""
 
-from jupyterhub.singleuser import main
-main()
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+import os
+try:
+    from urllib.parse import quote
+except ImportError:
+    # PY2 Compat
+    from urllib import quote
+
+import requests
+from jinja2 import ChoiceLoader, FunctionLoader
+
+from tornado import ioloop
+from tornado.web import HTTPError
+
+
+from IPython.utils.traitlets import (
+    Integer,
+    Unicode,
+    CUnicode,
+)
+
+try:
+    import notebook
+    # 4.x
+except ImportError:
+    from IPython.html.notebookapp import NotebookApp, aliases as notebook_aliases
+    from IPython.html.auth.login import LoginHandler
+    from IPython.html.auth.logout import LogoutHandler
+
+    from IPython.html.utils import url_path_join
+
+    from distutils.version import LooseVersion as V
+
+    import IPython
+    if V(IPython.__version__) < V('3.0'):
+        raise ImportError("JupyterHub Requires IPython >= 3.0, found %s" % IPython.__version__)
+else:
+    from notebook.notebookapp import NotebookApp, aliases as notebook_aliases
+    from notebook.auth.login import LoginHandler
+    from notebook.auth.logout import LogoutHandler
+
+    from notebook.utils import url_path_join
+
+
+# Define two methods to attach to AuthenticatedHandler,
+# which authenticate via the central auth server.
+
+class JupyterHubLoginHandler(LoginHandler):
+    @staticmethod
+    def login_available(settings):
+        return True
+    
+    @staticmethod
+    def verify_token(self, cookie_name, encrypted_cookie):
+        """method for token verification"""
+        cookie_cache = self.settings['cookie_cache']
+        if encrypted_cookie in cookie_cache:
+            # we've seen this token before, don't ask upstream again
+            return cookie_cache[encrypted_cookie]
+    
+        hub_api_url = self.settings['hub_api_url']
+        hub_api_key = self.settings['hub_api_key']
+        r = requests.get(url_path_join(
+            hub_api_url, "authorizations/cookie", cookie_name, quote(encrypted_cookie, safe=''),
+        ),
+            headers = {'Authorization' : 'token %s' % hub_api_key},
+        )
+        if r.status_code == 404:
+            data = None
+        elif r.status_code == 403:
+            self.log.error("I don't have permission to verify cookies, my auth token may have expired: [%i] %s", r.status_code, r.reason)
+            raise HTTPError(500, "Permission failure checking authorization, I may need to be restarted")
+        elif r.status_code >= 500:
+            self.log.error("Upstream failure verifying auth token: [%i] %s", r.status_code, r.reason)
+            raise HTTPError(502, "Failed to check authorization (upstream problem)")
+        elif r.status_code >= 400:
+            self.log.warn("Failed to check authorization: [%i] %s", r.status_code, r.reason)
+            raise HTTPError(500, "Failed to check authorization")
+        else:
+            data = r.json()
+        cookie_cache[encrypted_cookie] = data
+        return data
+    
+    @staticmethod
+    def get_user(self):
+        """alternative get_current_user to query the central server"""
+        # only allow this to be called once per handler
+        # avoids issues if an error is raised,
+        # since this may be called again when trying to render the error page
+        if hasattr(self, '_cached_user'):
+            return self._cached_user
+        
+        self._cached_user = None
+        my_user = self.settings['user']
+        encrypted_cookie = self.get_cookie(self.cookie_name)
+        if encrypted_cookie:
+            auth_data = JupyterHubLoginHandler.verify_token(self, self.cookie_name, encrypted_cookie)
+            if not auth_data:
+                # treat invalid token the same as no token
+                return None
+            user = auth_data['name']
+            if user == my_user:
+                self._cached_user = user
+                return user
+            else:
+                return None
+        else:
+            self.log.debug("No token cookie")
+            return None
+
+
+class JupyterHubLogoutHandler(LogoutHandler):
+    def get(self):
+        self.redirect(url_path_join(self.settings['hub_prefix'], 'logout'))
+
+
+# register new hub related command-line aliases
+aliases = dict(notebook_aliases)
+aliases.update({
+    'user' : 'SingleUserNotebookApp.user',
+    'cookie-name': 'SingleUserNotebookApp.cookie_name',
+    'hub-prefix': 'SingleUserNotebookApp.hub_prefix',
+    'hub-api-url': 'SingleUserNotebookApp.hub_api_url',
+    'base-url': 'SingleUserNotebookApp.base_url',
+})
+
+page_template = """
+{% extends "templates/page.html" %}
+
+{% block header_buttons %}
+{{super()}}
+
+<a href='{{hub_control_panel_url}}'
+ class='btn btn-default btn-sm navbar-btn pull-right'
+ style='margin-right: 4px; margin-left: 2px;'
+>
+Control Panel</a>
+{% endblock %}
+"""
+
+class SingleUserNotebookApp(NotebookApp):
+    """A Subclass of the regular NotebookApp that is aware of the parent multiuser context."""
+    user = CUnicode(config=True)
+    def _user_changed(self, name, old, new):
+        self.log.name = new
+    cookie_name = Unicode(config=True)
+    hub_prefix = Unicode(config=True)
+    hub_api_url = Unicode(config=True)
+    aliases = aliases
+    open_browser = False
+    trust_xheaders = True
+    login_handler_class = JupyterHubLoginHandler
+    logout_handler_class = JupyterHubLogoutHandler
+
+    cookie_cache_lifetime = Integer(
+        config=True,
+        default_value=300,
+        allow_none=True,
+        help="""
+        Time, in seconds, that we cache a validated cookie before requiring
+        revalidation with the hub.
+        """,
+    )
+
+    def _log_datefmt_default(self):
+        """Exclude date from default date format"""
+        return "%Y-%m-%d %H:%M:%S"
+
+    def _log_format_default(self):
+        """override default log format to include time"""
+        return "%(color)s[%(levelname)1.1s %(asctime)s.%(msecs).03d %(name)s %(module)s:%(lineno)d]%(end_color)s %(message)s"
+
+    def _confirm_exit(self):
+        # disable the exit confirmation for background notebook processes
+        ioloop.IOLoop.instance().stop()
+
+    def _clear_cookie_cache(self):
+        self.log.debug("Clearing cookie cache")
+        self.tornado_settings['cookie_cache'].clear()
+    
+    def start(self):
+        # Start a PeriodicCallback to clear cached cookies.  This forces us to
+        # revalidate our user with the Hub at least every
+        # `cookie_cache_lifetime` seconds.
+        if self.cookie_cache_lifetime:
+            ioloop.PeriodicCallback(
+                self._clear_cookie_cache,
+                self.cookie_cache_lifetime * 1e3,
+            ).start()
+        super(SingleUserNotebookApp, self).start()
+    
+    def init_webapp(self):
+        # load the hub related settings into the tornado settings dict
+        env = os.environ
+        s = self.tornado_settings
+        s['cookie_cache'] = {}
+        s['user'] = self.user
+        s['hub_api_key'] = env.pop('JPY_API_TOKEN')
+        s['hub_prefix'] = self.hub_prefix
+        s['cookie_name'] = self.cookie_name
+        s['login_url'] = self.hub_prefix
+        s['hub_api_url'] = self.hub_api_url
+        s['csp_report_uri'] = url_path_join(self.hub_prefix, 'security/csp-report')
+        
+        super(SingleUserNotebookApp, self).init_webapp()
+        self.patch_templates()
+    
+    def patch_templates(self):
+        """Patch page templates to add Hub-related buttons"""
+        env = self.web_app.settings['jinja2_env']
+        
+        env.globals['hub_control_panel_url'] = \
+            url_path_join(self.hub_prefix, 'home')
+        
+        # patch jinja env loading to modify page template
+        def get_page(name):
+            if name == 'page.html':
+                return page_template
+        
+        orig_loader = env.loader
+        env.loader = ChoiceLoader([
+            FunctionLoader(get_page),
+            orig_loader,
+        ])
+
+
+def main():
+    return SingleUserNotebookApp.launch_instance()
+
+
+if __name__ == "__main__":
+    main()

setup.py

@@ -83,8 +83,8 @@ setup_args = dict(
                         # this will be overridden when bower is run anyway
     data_files          = get_data_files() or ['dummy'],
     version             = ns['__version__'],
-    description         = """JupyterHub: A multi-user server for Jupyter notebooks""",
-    long_description    = "",
+    description         = "JupyterHub: A multi-user server for Jupyter notebooks",
+    long_description    = "See https://jupyterhub.readthedocs.org for more info.",
     author              = "Jupyter Development Team",
     author_email        = "jupyter@googlegroups.com",
     url                 = "http://jupyter.org",

share/jupyter/hub/templates/admin.html

@@ -22,10 +22,10 @@
     <thead>
       <tr>
         {% block thead %}
-        {{ th("User (%i)" % users.count(), 'name') }}
+        {{ th("User (%i)" % users|length, 'name') }}
         {{ th("Admin", 'admin') }}
         {{ th("Last Seen", 'last_activity') }}
-        {{ th("Running (%i)" % running.count(), 'running', colspan=2) }}
+        {{ th("Running (%i)" % running|length, 'running', colspan=2) }}
         {% endblock thead %}
       </tr>
     </thead>
@@ -73,7 +73,7 @@
 
 {% call modal('Shutdown Hub', btn_label='Shutdown', btn_class='btn-danger shutdown-button') %}
   Are you sure you want to shutdown the Hub?
-  You can chose to leave the proxy and/or single-user servers running by unchecking the boxes below:
+  You can choose to leave the proxy and/or single-user servers running by unchecking the boxes below:
   <div class="checkbox">
     <label>
       <input type="checkbox" class="shutdown-proxy-checkbox">Shutdown proxy

share/jupyter/hub/templates/home.html

@@ -9,8 +9,15 @@
       <a id="stop" class="btn btn-lg btn-danger">Stop My Server</a>
       {% endif %}
       <a id="start" class="btn btn-lg btn-success"
+      {% if user.running %}
         href="{{base_url}}user/{{user.name}}/"
+      {% else %}
+        href="{{base_url}}spawn"
+      {% endif %}
       >
+      {% if not user.running %}
+      Start
+      {% endif %}
         My Server
       </a>
       {% if user.admin %}

share/jupyter/hub/templates/spawn.html

@@ -0,0 +1,32 @@
+{% extends "page.html" %}
+
+{% block main %}
+
+<div class="container">
+  <div class="row text-center">
+    <h1>Spawner options</h1>
+  </div>
+  <div class="row col-sm-offset-2 col-sm-8">
+      {% if error_message %}
+        <p class="spawn-error-msg text-danger">
+          Error: {{error_message}}
+        </p>
+      {% endif %}
+    <form enctype="multipart/form-data" id="spawn_form" action="{{base_url}}spawn" method="post" role="form">
+      {{spawner_options_form | safe}}
+      <br>
+      <input type="submit" value="Spawn" class="btn btn-jupyter">
+    </form>
+  </div>
+</div>
+
+{% endblock %}
+
+{% block script %}
+<script type="text/javascript">
+require(["jquery"], function ($) {
+  // add bootstrap form-control class to inputs
+  $("#spawn_form").find("input, select, textarea, button").addClass("form-control");
+});
+</script>
+{% endblock %}

tools/tasks.py

@@ -165,15 +165,13 @@ def make_env(*packages):
     return py
 
 
-def build_sdist(py, upload=False):
+def build_sdist(py):
     """Build sdists
     
     Returns the path to the tarball
     """
     with cd(repo_root):
         cmd = [py, 'setup.py', 'sdist', '--formats=zip,gztar']
-        if upload:
-            cmd.append('upload')
         run(cmd)
     
     return glob.glob(pjoin(repo_root, 'dist', '*.tar.gz'))[0]
@@ -184,7 +182,12 @@ def sdist(vs, upload=False):
     clone_repo()
     tag(vs, push=upload)
     py = make_env()
-    tarball = build_sdist(py, upload=upload)
+    tarball = build_sdist(py)
+    if upload:
+        with cd(repo_root):
+            install(py, 'twine')
+            run([py, '-m', 'twine', 'upload', 'dist/*'])
+    
     untag(vs, push=upload)
     return untar(tarball)
 
@@ -214,14 +217,10 @@ def untar(tarball):
     return glob.glob(pjoin(sdist_root, '*'))[0]
 
 
-def bdist(upload=False):
+def bdist():
     """build a wheel, optionally uploading it"""
     py = make_env('wheel')
-    cmd = [py, 'setup.py', 'bdist_wheel']
-    if upload:
-        cmd.append('upload')
-    
-    run(cmd)
+    run([py, 'setup.py', 'bdist_wheel'])
 
 
 @task
@@ -233,7 +232,10 @@ def release(vs, upload=False):
         shutil.rmtree(env_root)
     
     path = sdist(vs, upload=upload)
-    
+    print("Working in %r" % path)
     with cd(path):
-        bdist(upload=upload)
+        bdist()
+        if upload:
+            py = make_env('twine')
+            run([py, '-m', 'twine', 'upload', 'dist/*'])