diff --git a/Makefile b/Makefile index 94b413a2cc..680eac74fe 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,7 @@ OWNER:=jupyter # need to list these manually because there's a dependency tree ALL_STACKS:=minimal-kernel \ + base-notebook \ minimal-notebook \ r-notebook \ scipy-notebook \ diff --git a/README.md b/README.md index ed2d2fc60d..31423055bb 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ If this is your first time using Docker or any of the Jupyter projects, do the f Here's a diagram of the `FROM` relationships between all of the images defined in this project: -[![Image inheritance diagram](internal/inherit-diagram.png)](http://interactive.blockdiag.com/?compression=deflate&src=eJyFzDELwjAQhuG9vyJ0trtYKnZzdxSRS3OVM9dcSOJQxf9u41BoEVzf77nTLJ01BDf1KpSSQOgSJBKnGuUlpACU6mkx2MOD07UXlyI9cZq3ubfqzKCRm9KgJnC7O8ZIeDgd2_JSF19R7dVAjgbgyklCLWI3c7EYHHJ-tTb5Lnbkx7lktSzZGEgwVXQdLuSvf-Gv8GP0EOzCrVt2wFyt5fsDQc9zBA) +[![Image inheritance diagram](internal/inherit-diagram.png)](http://interactive.blockdiag.com/?compression=deflate&src=eJyFzDEPwiAQhuG9v4J0lt3Y1NjN3dEYc5SrOaEcARyq8b9bTDrQpev7PXfKcm80wUN8KiE4ELoEidiJVngOKQClZl40DvCy6T6wS5HeOM_73DtxtaDQtrVGReAOT4yR8HQ5d_Wtqf5CHoWCiNJxQsVsdmIkRyNYaTA4tPlPAfLFQpaW0bplF3vyU6HKko2GBHNF1-Pmv7Ap_BQ9BFO4dcsOrJVr-f0B5CZ-hg) ## Stacks, Tags, Versioning, and Progress diff --git a/base-notebook/.dockerignore b/base-notebook/.dockerignore new file mode 100644 index 0000000000..9dea340f35 --- /dev/null +++ b/base-notebook/.dockerignore @@ -0,0 +1,2 @@ +# Documentation +README.md diff --git a/base-notebook/Dockerfile b/base-notebook/Dockerfile new file mode 100644 index 0000000000..1163ae7bed --- /dev/null +++ b/base-notebook/Dockerfile @@ -0,0 +1,89 @@ +# Copyright (c) Jupyter Development Team. +# Distributed under the terms of the Modified BSD License. + +# Debian Jessie image released 2016 May 03. +FROM debian@sha256:32a225e412babcd54c0ea777846183c61003d125278882873fb2bc97f9057c51 + +MAINTAINER Jupyter Project + +USER root + +# Install all OS dependencies for notebook server that starts but lacks all +# features (e.g., download as all possible file formats) +ENV DEBIAN_FRONTEND noninteractive +RUN apt-get update && apt-get install -yq --no-install-recommends \ + wget \ + bzip2 \ + ca-certificates \ + sudo \ + locales \ + && apt-get clean && \ + rm -rf /var/lib/apt/lists/* + +RUN echo "en_US.UTF-8 UTF-8" > /etc/locale.gen && \ + locale-gen + +# Install Tini +RUN wget --quiet https://github.com/krallin/tini/releases/download/v0.9.0/tini && \ + echo "faafbfb5b079303691a939a747d7f60591f2143164093727e870b289a44d9872 *tini" | sha256sum -c - && \ + mv tini /usr/local/bin/tini && \ + chmod +x /usr/local/bin/tini + +# Configure environment +ENV CONDA_DIR /opt/conda +ENV PATH $CONDA_DIR/bin:$PATH +ENV SHELL /bin/bash +ENV NB_USER jovyan +ENV NB_UID 1000 +ENV LC_ALL en_US.UTF-8 +ENV LANG en_US.UTF-8 +ENV LANGUAGE en_US.UTF-8 + +# Create jovyan user with UID=1000 and in the 'users' group +RUN useradd -m -s /bin/bash -N -u $NB_UID $NB_USER && \ + mkdir -p /opt/conda && \ + chown jovyan /opt/conda + +USER jovyan + +# Setup jovyan home directory +RUN mkdir /home/$NB_USER/work && \ + mkdir /home/$NB_USER/.jupyter && \ + mkdir /home/$NB_USER/.local && \ + echo "cacert=/etc/ssl/certs/ca-certificates.crt" > /home/$NB_USER/.curlrc + +# Install conda as jovyan +RUN cd /tmp && \ + mkdir -p $CONDA_DIR && \ + wget --quiet https://repo.continuum.io/miniconda/Miniconda3-3.19.0-Linux-x86_64.sh && \ + echo "9ea57c0fdf481acf89d816184f969b04bc44dea27b258c4e86b1e3a25ff26aa0 *Miniconda3-3.19.0-Linux-x86_64.sh" | sha256sum -c - && \ + /bin/bash Miniconda3-3.19.0-Linux-x86_64.sh -f -b -p $CONDA_DIR && \ + rm Miniconda3-3.19.0-Linux-x86_64.sh && \ + $CONDA_DIR/bin/conda install --quiet --yes conda==3.19.1 && \ + $CONDA_DIR/bin/conda config --system --add channels conda-forge && \ + conda clean -tipsy + +# Install Jupyter notebook as jovyan +RUN conda install --quiet --yes \ + 'notebook=4.2*' \ + && 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 +EXPOSE 8888 +WORKDIR /home/$NB_USER/work +ENTRYPOINT ["tini", "--"] +CMD ["start-notebook.sh"] + +# Add local files as late as possible to avoid cache busting +COPY start-notebook.sh /usr/local/bin/ +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 + +# Switch back to jovyan to avoid accidental container runs as root +USER jovyan diff --git a/base-notebook/README.md b/base-notebook/README.md new file mode 100644 index 0000000000..19054f68a3 --- /dev/null +++ b/base-notebook/README.md @@ -0,0 +1,63 @@ +![docker pulls](https://img.shields.io/docker/pulls/jupyter/base-notebook.svg) ![docker stars](https://img.shields.io/docker/stars/jupyter/base-notebook.svg) + +# Base Jupyter Notebook Stack + +Small base image for defining your own stack + +## What it Gives You + +* Minimally-functional Jupyter Notebook 4.2.x (e.g., no pandoc for document conversion) +* Miniconda Python 3.x +* 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 + +The following command starts a container with the Notebook server listening for HTTP connections on port 8888 without authentication configured. + +``` +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](https://github.com/jupyter/docker-stacks/blob/master/minimal-notebook/start-notebook.sh#L15) when launching the container. For example, to set the base URL of the notebook server you might do the following: + +``` +docker run -d -p 8888:8888 jupyter/minimal-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. + +## Docker Options + +You may customize the execution of the Docker container and the Notebook server it contains with the following optional arguments. + +* `-e PASSWORD="YOURPASS"` - Configures Jupyter Notebook to require the given password. Should be conbined with `USE_HTTPS` on untrusted networks. +* `-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. +* `-e NB_UID=1000` - Specify the uid of the `jovyan` user. Useful to mount host volumes with specific file ownership. For this option to take effect, you must run the container with `--user root`. (The `start-notebook.sh` script will `su jovyan` after adjusting the user id.) +* `-e GRANT_SUDO=yes` - Gives the `jovyan` user passwordless `sudo` capability. Useful for installing OS packages. For this option to take effect, you must run the container with `--user root`. (The `start-notebook.sh` script will `su jovyan` after adding `jovyan` to sudoers.) **You should only enable `sudo` if you trust the user or if the container is running on an isolated host.** +* `-v /some/host/folder/for/work:/home/jovyan/work` - Host mounts the default working directory on the host to preserve work even when the container is destroyed and recreated (e.g., during an upgrade). +* `-v /some/host/folder/for/server.pem:/home/jovyan/.local/share/jupyter/notebook.pem` - Mounts a SSL certificate plus key for `USE_HTTPS`. Useful if you have a real certificate for the domain under which you are running the Notebook server. + +## Conda Environment + +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. + + +## JupyterHub + +[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 +# 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' +}) +``` diff --git a/minimal-notebook/jupyter_notebook_config.py b/base-notebook/jupyter_notebook_config.py similarity index 100% rename from minimal-notebook/jupyter_notebook_config.py rename to base-notebook/jupyter_notebook_config.py diff --git a/minimal-notebook/start-notebook.sh b/base-notebook/start-notebook.sh old mode 100755 new mode 100644 similarity index 100% rename from minimal-notebook/start-notebook.sh rename to base-notebook/start-notebook.sh diff --git a/minimal-notebook/start-singleuser.sh b/base-notebook/start-singleuser.sh similarity index 100% rename from minimal-notebook/start-singleuser.sh rename to base-notebook/start-singleuser.sh diff --git a/internal/inherit-diagram.png b/internal/inherit-diagram.png index dd29befc1e..cb41999101 100644 Binary files a/internal/inherit-diagram.png and b/internal/inherit-diagram.png differ diff --git a/minimal-notebook/Dockerfile b/minimal-notebook/Dockerfile index 0f9d090314..aeac05fdbf 100644 --- a/minimal-notebook/Dockerfile +++ b/minimal-notebook/Dockerfile @@ -1,25 +1,20 @@ # Copyright (c) Jupyter Development Team. # Distributed under the terms of the Modified BSD License. -# Debian Jessie image released 2016 May 03. -FROM debian@sha256:32a225e412babcd54c0ea777846183c61003d125278882873fb2bc97f9057c51 +FROM jupyter/base-notebook MAINTAINER Jupyter Project USER root # Install all OS dependencies for fully functional notebook server -ENV DEBIAN_FRONTEND noninteractive RUN apt-get update && apt-get install -yq --no-install-recommends \ git \ vim \ jed \ emacs \ - wget \ build-essential \ python-dev \ - ca-certificates \ - bzip2 \ unzip \ libsm6 \ pandoc \ @@ -28,79 +23,9 @@ RUN apt-get update && apt-get install -yq --no-install-recommends \ texlive-fonts-extra \ texlive-fonts-recommended \ texlive-generic-recommended \ - sudo \ - locales \ libxrender1 \ && apt-get clean && \ rm -rf /var/lib/apt/lists/* -RUN echo "en_US.UTF-8 UTF-8" > /etc/locale.gen && \ - locale-gen - -# Install Tini -RUN wget --quiet https://github.com/krallin/tini/releases/download/v0.9.0/tini && \ - echo "faafbfb5b079303691a939a747d7f60591f2143164093727e870b289a44d9872 *tini" | sha256sum -c - && \ - mv tini /usr/local/bin/tini && \ - chmod +x /usr/local/bin/tini - -# Configure environment -ENV CONDA_DIR /opt/conda -ENV PATH $CONDA_DIR/bin:$PATH -ENV SHELL /bin/bash -ENV NB_USER jovyan -ENV NB_UID 1000 -ENV LC_ALL en_US.UTF-8 -ENV LANG en_US.UTF-8 -ENV LANGUAGE en_US.UTF-8 - -# Create jovyan user with UID=1000 and in the 'users' group -RUN useradd -m -s /bin/bash -N -u $NB_UID $NB_USER && \ - mkdir -p /opt/conda && \ - chown jovyan /opt/conda - -USER jovyan - -# Setup jovyan home directory -RUN mkdir /home/$NB_USER/work && \ - mkdir /home/$NB_USER/.jupyter && \ - mkdir /home/$NB_USER/.local && \ - echo "cacert=/etc/ssl/certs/ca-certificates.crt" > /home/$NB_USER/.curlrc - -# Install conda as jovyan -RUN cd /tmp && \ - mkdir -p $CONDA_DIR && \ - wget --quiet https://repo.continuum.io/miniconda/Miniconda3-3.19.0-Linux-x86_64.sh && \ - echo "9ea57c0fdf481acf89d816184f969b04bc44dea27b258c4e86b1e3a25ff26aa0 *Miniconda3-3.19.0-Linux-x86_64.sh" | sha256sum -c - && \ - /bin/bash Miniconda3-3.19.0-Linux-x86_64.sh -f -b -p $CONDA_DIR && \ - rm Miniconda3-3.19.0-Linux-x86_64.sh && \ - $CONDA_DIR/bin/conda install --quiet --yes conda==3.19.1 && \ - $CONDA_DIR/bin/conda config --system --add channels conda-forge && \ - conda clean -tipsy - -# Install Jupyter notebook as jovyan -RUN conda install --quiet --yes \ - 'notebook=4.2*' \ - 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 -EXPOSE 8888 -WORKDIR /home/$NB_USER/work -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 - # Switch back to jovyan to avoid accidental container runs as root USER jovyan diff --git a/minimal-notebook/README.md b/minimal-notebook/README.md index 5a60f9dab0..e60fe8b1df 100644 --- a/minimal-notebook/README.md +++ b/minimal-notebook/README.md @@ -2,10 +2,12 @@ # Minimal Jupyter Notebook Stack +Small image for working in the notebook and installing your own libraries + ## What it Gives You -* Jupyter Notebook 4.2.x -* Conda Python 3.x +* Fully-functional Jupyter Notebook 4.2.x +* Miniconda Python 3.x * 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