Simplest possible `Dockerfile` that runs with JupyterHub

JupyterHub Zero to JupyterHub on Kubernetes
,
1

At 2i2c, we’ve been helping some folks with creating their own Dockerfiles for use with JupyterHub. There are some docs for this:

  1. in Dockerspawner
  2. I swear it was somewhere in z2jh docs but can’t find it.

Regardless, I thought it would be useful to post some of that here, as I think it would be broadly helpful. It would also probably be nice to accumulate a series of these ‘most minimal for X’ Dockerfile examples for people to learn from.

Here’s two entries!

Simplest possible Dockerfile, with Ubuntu 24.04

Ubuntu 24.04’s docker images come with a non-root user already, so they allow us to create the simplest possible Dockerfile that works:

FROM ubuntu:24.04

# Install python (+ venv, due to PEP 0688 (https://peps.python.org/pep-0668/))
RUN apt update && \
    apt install --yes python3 python3-venv

# Create a venv to install packages into
RUN python3 -m venv /opt/venv

# "Activate" the venv, so `jupyterhub-singleuser` can be found when the container runs
ENV PATH /opt/venv/bin:${PATH}

# Install jupyterhub as well as at least one jupyter frontend
RUN /opt/venv/bin/pip install jupyterhub jupyterlab

# Run as the non-root user we just created
USER 1000

# Indicate what command we would like to be run to start this container image
CMD ["jupyterhub-singleuser"]

This doesn’t allow users to install their own packages (since the venv isn’t chownd), and we can probably get rid of the PATH situation explicitly putting the path for jupyterhub-singleuser, but otherwise I think this is the most minimal image possible.

Simplest possible Dockerfile with Ubuntu 22.04

Earlier versions of Ubuntu didn’t ship with a default non-root user, so we’ll have to add that.

FROM ubuntu:22.04

# Install python (+ venv, due to PEP 0688 (https://peps.python.org/pep-0668/))
# Install adduser, so we can ensure there's a non-root user we can use
RUN apt update && \
    apt install --yes python3 python3-venv adduser

# Create a non-root user
RUN adduser --disabled-password --gecos "Default Jupyter user" \
    --uid 1000 \
     jovyan

# Create a venv to install packages into
RUN python3 -m venv /opt/venv

# "Activate" the venv, so `jupyterhub-singleuser` can be found when the container runs
ENV PATH /opt/venv/bin:${PATH}

# Install jupyterhub as well as at least one jupyter frontend
RUN /opt/venv/bin/pip install jupyterhub jupyterlab

# Run as the non-root user we just created
USER 1000

# Indicate what command we would like to be run to start this container image
CMD ["jupyterhub-singleuser"]

A more complete minimal example, with mamba

The previous two are helpful as bare documentation to understand what is needed. But you most likely want to use things from the conda ecosystem. For that, I recommend this Dockerfile, which also sets up the LaTeX things needed for PDF generation.

What’s your minimal Dockerfile look like?

Would love to see what a ‘minimal’ Dockerfile looks like for you :slight_smile:

5 Likes