From ca8f41eaaefabac42b91974237d9b762060c38df Mon Sep 17 00:00:00 2001
From: mishaschwartz <4380924+mishaschwartz@users.noreply.github.com>
Date: Thu, 2 Oct 2025 11:46:31 -0400
Subject: [PATCH 1/2] Document how to allow Jupyterlab containers to access
 GPUs on the host machine

---
 CHANGES.md                      |  4 +++-
 birdhouse/components/README.rst | 36 +++++++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 1bc8efcc4..723e8c514 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -15,7 +15,9 @@
 [Unreleased](https://github.com/bird-house/birdhouse-deploy/tree/master) (latest)
 ------------------------------------------------------------------------------------------------------------------
 
-[//]: # (list changes here, using '-' for each new entry, remove this when items are added)
+## Documentation
+
+- Document how to allow Jupyterlab containers to access GPUs on the host machine
 
 [2.18.4](https://github.com/bird-house/birdhouse-deploy/tree/2.18.4) (2025-10-01)
 ------------------------------------------------------------------------------------------------------------------
diff --git a/birdhouse/components/README.rst b/birdhouse/components/README.rst
index 273a97175..ea7354c4d 100644
--- a/birdhouse/components/README.rst
+++ b/birdhouse/components/README.rst
@@ -821,6 +821,42 @@ Usage
 The service is available at ``${BIRDHOUSE_PROXY_SCHEME}://${BIRDHOUSE_FQDN_PUBLIC}/jupyter``. Users are able to log in to Jupyterhub using the
 same user name and password as Magpie. They will then be able to launch a personal jupyterlab server.
 
+GPU support for jupyterlab containers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the host machine has GPUs and you want to make them available to the docker containers running Jupyterlab:
+
+1. ensure that the GPU drivers on the host machine are up to date
+2. install the `NVIDIA container toolkit`_ package on the host machine
+3. configure docker to use the NVIDIA as a container run-time (See the "configure docker" section in `NVIDIA container toolkit`_)
+4. restart docker for the changes to take effect
+5. add the following to the ``JUPYTERHUB_CONFIG_OVERRIDE`` variable in your local environment file:
+
+.. code-block:: shell
+
+    export JUPYTERHUB_CONFIG_OVERRIDE='
+    # enable GPU support
+    import docker
+
+    c.DockerSpawner.extra_host_config["device_requests"] = [
+        docker.types.DeviceRequest(count=-1, capabilities=[["gpu"]])
+    ]
+    '
+
+This will allow the docker containers to access all GPUs on the host machine. To limit the number of GPUs you want to make available
+you can change the ``count`` value to a positive integer or you can specify the ``device_ids`` key instead. ``device_ids`` takes a list
+of integers representing the devices (GPUs) that you want to enable. Device IDs for each GPU can be inspected by running the ``nvidia-smi``
+command on the host machine.
+
+For example, if I only want to make available GPUs with ids 1 and 4 you would set:
+
+.. code-block::
+
+   docker.types.DeviceRequest(device_ids=[1, 4], capabilities=[["gpu"]])
+
+.. _NVIDIA container toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html 
+
+
 How to Enable the Component
 ---------------------------
 

From 8e9c6d8f638d994e6ab1956bfe2ecedb954b42fd Mon Sep 17 00:00:00 2001
From: mishaschwartz <4380924+mishaschwartz@users.noreply.github.com>
Date: Fri, 3 Oct 2025 13:24:52 -0400
Subject: [PATCH 2/2] review updates

---
 birdhouse/components/README.rst | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/birdhouse/components/README.rst b/birdhouse/components/README.rst
index ea7354c4d..89b8dbfb2 100644
--- a/birdhouse/components/README.rst
+++ b/birdhouse/components/README.rst
@@ -828,26 +828,28 @@ If the host machine has GPUs and you want to make them available to the docker c
 
 1. ensure that the GPU drivers on the host machine are up to date
 2. install the `NVIDIA container toolkit`_ package on the host machine
-3. configure docker to use the NVIDIA as a container run-time (See the "configure docker" section in `NVIDIA container toolkit`_)
+3. `configure docker`_ to use the NVIDIA as a container run-time
 4. restart docker for the changes to take effect
 5. add the following to the ``JUPYTERHUB_CONFIG_OVERRIDE`` variable in your local environment file:
 
-.. code-block:: shell
+.. code-block:: python
 
-    export JUPYTERHUB_CONFIG_OVERRIDE='
     # enable GPU support
     import docker
 
     c.DockerSpawner.extra_host_config["device_requests"] = [
         docker.types.DeviceRequest(count=-1, capabilities=[["gpu"]])
     ]
-    '
+    
 
 This will allow the docker containers to access all GPUs on the host machine. To limit the number of GPUs you want to make available
 you can change the ``count`` value to a positive integer or you can specify the ``device_ids`` key instead. ``device_ids`` takes a list
 of integers representing the devices (GPUs) that you want to enable. Device IDs for each GPU can be inspected by running the ``nvidia-smi``
 command on the host machine.
 
+The `driver capabilities`_ setting indicates that this device request is for GPUs (as opposed to other devices that may be 
+available such as TPUs). 
+
 For example, if I only want to make available GPUs with ids 1 and 4 you would set:
 
 .. code-block::
@@ -855,7 +857,8 @@ For example, if I only want to make available GPUs with ids 1 and 4 you would se
    docker.types.DeviceRequest(device_ids=[1, 4], capabilities=[["gpu"]])
 
 .. _NVIDIA container toolkit: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html 
-
+.. _configure docker: https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html#configuring-docker
+.. _driver capabilities: https://docs.docker.com/reference/compose-file/deploy/#capabilities
 
 How to Enable the Component
 ---------------------------