User-guide.md

@@ -128,6 +128,61 @@ export SLURM_EAR_LOADER_APPLICATION=my_app
 srun my_app
 ```
 
+## Using EAR inside Singularity containers
+
+[Apptainer](https://apptainer.org/) (formerly Singlarity) is an open source technology for containerization.
+It is widely used in HPC contexts because the level of virtualization it offers enables the access to local services.
+It allows for geater reproducibility, making the programs less dependant on the environment they are being run on.
+
+An example singularity command could look something like this:
+
+```
+singularity exec $IMAGE program
+```
+
+where `IMAGE` is an environment variable that contains the path of the Singularity container, and `program` is the executable to
+be run in the image.
+
+In order to be able to use EAR inside the container two actions are needed:
+
+- Binding EAR paths to make them visible in the container.
+- Exporting some environment variables to the execution environment to make them available during the execution.
+
+To bind folders there are two options: (1) using the environment variable `SINGULARITY_BIND`/`APPTAINER_BIND` or (2) using the `-B` flag when running the container.
+1 is a comma separated string of pairs of paths `[path_1][[:path_2][:perms]]` such that *path_1* in local will be mapped into *path_2* in the image with the permissions set in *perms*, which can be *r* or *rw*.
+Specifying *path_2* and *perm* is optional.
+If they are not specified *path_1* will be bound in the same location.
+
+To make EAR working the following paths sould be added to the binding configuration:
+
+- `$EAR_INSTALL_PATH,$EAR_INSTALL_PATH/bin,$EAR_INSTALL_PATH/lib,$EAR_TMP`
+
+You should have an EAR module to have the above environment variables.
+Contact with your system administrator for more information.
+
+Once paths are deployed, to execute (for example) an OpenMPI application inside a Singularity/Apptainer enabling the EAR Library just the following is needed:
+
+```
+module load ear
+
+mpirun -np <# processes> singularity exec $IMAGE erun --ear=on --program="program args"
+```
+
+A more complete example would look something like this:
+
+```
+export IMAGE=[path_to_image]/ubuntu_ompi.sif
+export BENCH_PATH=[path_to_benchmark]
+export APPTAINER_BIND="$EAR_INSTALL_PATH:$EAR_INSTALL_PATH:ro,$EAR_TMP:$EAR_TMP:rw"
+export APPTAINERENV_EAR_REPORT_ADD=sysfs.so
+
+mpirun -np 64 singularity exec $IMAGE $EAR_INSTALL_PATH/bin/erun \
+    --ear=on --ear-verbose=1 \
+    --program=$BENCH_PATH/bt-mz.D.64
+```
+
+Note that the example exports `APPTAINERENV_EAR_REPORT_ADD` to set the environment variable [`EAR_REPORT_ADD`](EAR-environment-variables#report-plug-ins) to load [`sysfs`](Report#sysfs-report-plugin) report plug-in.
+
 # Retrieving EAR data
 
 As a job accounting and monitoring tool, EARL collects some metrics that you can