docker-stacks Documentation

Technical Documentation: jupyter/docker-stacks

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

Jupyter Docker Stacks

Jupyter Docker Stacks are a set of ready-to-run Docker images containing Jupyter applications and interactive computing tools.
You can use a stack image to do any of the following (and more):

Start a personal Jupyter Server with the JupyterLab frontend (default)
Run JupyterLab for a team using JupyterHub
Start a personal Jupyter Server with the Jupyter Notebook frontend in a local Docker container
Write your own project Dockerfile

Quick Start

You can try the quay.io/jupyter/base-notebook image on https://mybinder.org.
Otherwise, the examples below may help you get started if you have Docker installed,
know which Docker image you want to use, and want to launch a single Jupyter Application in a container.

The User Guide on ReadTheDocs describes additional uses and features in detail.

{note}

Since `2023-10-20` our images are only pushed to `Quay.io` registry.
Older images are available on Docker Hub, but they will no longer be updated.

Example 1

This command pulls the jupyter/scipy-notebook image tagged 2026-07-28 from Quay.io if it is not already present on the local host.
It then starts a container running a Jupyter Server with the JupyterLab frontend and exposes the container's internal port 8888 to port 10000 of the host machine:

bash

docker run -p 10000:8888 quay.io/jupyter/scipy-notebook:2026-07-28

You can modify the host port to which the container's port is mapped by changing the value of the -p option to -p 8888:8888.

Visiting http://<hostname>:10000/?token=<token> in a browser loads JupyterLab,
where:

The hostname is the name of the computer running Docker
The token is the secret token printed in the console.

The container remains intact for restart after the Server exits.

Example 2

This command pulls the jupyter/datascience-notebook image tagged 2026-07-28 from Quay.io if it is not already present on the local host.
It then starts an ephemeral container running a Jupyter Server with the JupyterLab frontend and exposes the server on host port 10000.

bash

docker run -it --rm -p 10000:8888 -v "${PWD}":/home/jovyan/work quay.io/jupyter/datascience-notebook:2026-07-28

The use of the -v flag in the command mounts the current working directory on the host (${PWD} in the example command) as /home/jovyan/work in the container.
The server logs appear in the terminal.

Visiting http://<hostname>:10000/?token=<token> in a browser loads JupyterLab.

Due to the usage of the --rm flag
Docker automatically cleans up the container and removes the file system when the container exits,
but any changes made to the ~/work directory and its files in the container will remain intact on the host.
The -i flag keeps the container's STDIN open, and lets you send input to the container through standard input.
The -t flag attaches a pseudo-TTY to the container.

{note}

By default, [jupyter's root_dir](https://jupyter-server.readthedocs.io/en/latest/other/full-config.html) is `/home/jovyan`.
So, new notebooks will be saved there, unless you change the directory in the file browser.

To change the default directory, you must specify `ServerApp.root_dir` by adding this line to the previous command: `start-notebook.py --ServerApp.root_dir=/home/jovyan/work`.

Choosing Jupyter frontend

JupyterLab is the default for all the Jupyter Docker Stacks images.
It is still possible to switch back to Jupyter Notebook (or to launch a different startup command).
You can achieve this by passing the environment variable DOCKER_STACKS_JUPYTER_CMD=notebook (or any other valid jupyter subcommand) at container startup;
more information is available in the documentation.

Resources

Acknowledgments

Starting from 2022-07-05, aarch64 self-hosted runners were sponsored by @mathbunnyru.
Please, consider sponsoring his work on GitHub
Starting from 2023-10-31, aarch64 self-hosted runners are sponsored by an amazing 2i2c non-profit organization
Starting from 2025-02-11, we use GitHub-hosted aarch64 runners

CPU Architectures

We publish containers for both x86_64 and aarch64 platforms
Single-platform images have either aarch64- or x86_64- tag prefixes, for example, quay.io/jupyter/base-notebook:aarch64-python-3.13.14
Starting from 2022-09-21, we create multi-platform images (except tensorflow-notebook)
Starting from 2023-06-01, we create a multi-platform tensorflow-notebook image as well
Starting from 2024-02-24, we create CUDA enabled variants of pytorch-notebook image for x86_64 platform
Starting from 2024-03-26, we create CUDA enabled variant of tensorflow-notebook image for x86_64 platform
Starting from 2025-12-02, we create CUDA enabled variants of pytorch-notebook and tensorflow-notebook images for aarch64 platform as well

Using old images

This project only builds one set of images at a time.
The weekly build (latest tag) is based on Ubuntu 26.04 and Python 3.13.
If you want to use the older Ubuntu and/or Python version, you can use the following images:

Ubuntu 24.04

Build Date	Python	Tag
2024-10-22	3.11	`b74418220768`
2025-08-11	3.12	`82d322f00937`
2026-09-28	3.13	`ac62373f9f60`

Ubuntu 22.04

Build Date	Python	Tag
2022-10-09	3.7	`b86753318aa1`
2022-10-09	3.8	`7285848c0a11`
2022-10-09	3.9	`ed2908bbb62e`
2023-05-30	3.10	`4d70cf8da953`
2024-08-26	3.11	`00987883e58d`

Ubuntu 20.04

Build Date	Python	Tag
2022-10-09	3.7	`1aac87eb7fa5`
2022-10-09	3.8	`a374cab4fcb6`
2022-10-09	3.9	`5ae537728c69`
2022-10-09	3.10	`f3079808ca8c`

Contributing

Please see the the documentation
for information about how to contribute
issues,
features,
recipes,
tests,
and community-maintained stacks.

LICENSE

This project is licensed under the terms of the Modified BSD License (also known as New or Revised or 3-Clause BSD).

About the Jupyter Development Team

The Jupyter Development Team is the set of all contributors to the Jupyter project.
This includes all of the Jupyter subprojects.

The core team that coordinates development on GitHub can be found here:
https://github.com/jupyter/.

Our Copyright Policy

Jupyter uses a shared copyright model. Each contributor maintains copyright
over their contributions to Jupyter. But, it is important to note that these
contributions are typically only changes to the repositories. Thus, the Jupyter
source code, in its entirety is not the copyright of any single person or
institution. Instead, it is the collective copyright of the entire Jupyter
Development Team. If individual contributors want to maintain a record of what
changes/contributions they have specific copyright on, they should indicate
their copyright in the commit message of the change, when they commit the
change to one of the Jupyter repositories.

With this in mind, the following banner should be used in any source code file
to indicate the copyright and license terms:

text

# Copyright (c) Jupyter Development Team.
# Distributed under the terms of the Modified BSD License.

Alternatives

b-data's JupyterLab docker stacks - For
R,
Python,
MAX/Mojo and
Julia.
With code-server next to JupyterLab.
Just Python – no Conda /
Mamba.
rocker/binder -
From the R focused rocker-project,
lets you run both RStudio and Jupyter either standalone or in a JupyterHub
jupyter/repo2docker -
Turn git repositories into Jupyter-enabled Docker Images
openshift/source-to-image -
A tool for building artifacts from source code and injecting them into docker images
jupyter-on-openshift/jupyter-notebooks -
OpenShift compatible S2I builder for basic notebook images

Overview (`examples/README.md`)

Examples

These examples are not tested and might not work.
Please, send PRs if you start using these examples and see some issues.

Overview (`tagging/README.md`)

Docker stacks tagging and manifest creation

Please, refer to the tagging section of documentation to see how tags and manifests are created.

Overview (`tests/README.md`)

Docker stacks testing

Please, refer to the testing section of documentation to see how the tests are run.

Overview (`examples/docker-compose/README.md`)

Docker Compose example

This example demonstrate how to deploy docker-stack notebook containers to any Docker Machine-controlled host using Docker Compose.

Prerequisites

See the installation instructions for your environment.

Quickstart

Build and run a jupyter/minimal-notebook image on a VirtualBox VM on local desktop.

bash

# create a Docker Machine-controlled VirtualBox VM
bin/vbox.sh mymachine

# activate the docker machine
eval "$(docker-machine env mymachine)"

# build the notebook image on the machine
notebook/build.sh

# bring up the notebook container
notebook/up.sh

To stop and remove the container:

bash

notebook/down.sh

FAQ

How do I specify which docker-stack notebook image to deploy?

You can customize the docker-stack notebook image to deploy by modifying the notebook/Dockerfile.
For example, you can build and deploy a jupyter/all-spark-notebook by modifying the Dockerfile like so:

dockerfile

FROM quay.io/jupyter/all-spark-notebook
# Your RUN commands and so on

Once you modify the Dockerfile, don't forget to rebuild the image.

bash

# activate the docker machine
eval "$(docker-machine env mymachine)"

notebook/build.sh

Can I run multiple notebook containers on the same VM?

Yes. Set environment variables to specify unique names and ports when running the up.sh command.

bash

NAME=my-notebook PORT=9000 notebook/up.sh
NAME=your-notebook PORT=9001 notebook/up.sh

To stop and remove the containers:

bash

NAME=my-notebook notebook/down.sh
NAME=your-notebook notebook/down.sh

Where are my notebooks stored?

The up.sh creates a Docker volume named after the notebook container with a -work suffix, e.g., my-notebook-work.

Yes. Set the WORK_VOLUME environment variable to the same value for each notebook.

bash

NAME=my-notebook PORT=9000 WORK_VOLUME=our-work notebook/up.sh
NAME=your-notebook PORT=9001 WORK_VOLUME=our-work notebook/up.sh

How do I run over HTTPS?

To run the Jupyter Server with a self-signed certificate, pass the --secure option to the up.sh script.
You must also provide a password, which will be used to secure the Jupyter Server.
You can specify the password by setting the PASSWORD environment variable, or by passing it to the up.sh script.

bash

PASSWORD=a_secret notebook/up.sh --secure

# or
notebook/up.sh --secure --password a_secret

Can I use Let's Encrypt certificate chains?

Sure. If you want to secure access to publicly addressable notebook containers, you can generate a free certificate using the Let's Encrypt service.

This example includes the bin/letsencrypt.sh script, which runs the letsencrypt client to create a full-chain certificate and private key, and stores them in a Docker volume.

{note}

The script hard codes several `letsencrypt` options, one of which automatically agrees to the Let's Encrypt Terms of Service.

The following command will create a certificate chain and store it in a Docker volume named mydomain-secrets.

bash

FQDN=host.mydomain.com [email protected] \
    SECRETS_VOLUME=mydomain-secrets \
    bin/letsencrypt.sh

Now run up.sh with the --letsencrypt option.
You must also provide the name of the secrets volume and a password.

bash

PASSWORD=a_secret SECRETS_VOLUME=mydomain-secrets notebook/up.sh --letsencrypt

# or
notebook/up.sh --letsencrypt --password a_secret --secrets mydomain-secrets

Be aware that Let's Encrypt has a pretty low rate limit per domain at the moment.
You can avoid exhausting your limit by testing against the Let's Encrypt staging servers.
To hit their staging servers, set the environment variable CERT_SERVER=--staging.

bash

FQDN=host.mydomain.com [email protected] \
    CERT_SERVER=--staging \
    bin/letsencrypt.sh

Also, be aware that Let's Encrypt certificates are short-lived (90 days).
If you need them for a longer period of time, you'll need to manually set up a cron job to run the renewal steps.
(You can reuse the command above.)

Can I deploy to any Docker Machine host?

Yes, you should be able to deploy to any Docker Machine-controlled host.
To make it easier to get up and running, this example includes scripts to provision Docker Machines to VirtualBox and IBM SoftLayer, but more scripts are welcome!

To create a Docker machine using a VirtualBox VM on local desktop:

bash

bin/vbox.sh mymachine

To create a Docker machine using a virtual device on IBM SoftLayer:

bash

export SOFTLAYER_USER=my_softlayer_username
export SOFTLAYER_API_KEY=my_softlayer_api_key
export SOFTLAYER_DOMAIN=my.domain

# Create virtual device
bin/softlayer.sh myhost

# Add DNS entry (SoftLayer DNS zone must exist for SOFTLAYER_DOMAIN)
bin/sl-dns.sh myhost

Troubleshooting

Unable to connect to VirtualBox VM on Mac OS X when using Cisco VPN client

The Cisco VPN client blocks access to IP addresses that it does not know about, and may block access to a new VM if it is created while the Cisco VPN client is running.

Stop Cisco VPN client. (It does not allow modifications to route table).
Run ifconfig to list vboxnet virtual network devices.
Run sudo route -nv add -net 192.168.99 -interface vboxnetX, where X is the number of the virtual device assigned to the VirtualBox VM.
Start Cisco VPN client.

Overview (`examples/make-deploy/README.md`)

Make deploy example

This folder contains a Makefile and a set of supporting files demonstrating how to run a docker-stack notebook container on a docker-machine controlled host.

Prerequisites

make 3.81+
- Ubuntu users: Be aware of make 3.81 defect 483086 which exists in 14.04 LTS but is fixed in 15.04+
docker-machine 0.5.0+
docker 1.9.0+

Quickstart

To show what's possible, here's how to run the jupyter/minimal-notebook on a brand-new local virtualbox.

bash

# create a new VM
make virtualbox-vm NAME=dev
# make the new VM the active docker machine
eval $(docker-machine env dev)
# pull a docker stack and build a local image from it
make image
# start a Server in a container
make notebook

The last command will log the IP address and port to visit in your browser.

FAQ

Can I run multiple notebook containers on the same VM?

Yes. Specify a unique name and port on the make notebook command.

bash

make notebook NAME=my-notebook PORT=9000
make notebook NAME=your-notebook PORT=9001

Yes.

bash

make notebook NAME=my-notebook PORT=9000 WORK_VOLUME=our-work
make notebook NAME=your-notebook PORT=9001 WORK_VOLUME=our-work

How do I run over HTTPS?

Instead of make notebook, run make self-signed-notebook PASSWORD=your_desired_password.
This target gives you a notebook with a self-signed certificate.

That self-signed certificate is a pain. Let's Encrypt?

Yes. Please.

bash

make letsencrypt FQDN=host.mydomain.com [email protected]
make letsencrypt-notebook

The first command creates a Docker volume named after the notebook container with a -secrets suffix.
It then runs the letsencrypt client with a slew of options (one of which has you automatically agreeing to the Let's Encrypt Terms of Service, see the Makefile).
The second command mounts the secrets volume and configures Jupyter to use the full-chain certificate and private key.

Be aware: Let's Encrypt has a pretty low rate limit per domain at the moment.
You can avoid exhausting your limit by testing against the Let's Encrypt staging servers.
To hit their staging servers, set the environment variable CERT_SERVER=--staging.

bash

make letsencrypt FQDN=host.mydomain.com [email protected] CERT_SERVER=--staging

Also, keep in mind Let's Encrypt certificates are short-lived: 90 days at the moment.
You'll need to manually set up a cron job to run the renewal steps at the moment.
(You can reuse the first command above.)

My pip/conda/apt-get installs disappear every time I restart the container. Can I make them permanent?

bash

# add your pip, conda, apt-get, etc. permanent features to the Dockerfile where
# indicated by the comments in the Dockerfile
vi Dockerfile
make image
make notebook

How do I upgrade my Docker container?

bash

make image DOCKER_ARGS=--pull
make notebook

The first line pulls the latest version of the Docker image used in the local Dockerfile.
Then it rebuilds the local Docker image containing any customizations you may have added to it.
The second line kills your currently running notebook container, and starts a fresh one using the new image.

Can I run on another VM provider other than VirtualBox?

Yes. As an example, there's a softlayer.makefile included in this repo as an example.
You would use it like so:

bash

make softlayer-vm NAME=myhost \
    SOFTLAYER_DOMAIN=your_desired_domain \
    SOFTLAYER_USER=your_user_id \
    SOFTLAYER_API_KEY=your_api_key
eval $(docker-machine env myhost)
# optional, creates a real DNS entry for the VM using the machine name as the hostname
make softlayer-dns SOFTLAYER_DOMAIN=your_desired_domain
make image
make notebook

If you'd like to add support for another docker-machine driver, use the softlayer.makefile as a template.

Where are my notebooks stored?

make notebook creates a Docker volume named after the notebook container with a -data suffix.

Uh ... make?

Yes, sorry Windows users. It got the job done for a simple example.
We can certainly accept other deployment mechanism examples in the parent folder or in other repos.

Are there any other options?

Yes indeed. cat the Makefiles and look at the target parameters.

Overview (`examples/openshift/README.md`)

OpenShift example

This example provides templates for deploying the Jupyter Project docker-stacks images to OpenShift.

Prerequisites

Any OpenShift 3 environment.
The templates were tested with OpenShift 3.7.
It is believed they should work with at least OpenShift 3.6 or later.

Do be aware that the Jupyter Project docker-stacks images are very large.
The OpenShift environment you are using must provide sufficient quota on the per-user space for images and the file system for running containers.
If the quota is too small, the pulling of the images to a node in the OpenShift cluster when deploying them, will fail due to lack of space.
Even if the image is able to run, if the quota is only just larger than the space required for the image, you will not be able to install many packages into the container before running out of space.

OpenShift Online, the public hosted version of OpenShift from Red Hat has a quota of only 3GB for the image and container file system.
As a result, only the minimal-notebook can be started and there is little space remaining to install additional packages.
Although OpenShift Online is suitable for demonstrating these templates work, what you can do in that environment will be limited due to the size of the images.

If you want to experiment with using Jupyter Notebooks in an OpenShift environment, you should instead use Minishift.
Minishift provides you the ability to run OpenShift in a virtual machine on your own local computer.

Loading the Templates

To load the templates, login to OpenShift from the command line and run:

bash

oc create -f https://raw.githubusercontent.com/jupyter/docker-stacks/main/examples/openshift/templates.json

This should create the jupyter-notebook template

The template can be used from the command line using the oc new-app command, or from the OpenShift web console by selecting Add to Project.
This README is only going to explain deploying from the command line.

Deploying a Notebook

To deploy a notebook from the command line using the template, run:

bash

oc new-app --template jupyter-notebook

The output will be similar to:

lang-none

--> Deploying template "jupyter/jupyter-notebook" to project jupyter

     Jupyter Notebook
     ---------
     Template for deploying Jupyter Notebook images.

     * With parameters:
        * APPLICATION_NAME=notebook
        * NOTEBOOK_IMAGE=quay.io/jupyter/minimal-notebook:latest
        * NOTEBOOK_PASSWORD=ded4d7cada554aa48e0db612e1ed1080 # generated

--> Creating resources ...
    configmap "notebook-cfg" created
    deploymentconfig "notebook" created
    route "notebook" created
    service "notebook" created
--> Success
    Access your application via route 'notebook-jupyter.b9ad.pro-us-east-1.openshiftapps.com'
    Run 'oc status' to view your app.

When no template parameters are provided, the name of the deployed notebook will be notebook.
The image used will be:

lang-none

quay.io/jupyter/minimal-notebook:latest

A password you can use when accessing the notebook will be auto generated and is displayed in the output from running oc new-app.

To see the hostname for accessing the notebook run:

bash

oc get routes

The output will be similar to:

lang-none

NAME       HOST/PORT                                               PATH      SERVICES   PORT       TERMINATION     WILDCARD
notebook   notebook-jupyter.abcd.pro-us-east-1.openshiftapps.com             notebook   8888-tcp   edge/Redirect   None

A secure route will be used to expose the notebook outside the OpenShift cluster, so in this case the URL would be:

lang-none

https://notebook-jupyter.abcd.pro-us-east-1.openshiftapps.com/

When prompted, enter the password for the notebook.

Passing Template Parameters

To override the name for the notebook, the image used, and the password, you can pass template parameters using the --param option.

bash

oc new-app --template jupyter-notebook \
    --param APPLICATION_NAME=mynotebook \
    --param NOTEBOOK_IMAGE=quay.io/jupyter/scipy-notebook:latest \
    --param NOTEBOOK_PASSWORD=mypassword

You can deploy any of the Jupyter Project docker-stacks images.

If you don't care what version of the image is used, add the :latest tag at the end of the image name, otherwise use the hash corresponding to the image version you want to use.

Deleting the Notebook Instance

To delete the notebook instance, run oc delete using a label selector for the application name.

bash

oc delete all,configmap --selector app=mynotebook

Adding Persistent Storage

You can upload notebooks and other files using the web interface of the notebook.
Any uploaded files or changes you make to them will be lost when the notebook instance is restarted.
If you want to save your work, you need to add persistent storage to the notebook.
To add persistent storage run:

bash

oc set volume dc/mynotebook --add \
    --type=pvc --claim-size=1Gi --claim-mode=ReadWriteOnce \
    --claim-name mynotebook-data --name data \
    --mount-path /home/jovyan

When you have deleted the notebook instance, if using a persistent volume, you will need to delete it in a separate step.

bash

oc delete pvc/mynotebook-data

Customizing the Configuration

If you want to set any custom configuration for the notebook, you can edit the config map created by the template.

bash

oc edit configmap/mynotebook-cfg

The data field of the config map contains Python code used as the jupyter_server_config.py file.

If you are using a persistent volume, you can also create a configuration file at:

lang-none

/home/jovyan/.jupyter/jupyter_server_config.py

This will be merged at the end of the configuration from the config map.

Because the configuration is Python code, ensure any indenting is correct.
Any errors in the configuration file will cause the notebook to fail when starting.

If the error is in the config map, edit it again to fix it and trigger a new deployment if necessary by running:

bash

oc rollout latest dc/mynotebook

If you make an error in the configuration file stored in the persistent volume, you will need to scale down the notebook, so it isn't running.

bash

oc scale dc/mynotebook --replicas 0

Then run:

bash

oc debug dc/mynotebook

to run the notebook in debug mode.
This will provide you with an interactive terminal session inside a running container, but the notebook will not have been started.
Edit the configuration file in the volume to fix any errors and exit the terminal session.

Start up the notebook again.

bash

oc scale dc/mynotebook --replicas 1

Changing the Notebook Password

The password for the notebook is supplied as a template parameter, or if not supplied will be automatically generated by the template.
It will be passed into the container through an environment variable.

If you want to change the password, you can do so by editing the environment variable on the deployment configuration.

bash

oc set env dc/mynotebook JUPYTER_NOTEBOOK_PASSWORD=mypassword

This will trigger a new deployment so ensure you have downloaded any work if not using a persistent volume.

If using a persistent volume, you could instead set up a password in the file /home/jovyan/.jupyter/jupyter_server_config.py as per guidelines in https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html.

Deploying from a Custom Image

If you want to deploy a custom variant of the Jupyter Project docker-stacks images, you can replace the image name with that of your own.
If the image is not stored on Quay.io, but some other public image registry, prefix the name of the image with the image registry host details.

If the image is in your OpenShift project, because you imported the image into OpenShift, or used the docker build strategy of OpenShift to build a derived custom image,
you can use the name of the image stream for the image name, including any image tag if necessary.

This can be illustrated by first importing an image into the OpenShift project.

bash

oc import-image quay.io/jupyter/datascience-notebook:latest --confirm

Then deploy it using the name of the image stream created.

bash

oc new-app --template jupyter-notebook \
    --param APPLICATION_NAME=mynotebook \
    --param NOTEBOOK_IMAGE=datascience-notebook \
    --param NOTEBOOK_PASSWORD=mypassword

Importing an image into OpenShift before deploying it means that when a notebook is started, the image need only be pulled from the internal OpenShift image registry rather than Quay.io for each deployment.
Because the images are so large, this can speed up deployments when the image hasn't previously been deployed to a node in the OpenShift cluster.

Overview (`examples/source-to-image/README.md`)

Custom Jupyter Notebook images

This example provides scripts for building custom Jupyter Notebook images containing notebooks, data files, and with Python packages required by the notebooks already installed.
The scripts provided work with the Source-to-Image tool, and you can create the images from the command line on your own computer.
Templates are also provided to enable running builds in OpenShift, as well as deploying the resulting image to OpenShift to make it available.

The build scripts, when used with the Source-to-Image tool, provide similar capabilities to repo2docker.
When builds are run under OpenShift with the supplied templates, it provides similar capabilities to mybinder.org,
but where notebook instances are deployed in your existing OpenShift project and JupyterHub is not required.

For separate examples of using JupyterHub with OpenShift, see the project:

https://github.com/jupyter-on-openshift/jupyterhub-quickstart

Source-to-Image Project

Source-to-Image (S2I) is an open source project which provides a tool for creating container images.
It works by taking a base image, injecting additional source code or files into a running container created from the base image,
and running a builder script in the container to process the source code or files to prepare the new image.

Details on the S2I tool, and executable binaries for Linux, macOS and Windows, can be found on GitHub at:

https://github.com/openshift/source-to-image

The tool is standalone, and can be used on any system which provides a docker daemon for running containers.
To provide an end-to-end capability to build and deploy applications in containers, support for S2I is also integrated into container platforms such as OpenShift.

Getting Started with S2I

As an example of how S2I can be used to create a custom image with a bundled set of notebooks, run:

bash

s2i build \
    --scripts-url https://raw.githubusercontent.com/jupyter/docker-stacks/main/examples/source-to-image \
    --context-dir docs/source/examples/Notebook \
    https://github.com/jupyter/notebook \
    quay.io/jupyter/minimal-notebook:latest \
    notebook-examples

This example command will pull down the Git repository https://github.com/jupyter/notebook
and build the image notebook-examples using the files contained in the docs/source/examples/Notebook directory of that Git repository.
The base image which the files will be combined with is quay.io/jupyter/minimal-notebook:latest, but you can specify any of the Jupyter Project docker-stacks images as the base image.

The resulting image from running the command can be seen by running docker images command:

bash

docker images
# REPOSITORY         TAG     IMAGE ID      CREATED        SIZE
# notebook-examples  latest  f5899ed1241d  2 minutes ago  2.59GB

You can now run the image.

bash

docker run --rm -p 8888:8888 notebook-examples

Open your browser on the URL displayed, and you will find the notebooks from the Git repository and can work with them.

The S2I Builder Scripts

Normally when using S2I, the base image would be S2I enabled and contain the builder scripts needed to prepare the image and define how the application in the image should be run.
As the Jupyter Project docker-stacks images are not S2I enabled (although they could be),
in the above example the --scripts-url option has been used to specify that the example builder scripts contained in this directory of this Git repository should be used.

Using the --scripts-url option, the builder scripts can be hosted on any HTTP server,
or you could also use builder scripts local to your computer file using an appropriate file:// format URI argument to --scripts-url.

The builder scripts in this directory of this repository are assemble and run and are provided as examples of what can be done.
You can use the scripts as is, or create your own.

The supplied assemble script performs a few key steps.

The first steps copy files into the location they need to be when the image is run, from the directory where they are initially placed by the s2i command.

bash

cp -Rf /tmp/src/. "/home/${NB_USER}"

rm -rf /tmp/src

The next steps are:

bash

if [ -f "/home/${NB_USER}/environment.yml" ]; then
    mamba env update --name root --file "/home/${NB_USER}/environment.yml"
    mamba clean --all -f -y
else
    if [ -f "/home/${NB_USER}/requirements.txt" ]; then
        pip --no-cache-dir install -r "/home/${NB_USER}/requirements.txt"
    fi
fi

This determines whether a environment.yml or requirements.txt file exists with the files and if so, runs the appropriate package management tool to install any Python packages listed in those files.

This means that so long as a set of notebook files provides one of these files listing what Python packages they need,
those packages will be automatically installed into the image, so they are available when the image is run.

A final step is:

bash

fix-permissions "${CONDA_DIR}"
fix-permissions "/home/${NB_USER}"

This fixes up permissions on any new files created by the build.
This is necessary to ensure that when the image is run, you can still install additional files.
This is important for when an image is run in sudo mode, or it is hosted in a more secure container platform such as Kubernetes/OpenShift where it will be run as a set user ID that isn't known in advance.

As long as you preserve the first and last set of steps, you can do whatever you want in the assemble script to install packages, create files etc.
Do be aware though that S2I builds do not run as root and so you cannot install additional system packages.
If you need to install additional system packages, use a Dockerfile and normal docker build to first create a new custom base image from the Jupyter Project docker-stacks images,
with the extra system packages, and then use that image with the S2I build to combine your notebooks and have Python packages installed.

The run script in this directory is very simple and just runs the notebook application.

bash

exec start-notebook.py "$@"

Integration with OpenShift

The OpenShift platform provides integrated support for S2I type builds.
Templates are provided for using the S2I build mechanism with the scripts in this directory.
To load the templates run:

bash

oc create -f https://raw.githubusercontent.com/jupyter/docker-stacks/main/examples/source-to-image/templates.json

This will create the templates:

bash

jupyter-notebook-builder
jupyter-notebook-quickstart

The templates can be used from the OpenShift web console or command line.
This README is only going to explain deploying from the command line.

To use the OpenShift command line to build into an image, and deploy, the set of notebooks used above, run:

bash

oc new-app --template jupyter-notebook-quickstart \
    --param APPLICATION_NAME=notebook-examples \
    --param GIT_REPOSITORY_URL=https://github.com/jupyter/notebook \
    --param CONTEXT_DIR=docs/source/examples/Notebook \
    --param BUILDER_IMAGE=quay.io/jupyter/minimal-notebook:latest \
    --param NOTEBOOK_PASSWORD=mypassword

You can provide a password using the NOTEBOOK_PASSWORD parameter.
If you don't set that parameter, a password will be generated, with it being displayed by the oc new-app command.

Once the image has been built, it will be deployed.
To see the hostname for accessing the notebook, run oc get routes.

lang-none

NAME                HOST/PORT                                                       PATH SERVICES           PORT      TERMINATION    WILDCARD
notebook-examples   notebook-examples-jupyter.abcd.pro-us-east-1.openshiftapps.com       notebook-examples  8888-tcp  edge/Redirect  None

As the deployment will use a secure connection, the URL for accessing the notebook in this case would be https://notebook-examples-jupyter.abcd.pro-us-east-1.openshiftapps.com.

If you only want to build an image but not deploy it, you can use the jupyter-notebook-builder template.
You can then deploy it using the jupyter-notebook template provided with the openshift examples directory.

See the openshift examples directory for further information on customizing configuration for a Jupyter Notebook deployment and deleting a deployment.