From 9c9dee9aa11ed0dd87b2e1446347c3224262482e Mon Sep 17 00:00:00 2001
From: Gwangmu Lee <gwangmu.lee@cscs.ch>
Date: Tue, 17 Jun 2025 12:11:28 +0200
Subject: [PATCH] Update documentation for SquashFS mount

---
 docs/software/container-engine/edf.md |  7 ++++-
 docs/software/container-engine/run.md | 44 +++++++++++++++++++++++++++
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/software/container-engine/edf.md b/docs/software/container-engine/edf.md
index 26eae1fa..421c16f3 100644
--- a/docs/software/container-engine/edf.md
+++ b/docs/software/container-engine/edf.md
@@ -127,7 +127,7 @@ If false, the container filesystem is read-only.
  | **Type**    | array |
  | **Default** | `[]`  |
 
-List of bind mounts in the format `SOURCE:DESTINATION[:FLAGS]`. Flags are optional and can include `ro`, `private`, etc.
+List of mounts in the format `SOURCE:DESTINATION[:FLAGS]`. By default, it performs bind mount unless the only flag is `sqsh`, in which it performs [a SquashFS mount][ref-ce-run-mounting-squashfs]. When bind mounting, the flags are forwarded to the system mount operation (e.g., `ro` or `private`).
 
 !!! example
      * Literal fixed mount map
@@ -145,6 +145,11 @@ List of bind mounts in the format `SOURCE:DESTINATION[:FLAGS]`. Flags are option
         mounts = ["${SCRATCH}:/scratch"]
         ```
 
+     * Mounting a SquashFS image `${SCRATCH}/data.sqsh` to `/data`
+        ```toml
+        mounts = ["${SCRATCH}/data.sqsh:/data:sqsh"]
+        ```
+
 !!! note
     * Mount flags are separated with a plus symbol, for example: `ro+private`.
 
diff --git a/docs/software/container-engine/run.md b/docs/software/container-engine/run.md
index 67a7e5b3..cf9fd8a5 100644
--- a/docs/software/container-engine/run.md
+++ b/docs/software/container-engine/run.md
@@ -182,3 +182,47 @@ Using the `enroot import` documentation page as a reference:
     machine registry.ethz.ch login <username> password <GITLAB_TOKEN>
     machine gitlab.ethz.ch login <username> password <GITLAB_TOKEN>  
     ```
+
+## Working with storage
+
+Directories outside a container can be *mounted* inside a container so that the job inside the container can read/write on them. The directories to mount should be specified in EDF with `mounts`. 
+
+!!! example "Specifying directories to mount in EDF"
+    * Mount `${SCRATCH}` to `/scratch` inside the container
+
+    ```toml
+    mounts = ["${SCRATCH}:/scratch"]
+    ```
+
+    * Mount `${SCRATCH}` to `${SCRATCH}` inside the container
+
+    ```toml
+    mounts = ["${SCRATCH}:${SCRATCH}"]
+    ```
+
+    * Mount `${SCRATCH}` to `${SCRATCH}` and `${HOME}/data` to `${HOME}/data`
+
+    ```toml
+    mounts = ["${SCRATCH}:${SCRATCH}", "${HOME}/data:${HOME}/data"]
+    ```
+
+!!! note
+    The source (before `:`) should be present on the cluster: the destination (after `:`) doesn't have to be inside the container.
+
+See [the EDF reference][ref-ce-edf-reference] for the full specifiction of the `mounts` EDF entry.
+
+
+[](){#ref-ce-run-mounting-squashfs}
+### Mounting a SquashFS image
+
+!!! warning
+    This feature is only available on some vClusters (Daint and Santis, as of 17.06.2025).
+
+A SquashFS image, essentially being a compressed data archive, can also be mounted _as a directory_ so that the image contents are readable inside the container. For this, `:sqsh` should be appended after the destination.
+
+!!! example "Mounting a SquashFS image `${SCRATCH}/data.sqsh` to `/data`" 
+    ```toml
+    mounts = ["${SCRATCH}/data.sqsh:/data:sqsh"]
+    ```
+
+This is particularly useful if a job should read _multiple_ data files _frequently_, which may cause severe file access overheads. Instead, it is recommended to pack data files into one data SquashFS image and mount it inside a container. See the *"magic phase"* in [this documentation](https://tldp.org/HOWTO/SquashFS-HOWTO/creatingandusing.html) for creating a SquashFS image.