Create 02_Running Containers

Author: Amanda-dong

docs/hpc/15_tutorial_apptainer/02_Running Containers

@@ -0,0 +1,111 @@
+# Using Apptainer to Run Commands on Torch
+
+:::warning
+
+Container workloads should be run on compute nodes rather than login nodes.
+
+While simple commands may work on a login node, pulling images, launching software, installing packages, or building environments can consume significant CPU, memory, and storage resources. These activities should be performed within an interactive Slurm allocation or a batch job.
+:::
+
+Torch provides many prebuilt container images under:
+
+```bash
+ls /share/apps/images/
+```
+
+:::note
+
+Torch provides container images with both `.sif` and `.sqf` extensions.
+
+`.sif` is the standard Apptainer image format. Some Torch-provided application images use `.sqf` and may be intended to be launched through wrapper scripts such as `run-anaconda3-2024.10-1.bash`.
+
+When available, use the wrapper script documented for that application. For general Apptainer examples in this tutorial, we use `.sif` images because they work directly with `apptainer exec`, `apptainer run`, and `apptainer shell`.
+
+:::
+
+For this tutorial, we will use the Ubuntu 24.04 image that is already available on the cluster.
+
+## Running Your First Container
+
+Apptainer images can define a default action that runs when the container starts.
+
+To launch a container and execute its default action, use `apptainer run`:
+
+```bash
+apptainer run /share/apps/images/ubuntu-24.04.3.sif
+```
+
+Depending on how the image was built, this command may produce output, launch an application, or simply start and exit.
+
+The important point is that with `apptainer run`, Apptainer executes the default action defined by the image creator.
+
+Sometimes, however, we want to run a specific command instead of the image's default action. In those cases, we use `apptainer exec`.
+
+## Running Specific Commands Within a Container
+
+Unlike `apptainer run`, which executes the image's default action, `apptainer exec` allows us to specify exactly what command should run inside the container.
+
+For example:
+
+```bash
+apptainer exec /share/apps/images/ubuntu-24.04.3.sif /bin/echo "Hello World!"
+```
+
+Output:
+
+```text
+Hello World!
+```
+
+## The Difference Between `apptainer run` and `apptainer exec`
+
+Both `apptainer run` and `apptainer exec` start a container, but they serve different purposes.
+
+`apptainer run` executes the default action defined by the image creator. Depending on how the image was built, this may launch an application, run a script, or perform another predefined task.
+
+`apptainer exec` allows you to specify exactly which command should run inside the container. Rather than relying on the image's default behavior, you provide the command directly.
+
+In practice, `apptainer exec` is often used when working on HPC systems because it provides more control over what is executed inside the container environment.
+
+## Opening an Interactive Shell Within a Container
+
+Sometimes it is useful to explore a container interactively. Apptainer provides the `apptainer shell` command for this purpose.
+
+Launch a shell inside the Ubuntu container:
+
+```bash
+apptainer shell /share/apps/images/ubuntu-24.04.3.sif
+```
+
+You should see a prompt similar to:
+
+```text
+Singularity>
+```
+
+You can now run commands inside the container:
+
+```bash
+whoami
+pwd
+cat /etc/os-release
+```
+
+Example output:
+
+```text
+PRETTY_NAME="Ubuntu 24.04.3 LTS"
+NAME="Ubuntu"
+VERSION_ID="24.04"
+...
+```
+
+Notice that the prompt changes to indicate that you are working inside the container environment.
+
+When you are finished, leave the container with:
+
+```bash
+exit
+```
+
+This returns you to your normal shell on Torch.