Skip to content

Apptainer Recipe for Jupyter Notebook

This example provides an Apptainer recipe to build a container with Jupyter Lab, CUDA support, and PyTorch for use with Open OnDemand. The container includes NVIDIA CUDA runtime, Miniconda package manager, and essential scientific computing packages.

The files for this example can be found at: https://github.com/NCShare/examples/tree/main/Apptainer-Recipe-for-Jupyter-Notebook.

Building the Jupyter Lab Container

Create a jupyter-lab.def file with the following recipe:

jupyter-lab.def
Bootstrap: docker
FROM: nvidia/cuda:12.8.1-cudnn-devel-ubuntu24.04

%help
  This image contains NVidia CUDA, Jupyter Lab, and PyTorch

%labels
  Maintainer Mike Newton
  Maintainer_Email jmnewton@duke.edu

%environment
  export TZ="America/New_York"
  export LANG="en_US.UTF-8"
  export LC_COLLATE="en_US.UTF-8"
  export LC_CTYPE="en_US.UTF-8"
  export LC_MESSAGES="en_US.UTF-8"
  export LC_MONETARY="en_US.UTF-8"
  export LC_NUMERIC="en_US.UTF-8"
  export LC_TIME="en_US.UTF-8"
  export LC_PAPER="en_US.UTF-8"
  export LC_MEASUREMENT="en_US.UTF-8"
  export LC_ALL="en_US.UTF-8"
  export PATH="/opt/conda/bin:$PATH"

%post
  export TZ="America/New_York"
  export DEBIAN_FRONTEND=noninteractive
  # Update Apt index and install some packages
  apt update -qq
  apt install -y build-essential wget curl libcurl4 zlib1g zlib1g-dev sudo

  # Install miniconda
  wget -O Miniforge3.sh "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
  bash Miniforge3.sh -b -p /opt/conda
  rm Miniforge3.sh

  # Install Jupyter and PyTorch
  export PATH="/opt/conda/bin:$PATH"
  mamba install -y jupyter jupyterlab
  pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128

  # Install any other additional modules as needed

%runscript
  exec "${@}"

Then build the container with,

export APPTAINER_CACHEDIR=/work/${USER}/tmp
export APPTAINER_TMPDIR=/work/${USER}/tmp
apptainer build jupyter-lab.sif jupyter-lab.def

You may also install Python packages by providing a requirements.txt file. For example,

requirements.txt
numpy
scipy
pandas
matplotlib
seaborn
scikit-learn

Modify the %files and %post sections in your jupyter-lab.def,

%files
    requirements.txt requirements.txt

%post
    ...
    # Install additional packages
    pip3 install -r requirements.txt

For global access, move the built container to /opt/apps/containers/user/jupyter-lab.sif.

For automated building and deployment to NCShare, refer to the Cluster Software guide.

Using the Jupyter Lab Container on Open OnDemand

To use the container with Open OnDemand, follow these steps.

  1. Navigate to Open OnDemand
  2. Launch the Jupyter Lab application
  3. Under "Apptainer Container File", select your built container (jupyter-lab.sif)
  4. Configure other settings as needed (GPU, memory, etc.)
  5. Launch the session

Command Line Usage

You may also use this container directly from the command line to run a Python script that uses PyTorch or other libraries.

Request an interactive GPU session and run your desired Python application,

srun -p gpu --gres=gpu:h200:1 -t 2:00:00 --mem=20G --pty bash -i

# Run Jupyter Lab with GPU support
apptainer exec --nv jupyter-lab.sif python <your_python_script.py>

To interact with the container in shell-mode, run the following command

apptainer shell --nv jupyter-lab.sif

For batch jobs, create and submit a Slurm script like the one below.

jobscript.sh
#!/bin/bash
#SBATCH -J python-example           # Job name
#SBATCH -p gpu                   # Partition name
#SBATCH --gres=gpu:h200:1        # Number of GPUs
#SBATCH --mem=20G                # Memory per node
#SBATCH -t 2:00:00               # Time limit

cd $SLURM_SUBMIT_DIR
apptainer exec --nv jupyter-lab.sif python <your_python_script.py>