Common Features — Docker Stacks documentation (original) (raw)

Contents

Common Features#

Except for jupyter/docker-stacks-foundation, a container launched from any Jupyter Docker Stacks image runs a Jupyter Server with the JupyterLab frontend. The container does so by executing a start-notebook.py script. This script configures the internal container environment and then runs jupyter lab, passing any command-line arguments received.

This page describes the options supported by the startup script and how to bypass it to run alternative commands.

Jupyter Server Options#

You can pass Jupyter Server options to the start-notebook.py script when launching the container.

  1. For example, to secure the Jupyter Server with a custom passwordhashed using jupyter_server.auth.passwd() instead of the default token, you can run the following (this hash was generated for the my-password password):
    docker run -it --rm -p 8888:8888 quay.io/jupyter/base-notebook \
    start-notebook.py --PasswordIdentityProvider.hashed_password='argon2:$argon2id$v=19$m=10240,t=10,p=8$JdAN3fe9J45NvK/EPuGCvA$O/tbxglbwRpOFuBNTYrymAEH6370Q2z+eS1eF4GM6Do'
  2. To set the base URL of the Jupyter Server, you can run the following:
    docker run -it --rm -p 8888:8888 quay.io/jupyter/base-notebook \
    start-notebook.py --ServerApp.base_url=/customized/url/prefix/

Docker Options#

You may instruct the start-notebook.py script to customize the container environment before launching the Server. You do so by passing arguments to the docker run command.

Permission-specific configurations#

Additional runtime configurations#

Startup Hooks#

You can further customize the container environment by adding shell scripts (*.sh) to be sourced or executables (chmod +x) to be run to the paths below:

See the run-hooks.sh script here and how it’s used in the start.shscript for execution details.

SSL Certificates#

You may mount an SSL key and certificate file into a container and configure the Jupyter Server to use them to accept HTTPS connections. For example, to mount a host folder containing a notebook.key and notebook.crt and use them, you might run the following:

docker run -it --rm -p 8888:8888
-v /some/host/folder:/etc/ssl/notebook
quay.io/jupyter/base-notebook
start-notebook.py
--ServerApp.keyfile=/etc/ssl/notebook/notebook.key
--ServerApp.certfile=/etc/ssl/notebook/notebook.crt

Alternatively, you may mount a single PEM file containing both the key and certificate. For example:

docker run -it --rm -p 8888:8888
-v /some/host/folder/notebook.pem:/etc/ssl/notebook.pem
quay.io/jupyter/base-notebook
start-notebook.py
--ServerApp.certfile=/etc/ssl/notebook.pem

In either case, Jupyter Server expects the key and certificate to be a base64 encoded text file. The certificate file or PEM may contain one or more certificates (e.g., server, intermediate, and root).

For additional information about using SSL, see the following:

Alternative Commands#

Switching back to the classic notebook or using a different startup command#

JupyterLab, built on top of Jupyter Server, is now the default for all the images of the stack. However, switching back to the classic notebook or using a different startup command is still possible. You can achieve this by setting the environment variable DOCKER_STACKS_JUPYTER_CMD at container startup. The table below shows some options. Since Jupyter Notebook v7 jupyter-server is used as a backend.

Note

Example:

Run Jupyter Server with the Jupyter Notebook frontend

docker run -it --rm
-p 8888:8888
-e DOCKER_STACKS_JUPYTER_CMD=notebook
quay.io/jupyter/base-notebook

Executing the command: start-notebook.py

Executing: jupyter notebook

...

Use Jupyter NBClassic frontend

docker run -it --rm
-p 8888:8888
-e DOCKER_STACKS_JUPYTER_CMD=nbclassic
quay.io/jupyter/base-notebook

Executing the command: start-notebook.py

Executing: jupyter nbclassic

...

start.sh#

Most of the configuration options in the start-notebook.py script are handled by an internal start.sh script that automatically runs before the command provided to the container (it’s set as the container entrypoint). This allows you to specify an arbitrary command that takes advantage of all these features. For example, to run the text-based ipython console in a container, do the following:

docker run -it --rm quay.io/jupyter/base-notebook ipython

This script is handy when you derive a new Dockerfile from this image and install additional Jupyter applications with subcommands like jupyter console, jupyter kernelgateway, etc.

Conda Environments#

The default Python 3.x Conda environment resides in /opt/conda. The /opt/conda/bin directory is part of the default jovyan user’s ${PATH}. That directory is also searched for binaries when run using sudo (sudo my_binary will search for my_binary in /opt/conda/bin/).

The jovyan user has full read/write access to the /opt/conda directory. You can use either mamba, pip, or conda (mamba is recommended) to install new packages without any additional permissions.

install a package into the default (python 3.x) environment and cleanup it after

the installation

mamba install --yes some-package &&
mamba clean --all -f -y &&
fix-permissions "${CONDA_DIR}" &&
fix-permissions "/home/${NB_USER}"

pip install --no-cache-dir some-package &&
fix-permissions "${CONDA_DIR}" &&
fix-permissions "/home/${NB_USER}"

conda install --yes some-package &&
conda clean --all -f -y &&
fix-permissions "${CONDA_DIR}" &&
fix-permissions "/home/${NB_USER}"

Using Alternative Channels#

Conda is configured by default to use only the conda-forge channel. However, you can use alternative channels, either one-shot by overwriting the default channel in the installation command or by configuring mamba to use different channels. The examples below show how to use the anaconda default channels instead of conda-forge to install packages.

using defaults channels to install a package

mamba install --channel defaults humanize

configure conda to add default channels at the top of the list

conda config --system --prepend channels defaults

install a package

mamba install --yes humanize &&
mamba clean --all -f -y &&
fix-permissions "${CONDA_DIR}" &&
fix-permissions "/home/${NB_USER}"