Create 05_customize_container_environments.mdx

Author: Amanda-dong

docs/hpc/15_tutorial_apptainer/05_customize_container_environments.mdx

@@ -0,0 +1,67 @@
+## Why Customize a Container Environment?
+Prebuilt container images provide a convenient starting point, but they may not contain all of the software required for a particular project.
+
+Most Apptainer images are distributed as `.sif` files, which are typically read-only. If you need to install additional software or make persistent changes to a container, Apptainer provides overlays, which add a writable layer on top of the original image while leaving the `.sif` file unchanged.
+
+## Example: Creating a Custom Directory with an Overlay
+
+
+Pull a Python container image from Docker Hub:
+
+```bash
+apptainer pull python.sif docker://python:3.10
+```
+
+Create a writable overlay:
+
+```bash
+apptainer overlay create --size 1024 python_overlay.ext3
+```
+
+Launch the container with the overlay attached:
+
+```bash
+apptainer shell \
+    --overlay python_overlay.ext3:rw \
+    python.sif
+```
+
+Verify that numpy is not installed in the base image:
+
+```bash
+python -c "import numpy"
+```
+
+You should see:
+
+```text
+ModuleNotFoundError: No module named 'numpy'
+```
+
+Install numpy:
+
+```bash
+pip install numpy
+```
+
+Verify that the packages are available:
+
+```bash
+python -c "import numpy; print(numpy.__version__)"
+```
+
+Exit the container:
+
+```bash
+exit
+```
+
+The next time you want to use the customized environment, launch the container using the same overlay:
+
+```bash
+apptainer shell \
+    --overlay python_overlay.ext3:rw \
+    python.sif
+```
+
+This demonstrates that software installed within the overlay persists across sessions, while the original `.sif` image remains unchanged.