Notebook Servers

Note: this is a fork of the original Kubeflow notebook servers, with the intention of providing a maintained set of notebook images for 1Block.AI.

These images are provided as examples, and are supported on a best-effort basis.
Contributions are greatly appreciated.

Images

This chart shows how the images are related to each other (the nodes are clickable links to the Dockerfiles):

graph TD
  Base[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/base'>Base</a>] --> Jupyter[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter'>Jupyter</a>]
  Base --> Code-Server[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/codeserver'>code-server</a>]
  Base --> RStudio[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/rstudio'>RStudio</a>]
  
  Jupyter --> PyTorch[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-pytorch'>PyTorch</a>]
  Jupyter --> SciPy[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-scipy'>SciPy</a>]
  Jupyter --> TensorFlow[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-tensorflow'>TensorFlow</a>]
  
  Code-Server --> Code-Server-Conda-Python[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/codeserver-python'>Conda Python</a>]
  RStudio --> Tidyverse[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/rstudio-tidyverse'>Tidyverse</a>]

  PyTorch --> PyTorchFull[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-pytorch-full'>PyTorch Full</a>]
  TensorFlow --> TensorFlowFull[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-tensorflow-full'>TensorFlow Full</a>]

  Jupyter --> PyTorchCuda[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-pytorch-cuda'>PyTorch CUDA</a>]
  Jupyter --> TensorFlowCuda[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-tensorflow-cuda'>TensorFlow CUDA</a>]

  PyTorchCuda --> PyTorchCudaFull[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-pytorch-cuda-full'>PyTorch CUDA Full</a>]
  TensorFlowCuda --> TensorFlowCudaFull[<a href='https://github.com/oneblock-ai/notebook-images/tree/main/jupyter-tensorflow-cuda-full'>TensorFlow CUDA Full</a>]

Loading

Base Images

These images provide a common starting point for Kubeflow Notebook containers.

Dockerfile	Container Registry	Notes
./base	oneblockai/notebook-base	Common Base Image
./codeserver	oneblockai/codeserver	code-server (Visual Studio Code)
./jupyter	oneblockai/jupyter	JupyterLab
./rstudio	oneblockai/rstudio	RStudio

Kubeflow Images

These images extend the base images with common packages used in the real world.

Dockerfile	Container Registry	Notes
./codeserver-python	oneblockai/codeserver-python	code-server + Conda Python
./rstudio-tidyverse	oneblockai/rstudio-tidyverse	RStudio + Tidyverse
./jupyter-pytorch	oneblockai/jupyter-pytorch	JupyterLab + PyTorch
./jupyter-pytorch-full	oneblockai/jupyter-pytorch-full	JupyterLab + PyTorch + Common Packages
./jupyter-pytorch-cuda	oneblockai/jupyter-pytorch-cuda	JupyterLab + PyTorch + CUDA
./jupyter-pytorch-cuda-full	oneblockai/jupyter-pytorch-cuda-full	JupyterLab + PyTorch + CUDA + Common Packages
./jupyter-scipy	oneblockai/jupyter-scipy	JupyterLab + Common Packages
./jupyter-tensorflow	oneblockai/jupyter-tensorflow	JupyterLab + TensorFlow
./jupyter-tensorflow-full	oneblockai/jupyter-tensorflow-full	JupyterLab + TensorFlow + Common Packages
./jupyter-tensorflow-cuda	oneblockai/jupyter-tensorflow-cuda	JupyterLab + TensorFlow + CUDA
./jupyter-tensorflow-cuda-full	oneblockai/jupyter-tensorflow-cuda-full	JupyterLab + TensorFlow + CUDA + Common Packages

Package Installation

Packages installed by users after spawning a Kubeflow Notebook will only last the lifetime of the pod (unless installed into a PVC-backed directory).

To ensure packages are preserved throughout Pod restarts users will need to either:

1. Build custom images that include them, or
2. Ensure they are installed in a PVC-backed directory

Custom Images

You can build your own custom images to use with Kubeflow Notebooks.

The easiest way to ensure your custom image meets the requirements is to extend one of our base images.

Image Requirements

For a container image to work with Kubeflow Notebooks, it must:

• expose an HTTP interface on port 8888:
  • kubeflow sets an environment variable NB_PREFIX at runtime with the URL path we expect the container be listening under
  • kubeflow uses IFrames, so ensure your application sets Access-Control-Allow-Origin: * in HTTP response headers
• run as a user called jovyan:
  • the home directory of jovyan should be /home/jovyan
  • the UID of jovyan should be 1000
• start successfully with an empty PVC mounted at /home/jovyan:
  • kubeflow mounts a PVC at /home/jovyan to keep state across Pod restarts

Install Python Packages

You may extend one of the images and install any pip or conda packages your Kubeflow Notebook users are likely to need. As a guide, look at ./jupyter-pytorch-full/Dockerfile for a pip install ... example, and the ./rstudio-tidyverse/Dockerfile for conda install ....

A common cause of errors is users running pip install --user ..., causing the home-directory (which is backed by a PVC) to contain a different or incompatible version of a package contained in /opt/conda/...

Install Linux Packages

You may extend one of the images and install any apt-get packages your Kubeflow Notebook users are likely to need. Ensure you swap to root in the Dockerfile before running apt-get, and swap back to $NB_USER after.

Configure S6 Overlay

Some use-cases might require custom scripts to run during the startup of the Notebook Server container, or advanced users might want to add additional services that run inside the container (for example, an Apache or NGINX web server). To make this easy, we use the s6-overlay.

The s6-overlay differs from other init systems like tini. While tini was created to handle a single process running in a container as PID 1, the s6-overlay is built to manage multiple processes and allows the creator of the image to determine which process failures should silently restart, and which should cause the container to exit.

Create Scripts

Scripts that need to run during the startup of the container can be placed in /etc/cont-init.d/, and are executed in ascending alphanumeric order.

An example of a startup script can be found in ./rstudio/s6/cont-init.d/02-rstudio-env-fix. This script uses the with-contenv helper so that environment variables (passed to container) are available in the script. The purpose of this script is to snapshot any KUBERNETES_* environment variables into the Renviron.site at pod startup, as without these variables kubectl does not work.

Create Services

Extra services to be monitored by s6-overlay should be placed in their own folder under /etc/services.d/ containing a script called run and optionally a finishing script finish.

An example of a service can be found in the run script of .jupyter/s6/services.d/jupyterlab which is used to start JupyterLab itself. For more information about the run and finish scripts, please see the s6-overlay documentation.

Run Services As Root

There may be cases when you need to run a service as root, to do this, you can change the Dockerfile to have USER root at the end, and then use s6-setuidgid to run the user-facing services as $NB_USER.

Our example images run s6-overlay as $NB_USER (not root), meaning any files or scripts related to s6-overlay must be owned by the $NB_USER user to successfully run.

Build Images

The server images depend on each other, so you MUST build them in the correct order.

Build Single Image

You can build a single image (and its dependencies) by running make commands in its directory.

For example, to build the ./jupyter-scipy image:

# from the root of the repository
cd jupyter-scipy

# optionally define a version tag
#  default: sha-{GIT_COMMIT}{GIT_TREE_STATE}
#export TAG="X.Y.Z-patch.N"

# configure the image registry
#  full image name: {REGISTRY}/{IMAGE_NAME}:{TAG}
export REGISTRY="docker.io/MY_USERNAME"

# build and push (current CPU architecture)
make docker-build-dep
make docker-push-dep

To build the image for different CPU architectures, you can use the following commands:

# from the root of the repository
cd jupyter-scipy

# optionally define a version tag
#export TAG="X.Y.Z-patch.N"

# configure the image registry
export REGISTRY="docker.io/MY_USERNAME"

# define the image build cache
#  - sets the following build args:
#     cache-from: type=registry,ref={CACHE_IMAGE}:{IMAGE_NAME}
#     cache-to:   type=registry,ref={CACHE_IMAGE}:{IMAGE_NAME},mode=max
#  - currently, this is a requirement for multi-arch builds.
#    you won't have access to push to the upstream cache,
#    so you will need to set your own cache image.
export CACHE_IMAGE="ghcr.io/kubeflow/kubeflow/notebook-servers/build-cache"

# define the architectures to build for
export ARCH="linux/amd64,linux/arm64"

# build and push (multiple CPU architectures)
# requires that `docker buildx` is configured
make docker-build-push-multi-arch-dep

Build All Images

You can build all images (in the correct order) by running a make command in the root of this directory.

For example, to build all images:

# from the root of the repository
echo $(pwd)

# optionally define a version tag
#export TAG="X.Y.Z-patch.N"

# configure the image registry
export REGISTRY="docker.io/MY_USERNAME"

# build and push (current CPU architecture)
make docker-build
make docker-push

To build the images for different CPU architectures, you can use the following commands:

# from the root of the repository
echo $(pwd)

# optionally define a version tag
#export TAG="X.Y.Z-patch.N"

# configure the image registry
export REGISTRY="docker.io/MY_USERNAME"

# define the image build cache
export CACHE_IMAGE="ghcr.io/kubeflow/kubeflow/notebook-servers/build-cache"

# define the architectures to build for
export ARCH="linux/amd64,linux/arm64"

# build and push (multiple CPU architectures)
make docker-build-push-multi-arch