Add generic start.sh to base-notebook

* Update doc in base-notebook to describe use case
* Rebase start-notebook.sh on it

base-notebook/Dockerfile

@@ -78,13 +78,15 @@ RUN pip --no-cache-dir install 'jupyterhub==0.5'
 
 USER root
 
-# Configure container startup as root
 EXPOSE 8888
 WORKDIR /home/$NB_USER/work
+
+# Configure container startup
 ENTRYPOINT ["tini", "--"]
-CMD ["start-notebook.sh"]
+CMD ["start-jupyter.sh", "notebook"]
 
 # Add local files as late as possible to avoid cache busting
+COPY start.sh /usr/local/bin/
 COPY start-notebook.sh /usr/local/bin/
 COPY start-singleuser.sh /usr/local/bin/
 COPY jupyter_notebook_config.py /home/$NB_USER/.jupyter/

base-notebook/README.md

@@ -11,7 +11,8 @@ Small base image for defining your own stack
 * 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](./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)
+* A [start-singleuser.sh](start-singleuser.sh) script useful for running a single-user instance of the Notebook server, as required by [JupyterHub](#JupyterHub)
+* A [start.sh](start.sh) script useful for running alternative commands in the container (e.g. `ipython`, `jupyter kernelgateway`, `jupyter lab`)
 * Options for HTTPS, password auth, and passwordless `sudo`
 
 ## Basic Use
@@ -24,23 +25,25 @@ docker run -d -p 8888:8888 jupyter/base-notebook
 
 ## Notebook Options
 
-You can pass [Jupyter command line options](http://jupyter.readthedocs.org/en/latest/config.html#command-line-arguments) through the [`start-notebook.sh` command](./start-notebook.sh#L17) when launching the container. For example, to set a password hashed using `IPython.lib.passwd()` to secure the notebook server:
+The Docker container executes a [`start-notebook.sh` script](https://github.com/jupyter/docker-stacks/blob/master/base-notebook/start-notebook.sh) script by default. The `start-notebook.sh` script handles the `NB_UID` and `GRANT_SUDO` features documented in the next section, and then executes the `jupyter notebook`.
+
+You can pass [Jupyter command line options](http://jupyter.readthedocs.org/en/latest/config.html#command-line-arguments) through the `start-notebook.sh` script when launching the container. For example, to secure the Notebook server with a password hashed using `IPython.lib.passwd()`, run the following:
 
 ```
 docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.password='sha1:74ba40f8a388:c913541b7ee99d15d5ed31d4226bf7838f83a50e'
 ```
 
-Or to set the base URL of the notebook server:
+For example, to set the base URL of the notebook server, run the following:
 
 ```
 docker run -d -p 8888:8888 jupyter/base-notebook start-notebook.sh --NotebookApp.base_url=/some/path
 ```
 
-You can sidestep the `start-notebook.sh` script entirely by specifying a command other than `start-notebook.sh`. If you do, the `NB_UID` and `GRANT_SUDO` features documented below will not work. See the Docker Options section for details.
+You can sidestep the `start-notebook.sh` script and run your own commands in the container. See the *Alternative Commands* section later in this document for more information.
 
 ## Docker Options
 
-You may customize the execution of the Docker container and the Notebook server it contains with the following optional arguments.
+You may customize the execution of the Docker container and the command it is running with the following optional arguments.
 
 * `-e PASSWORD="YOURPASS"` - Configures Jupyter Notebook to require the given plain-text password. Should be combined with `USE_HTTPS` on untrusted networks. **Note** that this option is not as secure as passing a pre-hashed password on the command line as shown above.
 * `-e USE_HTTPS=yes` - Configures Jupyter Notebook to accept encrypted HTTPS connections. If a `pem` file containing a SSL certificate and key is not provided (see below), the container will generate a self-signed certificate for you.
@@ -53,8 +56,9 @@ You may customize the execution of the Docker container and the Notebook server
 
 The default Python 3.x [Conda environment](http://conda.pydata.org/docs/using/envs.html) resides in `/opt/conda`. The commands `ipython`, `python`, `pip`, `easy_install`, and `conda` (among others) are available in this environment.
 
+## Alternative Commands
 
-## JupyterHub
+### start-singleuser.sh
 
 [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`:
 
@@ -67,3 +71,17 @@ c.DockerSpawner.extra_create_kwargs.update({
 	'command': '/usr/local/bin/start-singleuser.sh'
 })
 ```
+
+### start.sh
+
+The `start.sh` script supports the same features as the default `start-notebook.sh` script (e.g., `GRANT_SUDO`), but allows you to specify an arbitrary command to execute. For example, to run the text-based `ipython` console in a container, do the following:
+
+```
+docker run -it --rm jupyter/base-notebook start.sh ipython
+```
+
+This script is particularly useful when you derive a new Dockerfile from this image and install additional Jupyter applications with subcommands like `jupyter console`, `jupyter kernelgateway`, and `jupyter lab`.
+
+### Others
+
+You can bypass the provided scripts and specify your an arbitrary start command. If you do, keep in mind that certain features documented above will not function (e.g., `GRANT_SUDO`).

base-notebook/start-notebook.sh

 #!/bin/bash
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
 
-# Handle special flags if we're root
-if [ $UID == 0 ] ; then
-    # Change UID of NB_USER to NB_UID if it does not match
-    if [ "$NB_UID" != $(id -u $NB_USER) ] ; then
-        usermod -u $NB_UID $NB_USER
-        chown -R $NB_UID $CONDA_DIR .
-    fi
+set -e
 
-    # Enable sudo if requested
-    if [ ! -z "$GRANT_SUDO" ]; then
-        echo "$NB_USER ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/notebook
-    fi
-
-    # Start the notebook server
-    exec su $NB_USER -c "env PATH=$PATH jupyter notebook $*"
-else
-    # Otherwise just exec the notebook
-    exec jupyter notebook $*
-fi
+start.sh jupyter notebook $*

base-notebook/start-singleuser.sh

 #!/bin/bash
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
 set -e
 
 notebook_arg=""

base-notebook/start.sh

+#!/bin/bash
+# Copyright (c) Jupyter Development Team.
+# Distributed under the terms of the Modified BSD License.
+
+set -e
+
+# Handle special flags if we're root
+if [ $UID == 0 ] ; then
+    # Change UID of NB_USER to NB_UID if it does not match
+    if [ "$NB_UID" != $(id -u $NB_USER) ] ; then
+        usermod -u $NB_UID $NB_USER
+        chown -R $NB_UID $CONDA_DIR .
+    fi
+
+    # Enable sudo if requested
+    if [ ! -z "$GRANT_SUDO" ]; then
+        echo "$NB_USER ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/notebook
+    fi
+
+    # Exec the command as NB_USER
+    exec su $NB_USER -c "env PATH=$PATH $*"
+else
+    # Exec the command
+    exec $*
+fi