testing

Author: RobJY

docs/hpc/09_ood/02_jupyter_with_conda_singularity.mdx

@@ -6,3 +6,111 @@ This page describes how to use your Singularity with conda environment in OOD GU
 ### Log Into Greene via the Terminal
 The following commands must be run from the terminal. Information on accessing via the terminal can be found at [Connecting to the HPC](../02_connecting_to_hpc/01_connecting_to_hpc.mdx) or you can log into OOD and select the `Clusters` tab at the top of the page and select `Greene Shell Access`.
 
+### Preinstallation Warning
+:::warning
+If you have initialized Conda in your base environment, your prompt on Greene may show something like:
+```bash
+(base) [NetID@log-1 ~]$
+```
+then you must first comment out or remove this portion of your `~/.bashrc` file:
+
+```bash
+# >>> conda initialize >>>
+# !! Contents within this block are managed by 'conda init' !!
+__conda_setup="$('/share/apps/anaconda3/2020.07/bin/conda' 'shell.bash' 'hook' 2> /dev/null)"
+if [ $? -eq 0 ]; then
+    eval "$__conda_setup"
+else
+    if [ -f "/share/apps/anaconda3/2020.07/etc/profile.d/conda.sh" ]; then
+        . "/share/apps/anaconda3/2020.07/etc/profile.d/conda.sh"
+    else
+        export PATH="/share/apps/anaconda3/2020.07/bin:$PATH"
+    fi
+fi
+unset __conda_setup
+# <<< conda initialize <<<
+```
+
+The above code automatically makes your environment look for the default shared installation of Conda on the cluster and will sabotage  any attempts to install packages to a Singularity environment. Once removed or commented out, log out and back into the cluster for a fresh environment.
+:::
+
+### Prepare Overlay File 
+```bash
+[NetID@log-1 ~]$ mkdir /scratch/$USER/my_env
+[NetID@log-1 ~]$ cd /scratch/$USER/my_env
+[NetID@log-1 my_env]$ cp -rp /scratch/work/public/overlay-fs-ext3/overlay-15GB-500K.ext3.gz .
+[NetID@log-1 my_env]$ gunzip overlay-15GB-500K.ext3.gz
+```
+Above we used the overlay file `overlay-15GB-500K.ext3.gz` which will contain all of the installed packages. There are more optional overlay files. You can find instructions on the following pages: [Singularity with Conda](../07_containers/03_singularity_with_conda.md), [Squash File System and Singularity](../07_containers/04_squash_file_system_and_singularity.md). 
+
+### Launch Singularity Environment for Installation
+```bash
+[NetID@log-1 ~]$ singularity exec --overlay /scratch/$USER/my_env/overlay-15GB-500K.ext3:rw /scratch/work/public/singularity/cuda12.3.2-cudnn9.0.0-ubuntu-22.04.4.sif /bin/bash
+```
+Above we used the Singularity OS image `cuda12.3.2-cudnn9.0.0-ubuntu-22.04.4.sif` which provides the base operating system environment for the conda environment. There are other Singularity OS images available at `/scratch/work/public/singularity`
+
+Launching Singularity with the `--overlay` flag mounts the overlay file to a new directory: `/ext3` - you will notice that when not using Singularity `/ext3` is not available.
+
+:::warning
+Be sure that you have the Singularity prompt (`Singularity>`) and that `/ext3` is available before the next step.
+```bash
+Singularity> ls -lah /ext3
+total 8.5K
+drwxrwxr-x.  2 root root 4.0K Oct 19 10:01 .
+drwx------. 29 root root 8.0K Oct 19 10:01 ..
+```
+:::
+
+### Install Miniforge to Overlay File
+```bash
+Singularity> wget --no-check-certificate https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
+Singularity> sh Miniforge3-Linux-x86_64.sh -b -p /ext3/miniforge3
+```
+Next, create a wrapper script at `/ext3/env.sh`:
+```bash
+Singularity> touch /ext3/env.sh
+Singularity> echo '#!/bin/bash' >> /ext3/env.sh
+Singularity> echo 'unset -f which' >> /ext3/env.sh
+Singularity> echo 'source /ext3/miniforge3/etc/profile.d/conda.sh' >> /ext3/env.sh
+Singularity> echo 'export PATH=/ext3/miniforge3/bin:$PATH'         >> /ext3/env.sh
+Singularity> echo 'export PYTHONPATH=/ext3/miniforge3/bin:$PATH'   >> /ext3/env.sh
+```
+Your `/ext3/env.sh` file should now contain the following:
+```bash
+#!/bin/bash
+unset -f which
+source /ext3/miniforge3/etc/profile.d/conda.sh
+export PATH=/ext3/miniforge3/bin:$PATH
+export PYTHONPATH=/ext3/miniforge3/bin:$PATH
+```
+The wrapper script will activate your conda environment, to which you will be installing your packages and dependencies. 
+
+Next, activate your conda environment with the following:
+```bash
+Singularity> source /ext3/env.sh
+```
+
+### Install Packages to Miniforge Environment
+Now that your environment is activated, you can update and install packages:
+```bash
+Singularity> conda config --remove channels defaults
+Singularity> conda update -n base conda -y
+Singularity> conda clean --all --yes
+Singularity> conda install pip --yes
+Singularity> conda install ipykernel --yes # Note: ipykernel is required to run as a kernel in the Open OnDemand Jupyter Notebooks
+```
+To confirm that your environment is appropriately referencing your Miniforge installation, try out the following:
+```bash
+Singularity> unset which
+Singularity> which conda
+# output: /ext3/miniforge3/bin/conda
+
+Singularity> which python
+# output: /ext3/miniforge3/bin/python
+
+Singularity> python --version
+# output: Python 3.12.9
+
+Singularity> which pip
+# output: /ext3/miniforge3/bin/pip
+```