Merge pull request #120 from mambelli/instructor_links_comments_from_…

…students240229

Instructor links comments from students240229

_episodes/02-running-containers.md

@@ -264,8 +264,9 @@ with Apptainer available.
 > > ## Solution
 > >
 > > ```bash
-> > apptainer exec docker://rootproject/root python3
+> > apptainer exec --cleanenv docker://rootproject/root python3
 > > ```
+> > `--cleanenv` is optional but makes the command more robust (see Episode 4)
 > >
 > > ~~~
 > > INFO:    Using cached SIF image

_episodes/04-building-containers.md

@@ -54,15 +54,28 @@ apptainer build --sandbox myAlma9 docker://almalinux:9
 The container name is `myAlma9`, and it has been initialized from the [official Docker image](https://hub.docker.com/_/almalinux)
 of AlmaLinux9.
 To initialize an interactive session use the `shell` command. And to write files within the sandbox directory use the `--writable` option.
+The `--cleanenv` option is added to make sure that the host environment is not affecting the container.
 Finally, the installation of new components will require superuser access inside the container, so use also the `--fakeroot` option, unless you are already root also outside.
 ```bash
-apptainer shell --writable --fakeroot myAlma9
+apptainer shell --cleanenv --writable --fakeroot myAlma9
 Apptainer> whoami
 ```
 ~~~
 root
 ~~~
 {: .output}
+`--cleanenv` clears the environment. It has been added to make sure that the eventual setting of
+Variables like PYTHONPATH or PYTHONHOME can affect the Python execution inside the container.
+A corrupted Python environment could cause errors like "ModuleNotFoundError: No module named 'encodings'"
+> ## Apptainer environment
+> [Environment variables in Linux](https://www.geeksforgeeks.org/environment-variables-in-linux-unix/)
+> are dynamic values that can affect programs and containers.
+> Apptainer by default preserves most of the outside environment inside the container
+> but has many options to control that.
+> You can clear the environment with the `--cleanenv` option, you can set variables with `--env`.
+> See the [Apptianer manual](https://apptainer.org/docs/user/main/environment_and_metadata.html))
+> for more options and details.
+{: .callout}
 Depending on the Apptainer/Singularity installation (privileged or unprivileged) and the version, you may have some requirements, like the `fakeroot` utility or `newuidmap` and `newgidmap`.
 If you get an error when using `--fakeroot` have a look at the [fakeroot documentation](https://apptainer.org/docs/user/main/fakeroot.html).
 > ## `--fakeroot` is not root

_episodes/08-instances.md

@@ -130,11 +130,13 @@ apptainer build --fakeroot basicServer.sif basicServer.def
 
 Now, let's start an instance named `myWebService` with the image that we just built
 ```bash
-apptainer instance start --no-mount tmp basicServer.sif myWebService
+apptainer instance start --no-mount tmp --cleanenv basicServer.sif myWebService
 ```
 Reminder from the previous chapter: with `--no-mount tmp` we are asking Apptainer to NOT bind `/tmp` from the host
 to the instance (it is mounted by default), we use instead an isolated `/tmp` inside the instance where index.html has
 been copied.
+And with `--cleanenv` we clear the environment.
+
 
 You can confirm in the terminal that the web service is up using `curl` as
 ```bash
@@ -217,7 +219,8 @@ Save the definition file as `jupyterWithROOT.def`, and let's build an image call
 ```bash
 apptainer build --fakeroot jupyterWithROOT.sif jupyterWithROOT.def
 ```
-Now, start an instance named `mynotebook` with our brand-new image
+Now, start an instance named `mynotebook` with our brand-new image.
+Consider using `--cleanenv` if needed.
 ```bash
 apptainer instance start jupyterWithROOT.sif mynotebook
 ```
@@ -243,6 +246,13 @@ http://localhost:8850/?token=12asldc9b2084f9b664b39a6246022312bc9c605b :: /home/
 ~~~
 {: .output}
 
+> ## Notebook starting on a different port!
+> If the chosen port for the Notebook (8850 stated in the SIF file) is not available,
+> the notebook will not error out, but will start and use the first available port after that.
+> E.g. if you did not terminate the web server from the previous example,
+> The above command "jupyter notebook list" will show you the correct port.
+{: .callout}
+
 Open the URL with the token (from http to the first space), and you will be able to see the Jupyter interface. Try to open a new notebook and write in
 a cell to confirm that ROOT is available:
 ```python

_extras/guide.md

@@ -22,57 +22,57 @@ and a quick run through to learn just the bare minimum.
 ### Links used for explanation
 
 Episode 1 (Introduction)
-* [https://hsf-training.github.io/hsf-training-singularity-webpage/01-introduction/index.html]
+* [https://hsf-training.github.io/hsf-training-singularity-webpage/01-introduction/index.html](https://hsf-training.github.io/hsf-training-singularity-webpage/01-introduction/index.html)
 * [https://www.docker.com/resources/what-container/](https://www.docker.com/resources/what-container/)
-* https://q15928.github.io/2021/01/09/container-101/
-* https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0177459
-* https://docs.sylabs.io/guides/2.6/user-guide/singularity_flow.html
-* https://docs.sylabs.io/guides/2.6/user-guide/_images/flow.png
-* https://en.wikipedia.org/wiki/Singularity_%28software%29#History
-* https://apptainer.org/documentation/
-* https://apptainer.org/docs/user/latest/
-* https://github.com/hsf-training/hsf-training-singularity-webpage
+* [https://q15928.github.io/2021/01/09/container-101/](https://q15928.github.io/2021/01/09/container-101/)
+* [https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0177459](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0177459)
+* [https://docs.sylabs.io/guides/2.6/user-guide/singularity_flow.html](https://docs.sylabs.io/guides/2.6/user-guide/singularity_flow.html)
+* [https://docs.sylabs.io/guides/2.6/user-guide/_images/flow.png](https://docs.sylabs.io/guides/2.6/user-guide/_images/flow.png)
+* [https://en.wikipedia.org/wiki/Singularity_%28software%29#History](https://en.wikipedia.org/wiki/Singularity_%28software%29#History)
+* [https://apptainer.org/documentation/](https://apptainer.org/documentation/)
+* [https://apptainer.org/docs/user/latest/](https://apptainer.org/docs/user/latest/)
+* [https://github.com/hsf-training/hsf-training-singularity-webpage](https://github.com/hsf-training/hsf-training-singularity-webpage)
 
 Episode 2
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/02-running-containers/index.html
-* https://circleci.com/blog/docker-image-vs-container/
-* https://singularityhub.github.io/library-api/#/?id=library-api
-* https://docs.google.com/presentation/d/1GMDyEHw02AqFnD8IV9YxeilQZ0E7zQuovtvaS0hgE0s/edit#slide=id.g2bb13c81de3_0_295
-* https://root.cern/
-* https://apptainer.org/docs/user/latest/
+* [https://hsf-training.github.io/hsf-training-singularity-webpage/02-running-containers/index.html](https://hsf-training.github.io/hsf-training-singularity-webpage/02-running-containers/index.html)
+* [https://circleci.com/blog/docker-image-vs-container/](https://circleci.com/blog/docker-image-vs-container/)
+* [https://singularityhub.github.io/library-api/#/?id=library-api](https://singularityhub.github.io/library-api/#/?id=library-api)
+* [https://docs.google.com/presentation/d/1GMDyEHw02AqFnD8IV9YxeilQZ0E7zQuovtvaS0hgE0s/edit#slide=id.g2bb13c81de3_0_295](https://docs.google.com/presentation/d/1GMDyEHw02AqFnD8IV9YxeilQZ0E7zQuovtvaS0hgE0s/edit#slide=id.g2bb13c81de3_0_295)
+* [https://root.cern/](https://root.cern/)
+* [https://apptainer.org/docs/user/latest/](https://apptainer.org/docs/user/latest/)
 
 Episode 4
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/04-building-containers/index.html
-* https://circleci.com/blog/docker-image-vs-container/
-* https://github.com/scikit-hep/uproot5
-* https://uproot.readthedocs.io/en/latest/
-* https://apptainer.org/docs/user/latest/cli/apptainer_build.html
-* https://apptainer.org/docs/user/latest/
+* [https://hsf-training.github.io/hsf-training-singularity-webpage/04-building-containers/index.html](https://hsf-training.github.io/hsf-training-singularity-webpage/04-building-containers/index.html)
+* [https://circleci.com/blog/docker-image-vs-container/](https://circleci.com/blog/docker-image-vs-container/)
+* <https://github.com/scikit-hep/uproot5>
+* <https://uproot.readthedocs.io/en/latest/>
+* <https://apptainer.org/docs/user/latest/cli/apptainer_build.html>
+* <https://apptainer.org/docs/user/latest/>
 
 Episode 5
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/05-definition-files/index.html
-* https://apptainer.org/docs/user/latest/definition_files.html
-* https://apptainer.org/docs/user/latest/
+* <https://hsf-training.github.io/hsf-training-singularity-webpage/05-definition-files/index.html>
+* <https://apptainer.org/docs/user/latest/definition_files.html>
+* <https://apptainer.org/docs/user/latest/>
 
 Episode 7
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/07-file-sharing/index.html
-* https://apptainer.org/docs/user/latest/
+* <https://hsf-training.github.io/hsf-training-singularity-webpage/07-file-sharing/index.html>
+* <https://apptainer.org/docs/user/latest/>
 
 Episode 8
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/08-instances/index.html
-* https://jupyter.org/
-* https://apptainer.org/docs/user/latest/
+* <https://hsf-training.github.io/hsf-training-singularity-webpage/08-instances/index.html>
+* <https://jupyter.org/>
+* <https://apptainer.org/docs/user/latest/>
 
 Episode 9
 * Terminal
-* https://hsf-training.github.io/hsf-training-singularity-webpage/09-bonus-episode/index.html
-* https://swcarpentry.github.io/git-novice/
-* https://hsf-training.github.io/hsf-training-cicd-github/
-* https://apptainer.org/docs/user/latest/
+* <https://hsf-training.github.io/hsf-training-singularity-webpage/09-bonus-episode/index.html>
+* <https://swcarpentry.github.io/git-novice/>
+* <https://hsf-training.github.io/hsf-training-cicd-github/>
+* <https://apptainer.org/docs/user/latest/>
 
 {% include links.md %}