iot-salzburg/gpu-jupyter

GPU‑Jupyter – a ready‑to‑run, GPU‑enabled JupyterLab environment

What it is – A Docker image (and supporting scripts) that bundles NVIDIA’s CUDA runtime, the official Jupyter Docker Stacks, and a full data‑science toolchain (Python, PyTorch, TensorFlow, Julia, R, etc.). The image is built on Ubuntu and can be launched with a single docker run command, giving you a reproducible, shareable JupyterLab server that can directly use the host’s NVIDIA GPUs.

Why it matters – Running deep‑learning code on a GPU usually requires:

• matching CUDA driver versions,
• installing the right Python packages, and
• keeping the environment reproducible across machines. GPU‑Jupyter solves all of this by packaging everything in a version‑controlled Docker image. The same image can be pulled from Docker Hub, or rebuilt locally with custom layers, ensuring that experiments are exactly the same wherever they run.

---

Key Features (as described in the README)

• GPU support out of the box – --gpus all gives the container full access to the host’s GPUs.
• Multiple pre‑built flavours – full image, python‑only, and slim variants for different size/feature needs.
• Versioned images – tags like v1.11_cuda-13.0_ubuntu-24.04 encode the generator version, CUDA version, and Ubuntu base, making experiments reproducible.
• Built‑in deep‑learning libraries – PyTorch, TensorFlow, plus optional Julia and R support.
• JupyterLab UI – launched automatically; token‑based login can be made static via JUPYTER_TOKEN.
• Easy customization – add extra apt packages or pip requirements via a custom Dockerfile that FROM cschranz/gpu-jupyter:….
• Docker‑Compose ready – a sample docker‑compose.yml is provided for more complex deployments.
• TensorBoard integration – ports can be forwarded (-p 6006:6006) and the --bind_all flag is documented.
• Reproducibility focus – the README stresses version‑controlled Dockerfiles, seeded random functions, and tagged data spaces.

---

Typical Use‑Case Workflow

1. Check prerequisites – NVIDIA GPU, drivers, CUDA, Docker, and the NVIDIA Container Toolkit. Verify with docker run --rm --gpus all nvidia/cuda:13.0.3-cudnn-runtime-ubuntu24.04 nvidia-smi.
2. Pull & run – e.g.

   mkdir -p data
   docker run --gpus all -it -p 8848:8888 \
       -v "$(pwd)/data:/home/jovyan/work" \
       -e GRANT_SUDO=yes -e JUPYTER_ENABLE_LAB=yes \
       --user root cschranz/gpu-jupyter:v1.11_cuda-13.0_ubuntu-24.04_python-only
   

   Open the printed token URL (or http://localhost:8848) to start coding.
3. Develop – Use the mounted data/ directory to keep notebooks, scripts, and datasets. Run nvidia-smi inside the notebook to confirm GPU visibility.
4. Add extra packages – either apt install … inside the running container or extend the image with a custom Dockerfile (see the README’s example).
5. Share – Push your custom image to Docker Hub and distribute the Docker‑run command (or a docker‑compose.yml) so collaborators can reproduce the exact environment.

---

Getting Started Resources

• Quickstart section – step‑by‑step command line instructions.
• Sample project – github.com/iot-salzburg/reproducible-research-with-gpu-jupyter demonstrates a full reproducible experiment.
• Installation guide – extra/README‑installations.md and a Medium article for setting up drivers, CUDA, and the NVIDIA Container Toolkit.
• Version list – extra/README‑versions.md enumerates the exact Python, PyTorch, TensorFlow, Julia, and R versions shipped in each tag.
• Tutorial video – link to a JupyterLab introductory YouTube video.

---

Who Might Use This?

• Researchers & students who need a portable, reproducible deep‑learning environment without fiddling with system‑wide CUDA installs.
• Teams that want to share a single Docker image so every member runs the same library versions.
• Educators looking for a plug‑and‑play JupyterLab setup for GPU‑accelerated labs.
• DevOps / MLOps engineers who prefer Docker‑based deployment of notebooks and want to integrate with CI pipelines (the repository even includes a GitHub Actions badge).

---

Limitations Mentioned

• Requires an NVIDIA GPU (or a cloud provider that supplies one).
• The correct CUDA version must be compatible with the host driver; otherwise you need to rebuild the image.
• The default container runs as root; you can change the UID/GID to match the host, but permission handling still needs attention when mounting volumes.

---

Bottom Line

GPU‑Jupyter is a well‑documented, actively maintained Docker‑based distribution that turns a host machine with an NVIDIA GPU into a fully fledged JupyterLab workstation, pre‑loaded with the most common deep‑learning libraries. Its emphasis on versioned images and easy customisation makes it a solid foundation for reproducible AI research and teaching.