Add single-user scripts to minimal-notebook stack to make notebook

stacks easily usable with JupyterHub.

* pip install jupyterhub to gain access to the jupyterhub-singleuser
  startup script, which starts a single-user instance of the Notebook
  server
* Add shell script to wrap jupyterhub-singleuser script; use as
  alternate Docker command

fixes #181

(c) Copyright IBM Corp. 2016

README.md

@@ -32,8 +32,6 @@ Here's a diagram of the `FROM` relationships between all of the images defined i
 Starting with [git commit SHA 9bd33dcc8688](https://github.com/jupyter/docker-stacks/tree/9bd33dcc8688):
 
 * Every folder here on GitHub has an equivalent `jupyter/<stack name>` on Docker Hub.
-* Each `*-notebook` stack also has a corresponding `*-singleuser` stack,
-  for use with [JupyterHub](https://jupyterhub.readthedocs.org).
 * The `latest` tag in each Docker Hub repository tracks the `master` branch `HEAD` reference on GitHub.
 * Any 12-character image tag on Docker Hub refers to a git commit SHA here on GitHub. See the [Docker build history wiki page](https://github.com/jupyter/docker-stacks/wiki/Docker-build-history) for a table of build details.
 * Stack contents (e.g., new library versions) will be updated upon request via PRs against this project.
@@ -42,7 +40,8 @@ Starting with [git commit SHA 9bd33dcc8688](https://github.com/jupyter/docker-st
 
 ## Other Tips
 
-* `tini -- start-notebook.sh` is the default Docker entrypoint-plus-command in every notebook stack. If you plan to modify it any way, be sure to check the *Notebook Options* section of your stack's README to understand the consequences.
+* `tini -- start-notebook.sh` is the default Docker entrypoint-plus-command in every notebook stack. If you plan to modify it in any way, be sure to check the *Notebook Options* section of your stack's README to understand the consequences.
+* Every notebook stack is compatible with [JupyterHub](https://jupyterhub.readthedocs.org) 0.5.  When running with JupyterHub, you must override the Docker run command to point to the [start-singleuser.sh](minimal-notebook/start-singleuser.sh) script, which starts a single-user instance of the Notebook server.  See each stack's README for instructions on running with JupyterHub.
 * Check the [Docker recipes wiki page](https://github.com/jupyter/docker-stacks/wiki/Docker-Recipes) attached to this project for information about extending and deploying the Docker images defined here. Add to the wiki if you have relevant information.
 
 ## Maintainer Workflow

all-spark-notebook/README.md

@@ -14,6 +14,7 @@
 * Mesos client 0.22 binary that can communicate with a Mesos master
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](../minimal-notebook/start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 
@@ -253,9 +254,14 @@ The commands `ipython`, `python`, `pip`, `easy_install`, and `conda` (among othe
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/all-spark-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/all-spark-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```

datascience-notebook/README.md

@@ -12,6 +12,7 @@
 * Julia v0.3.x with Gadfly, RDatasets and HDF5 pre-installed
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](../minimal-notebook/start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -62,9 +63,14 @@ The commands `ipython`, `python`, `pip`, `easy_install`, and `conda` (among othe
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/datascience-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/datascience-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```

minimal-notebook/Dockerfile

@@ -82,6 +82,9 @@ RUN conda install --quiet --yes \
     terminado \
     && conda clean -tipsy
 
+# Install JupyterHub to get the jupyterhub-singleuser startup script
+RUN pip install 'jupyterhub==0.5'
+
 USER root
 
 # Configure container startup as root
@@ -91,7 +94,10 @@ ENTRYPOINT ["tini", "--"]
 CMD ["start-notebook.sh"]
 
 # Add local files as late as possible to avoid cache busting
+# Start notebook server
 COPY start-notebook.sh /usr/local/bin/
+# Start single-user notebook server for use with JupyterHub
+COPY start-singleuser.sh /usr/local/bin/
 COPY jupyter_notebook_config.py /home/$NB_USER/.jupyter/
 RUN chown -R $NB_USER:users /home/$NB_USER/.jupyter
 

minimal-notebook/README.md

@@ -9,6 +9,7 @@
 * No preinstalled scientific computing packages
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](./start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -47,9 +48,14 @@ The default Python 3.x [Conda environment](http://conda.pydata.org/docs/using/en
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/minimal-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/minimal-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```

minimal-notebook/start-singleuser.sh

+#!/bin/bash
+set -e
+
+notebook_arg=""
+if [ -n "${NOTEBOOK_DIR:+x}" ]
+then
+    notebook_arg="--notebook-dir=${NOTEBOOK_DIR}"
+fi
+
+exec jupyterhub-singleuser \
+  --port=8888 \
+  --ip=0.0.0.0 \
+  --user=$JPY_USER \
+  --cookie-name=$JPY_COOKIE_NAME \
+  --base-url=$JPY_BASE_URL \
+  --hub-prefix=$JPY_HUB_PREFIX \
+  --hub-api-url=$JPY_HUB_API_URL \
+  ${notebook_arg} \
+  $@

pyspark-notebook/README.md

@@ -11,6 +11,7 @@
 * Mesos client 0.22 binary that can communicate with a Mesos master
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](../minimal-notebook/start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -136,9 +137,14 @@ The commands `ipython`, `python`, `pip`, `easy_install`, and `conda` (among othe
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/pyspark-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/pyspark-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```

r-notebook/README.md

@@ -9,6 +9,7 @@
 * plyr, devtools, dplyr, ggplot2, tidyr, shiny, rmarkdown, forecast, stringr, rsqlite, reshape2, nycflights13, caret, rcurl, and randomforest pre-installed
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](../minimal-notebook/start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -43,9 +44,14 @@ You may customize the execution of the Docker container and the Notebook server
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/r-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/r-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```

scipy-notebook/README.md

@@ -9,6 +9,7 @@
 * pandas, matplotlib, scipy, seaborn, scikit-learn, scikit-image, sympy, cython, patsy, statsmodel, cloudpickle, dill, numba, bokeh pre-installed
 * Unprivileged user `jovyan` (uid=1000, configurable, see options) in group `users` (gid=100) with ownership over `/home/jovyan` and `/opt/conda`
 * [tini](https://github.com/krallin/tini) as the container entrypoint and [start-notebook.sh](../minimal-notebook/start-notebook.sh) as the default command
+* A [start-singleuser.sh](../minimal-notebook/start-singleuser.sh) script for use as an alternate command that runs a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -59,9 +60,14 @@ The commands `ipython`, `python`, `pip`, `easy_install`, and `conda` (among othe
 
 ## JupyterHub
 
-To use this stack with [JupyterHub](https://jupyterhub.readthedocs.org) and [DockerSpawner](https://github.com/jupyter/dockerspawner),
-set
+[JupyterHub](https://jupyterhub.readthedocs.org) requires a single-user instance of the Jupyter Notebook server per user.   To use this stack with JupyterHub and [DockerSpawner](https://github.com/jupyter/dockerspawner), you must specify the container image name and override the default container run command in your `jupyterhub_config.py`:
 
 ```python
-c.DockerSpawner.container_image = 'jupyter/scipy-singleuser'
+# Spawn user containers from this image
+c.DockerSpawner.container_image = 'jupyter/scipy-notebook'
+
+# Have the Spawner override the Docker run command
+c.DockerSpawner.extra_create_kwargs.update({
+	'command': '/usr/local/bin/start-singleuser.sh'
+})
 ```