From 484975ccca4f8df5eb0359a6e83068ff91db46d0 Mon Sep 17 00:00:00 2001
From: Tom Eichlersmith <31970302+tomeichlersmith@users.noreply.github.com>
Date: Fri, 10 Jan 2025 16:14:14 -0600
Subject: [PATCH] more detail on using containers for jupyter lab on S3DF (#72)

* update notes on using jupyter via containers

- S3DF has an apptainer installation (which still has a symlink to singularity but it is helpful to use the right name so the right docs are found)
- One can have apptainer download and create the image from an publicly-available OCI image tag (which are most images folks will be using)

* add helpful note about fixing up prompt

* reword instructions on image path

hopefully make it more clear the two different ways to specify an image
---
 interactive-compute.md | 28 +++++++++++++++++++++++-----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/interactive-compute.md b/interactive-compute.md
index 1e1de5e..5ccf5d7 100644
--- a/interactive-compute.md
+++ b/interactive-compute.md
@@ -91,15 +91,33 @@ Replace `<path-to-miniconda3>` and `<your-environment-name>` appropriately.
 Fill the rest of the form as you would for any provided Jupyter Instance and click "Launch". If you run into any issues, please see [Debugging your interactive session](#debugging).
 
 
-#### In an Apptainer container
+#### in a container
 
-Once you have built or pulled an Apptainer image on SDF (see [Software/Apptainer](software.md#apptainer) page for more information on how to do that), ensuring that you have the `jupyter[lab]` binary in the image's `PATH`, go to the [Jupyter portal](/pun/sys/dashboard/batch_connect/sys/slac-ood-jupyter/session_contexts/new ':ignore'), select "Custom Apptainer Image" from the "Jupyter Instance" dropown menu. Then modify the text in the "Commands to initiate Jupyter":
+Once you have built or pulled a container image on SDF (see [Software/Apptainer](software.md#apptainer) page for more information on how to do that), ensuring that you have the `jupyter[lab]` binary in the image's `PATH`, go to the [Jupyter portal](/pun/sys/dashboard/batch_connect/sys/slac-ood-jupyter/session_contexts/new ':ignore'), select "Custom Apptainer Image" from the "Jupyter Instance" dropown menu. Then modify the text in the "Commands to initiate Jupyter":
 ```bash
-export APPTAINER_IMAGE_PATH=<path-to-the.sif>
-function jupyter() { apptainer exec --nv -B /sdf,/lscratch ${APPTAINER_IMAGE_PATH} jupyter $@; }
+export APPTAINER_IMAGE_PATH=<path to apptainer image>
+function jupyter() {
+  apptainer \
+    exec \
+    --nv \
+    -B /sdf,/fs,/sdf/scratch,/lscratch \
+    ${APPTAINER_IMAGE_PATH} \
+    jupyter $@;
+}
 ```
 
-Replace `<path-to-the.sif>` with the full path to your local apptainer image file.
+Replace `<path-to-the.sif>` with the image you want to use for jupyter. `<path-to-the.sif>` could be
+- The full path to a image you've already built on SDF: For example, if you ran `apptainer build` in your home directory, the image path may be `/sdf/home/u/username/my-special-jupyter.sif`
+- A tag available publicly on a remote registry (for example, `docker://jupyter/datascience-notebook:lab-4.0.7` would download and use [a specific version of Jupyter Lab](https://hub.docker.com/layers/jupyter/datascience-notebook/lab-4.0.7/images/sha256-9504f4f4ab7e89b49d61d7be2e9ff8c57870de2050aa4360f55b2e59193f7486?context=explore) already packaged into a container by Project Jupyter
+  - Note: If you use this method, the image will still need to be downloaded onto SDF and (by default) take up disk space in your home directory (in `~/.apptainer`) storing the resulting image.
+
+By default `apptainer` overrides your terminal prompt with `Apptainer> ` in order to emphasize that you are opening a terminal within a container.
+I prefer a less stark reminder and instead include the following lines in my `~/.bashrc` to have my normal prompt (but with a `(apptainer)` prefix if I'm in a container).
+```bash
+# add a prefix if this shell is in a container
+export PROMPT_COMMAND='[ -f /singularity ] && PS1="(apptainer) ${PS1}"; unset PROMPT_COMMAND'
+```
+This will make the terminals that you open in Jupyter Lab appear normal (expect the `(apptainer) ` prefix).
 
 Fill the rest of the form as you would for any provided Jupyter Instance and click "Launch". If you run into any issues, please see [Debugging your interactive session](#debugging).