From 124791a24c3ef58ae16afc5237d50db1bab5d80e Mon Sep 17 00:00:00 2001
From: Clemens Lange <clemens.lange@cern.ch>
Date: Thu, 25 Jul 2024 10:44:15 +0200
Subject: [PATCH] Add more details on Apptainer usage to setup/getting started
 docs (#268)

---
 README.md      | 14 ++++++++++++--
 docs/setup.rst |  8 ++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index ca5619a2..bd93fc09 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@ conda install --channel conda-forge hepdata-lib
 ```
 
 If you are not sure about your Python environment, please also see below how to use `hepdata_lib` in a Docker or Apptainer container.
+The use of Apptainer is recommended when working on typical HEP computing clusters such as CERN LXPLUS.
 
 ## Getting started
 
@@ -37,7 +38,7 @@ For using `hepdata_lib`, you don't even need to install it, but can use the [bin
 [![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/HEPData/hepdata_lib/main?filepath=examples/Getting_started.ipynb)
 [![SWAN](https://swanserver.web.cern.ch/swanserver/images/badge_swan_white_150.png)](https://cern.ch/swanserver/cgi-bin/go/?projurl=https://github.com/HEPData/hepdata_lib.git)
 
-You can also use the Docker image:
+You can also use the Docker image (recommended when working on local machine):
 
 ```shell
 docker run --rm -it -p 8888:8888 -v ${PWD}:/home/hepdata ghcr.io/hepdata/hepdata_lib:latest
@@ -51,7 +52,16 @@ If you prefer a shell, instead run:
 docker run --rm -it -p 8888:8888 -v ${PWD}:/home/hepdata ghcr.io/hepdata/hepdata_lib:latest bash
 ```
 
-If on CERN LXPLUS or anywhere else where there is Apptainer available but not Docker, you can still use the docker image:
+If on CERN LXPLUS or anywhere else where there is Apptainer available but not Docker, you can still use the docker image.
+
+If CVMFS (specifically `/cvmfs/unpacked.cern.ch/`) is available:
+
+```shell
+export APPTAINER_CACHEDIR="/tmp/$(whoami)/apptainer"
+apptainer shell -B /afs -B /eos /cvmfs/unpacked.cern.ch/ghcr.io/hepdata/hepdata_lib:latest
+```
+
+If CVMFS is not available:
 
 ```shell
 export APPTAINER_CACHEDIR="/tmp/$(whoami)/apptainer"
diff --git a/docs/setup.rst b/docs/setup.rst
index cda8762d..ff0f7107 100644
--- a/docs/setup.rst
+++ b/docs/setup.rst
@@ -33,6 +33,14 @@ On LXPLUS and many other local computing sites with CVMFS and Apptainer (previou
 
 This opens a new shell with ``hepdata_lib``, ROOT, and Python 3 available.
 Your home directory and most other user directories on the machine on which you execute Apptainer will also be accessible from within this shell.
+Additional directories can be made available by using the ``-B`` flag, e.g. ``-B /eos``.
+
+If CVMFS is not available, use the following commands:
+
+::
+
+    export APPTAINER_CACHEDIR="/tmp/$(whoami)/apptainer"
+    apptainer run docker://ghcr.io/hepdata/hepdata_lib:latest /bin/bash
 
 Using SWAN
 ++++++++++