diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e92c352..82550af 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -16,7 +16,7 @@ jobs: uses: codespell-project/actions-codespell@8f01853be192eb0f849a5c7d721450e7a467c579 # v2.2 with: check_filenames: true - skip: '.git' + skip: .git,*.pdf ignore_words_list: - name: install Zensical diff --git a/docs/advanced-topics.md b/docs/advanced-topics.md deleted file mode 100644 index 2fcde33..0000000 --- a/docs/advanced-topics.md +++ /dev/null @@ -1,9 +0,0 @@ -# Customisation of EESSI - -## GPU drivers - -## MPI runtimes - -## Other software installation tools on top of EESSI - -### Spack diff --git a/docs/ci.md b/docs/ci.md index 2367c24..47d6d17 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -10,8 +10,8 @@ **Continuous Integration (CI)** is a software development practice where developers frequently merge their code changes into a shared repository. Each time code is added or updated, automated processes build the application and run tests -to verify that everything still works correctly. This verification workflow is exactly the process we went through in -the last episode: +to verify that everything still works correctly. A basic verification workflow is exactly the process we went +through in the last episode: * Prepare the environment * Build the application @@ -58,7 +58,7 @@ and GitLab to make sure this is the case: The [EESSI GitLab Component](https://gitlab.com/explore/catalog/eessi/gitlab-eessi) also exists, and this allows you to follow a very similar approach to that described - here for GitHub. At the end of the episode we will provide the equivalent file needed to enable GitLab CI. + here for GitHub. Near the end of the episode we will provide the equivalent file needed to enable GitLab CI. The first thing we need to do is to translate our workflow into something that the workflow tool, GitHub Actions in this case, can understand. GitHub itself has @@ -199,7 +199,7 @@ To github.com:vlad/cicd-demo.git * [new branch] add_ci_to_project -> add_ci_to_project ... ``` -(where `vlad` is replaced by your own GitHub user handle). Let's go ahead and create the pull request lile the text +(where `vlad` is replaced by your own GitHub user handle). Let's go ahead and create the pull request like the text suggested by visiting the URL. Once we open the link, we can modify the title/description if we wish, but otherwise we can just go ahead and click "Create pull request". @@ -287,8 +287,8 @@ will become a green tick which indicates that our CI for the commit has passed. ### What happens when CI fails? -What does a failure look like in CI? From the previous episode, we know that if we do not load the `buildenv` module -our tests should fail. Let's +What does a real failure look like in CI? From the previous episode, we know that if we do not load the `buildenv` +module our tests should fail. Let's construct that scenario, by commenting out the line that loads that module: ```yaml title="ci.yml" --8<-- "scripts/ci-broken.yml" @@ -301,7 +301,7 @@ git commit -m "Don't load buildenv, which should break our CI" git push origin add_ci_to_project ``` -Eventually, as expected, our CI will fail and we will get a red X beside our commit. We should also receive an email +Eventually, as expected, our CI will fail and we will get a red `X` beside our commit. We should also receive an email notification that our CI has failed. Such notifications are a critical part of CI, the value of CI is not just that the tests run silently, but that we are made aware immediately when things go wrong. diff --git a/docs/downloads/EESSI_tutorial_slides_ISC2026.pdf b/docs/downloads/EESSI_tutorial_slides_ISC2026.pdf new file mode 100755 index 0000000..bb1347f Binary files /dev/null and b/docs/downloads/EESSI_tutorial_slides_ISC2026.pdf differ diff --git a/docs/getting-access.md b/docs/getting-access.md index 0a97ae7..78735e6 100644 --- a/docs/getting-access.md +++ b/docs/getting-access.md @@ -12,9 +12,10 @@ of the EESSI repository. ## Is EESSI accessible? EESSI can be accessed via [a native (CernVM-FS) installation](#native-installation), -or via [a container that includes CernVM-FS](#eessi-via-a-container). +via [a container that includes CernVM-FS](#eessi-via-a-container), or via a dedicated user-space tool called +[`cvmfsexec`](#eessi-via-cvmfsexec). -Before you look into these options, check if EESSI is already accessible on your system. +Before you look into other options, check if EESSI is already accessible on your system. Run the following command: ``` { .bash .copy } @@ -41,23 +42,20 @@ ls: /cvmfs/software.eessi.io: No such file or directory ``` No worries, you don't need to be a :mage: to get access to EESSI. -Continue reading about the [Native installation](#native-installation) of EESSI, -or accessing [EESSI via a container](#eessi-via-a-container). +Continue reading about the [Native installation](#native-installation) of EESSI, or +accessing EESSI via a [container](#eessi-via-a-container) or via [`cvmfsexec`](#eessi-via-cvmfsexec). ## Native installation Setting up native access to EESSI, that is a system-wide deployment that does not require workarounds like [using a container](#eessi-via-a-container), requires the installation and configuration of [CernVM-FS](https://cernvm.cern.ch/fs). -This requires **admin privileges**, since you need to install CernVM-FS as an OS package. +This requires **administrator privileges**, since you need to install CernVM-FS as an OS package. The following actions must be taken for a (basic) native installation of EESSI: * Installing CernVM-FS itself, ideally using the OS packages provided by the CernVM-FS project (although installing from source is also possible); -* Installing the EESSI configuration for CernVM-FS, which can be done by installing the ``cvmfs-config-eessi`` - package that we provide for the most popular Linux distributions - (more information available [here](https://github.com/EESSI/filesystem-layer/)); * Creating a small client configuration file for CernVM-FS (``/etc/cvmfs/default.local``); see also the [CernVM-FS documentation](https://cvmfs.readthedocs.io/en/stable/cpt-quickstart.html#create-default-local). @@ -180,6 +178,41 @@ In this environment, you should be able to access the EESSI `software.eessi.io` ls /cvmfs/software.eessi.io ``` +## EESSI via `cvmfsexec` + +When you do not have administrator rights, nor access to `singularity`/`apptainer`, there is still another option that +may work for you: [`cvmfsexec`](https://github.com/cvmfs/cvmfsexec) allows you to mount CernVM-FS repositories +as an unprivileged user. + +Whether this approach will work is very dependent on the specific system you have access to. If this approach is your +only option, the best way to check if it will work is to try it out and see if you run into problems. + +The first thing you need to do is clone the `cvmfsexec` repository, and enter the directory +``` { .bash .copy } +git clone https://github.com/cvmfs/cvmfsexec.git +cd cvmfsexec +``` +Once inside this directory, `cvmfsexec` does still require an internet connection and some tools from your system that +may not be available by default (but are quite common): `curl`, `rpm2cpio`, and `cpio`. If those are available then the +see if the steps below work for you. + +First we gather the files that `cvmfsexec` requires (this will also tell you if your OS is supported), +by running the `makedist` script: +``` { .bash .copy } +# +./makedist default +``` + +If that worked, we can try to start `cvmfsexec` as follows, +and see if that result in a shell environment in which EESSI is available: + +``` +./cvmfsexec cvmfs-config.cern.ch software.eessi.io -- bash +``` + +Here we also mount the `cvmfs-config.cern.ch` repository, which provides the necessary configuration files to CernVM-FS to be aware of EESSI. + + --- To start using EESSI, see [Using EESSI](usage.md). diff --git a/docs/index.md b/docs/index.md index ca2e6f8..c27030b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,12 @@ EESSI provides a shared, portable, and optimized software stack for scientific c ## Tutorial Contents -For those attending the live tutorial at ISC26, there is a [prepared environment](prepared-environment.md) available. +For those attending the live tutorial at ISC 2026, there is a [prepared environment](prepared-environment.md) available. + +!!! note "Slidedeck for the ISC 2026 tutorial" + + The slidedeck for the tutorial given at ISC 2026 is available: + Download PDF 1. [Introduction to EESSI](introduction.md) 2. [Getting Access to EESSI](getting-access.md) @@ -20,7 +25,6 @@ For those attending the live tutorial at ISC26, there is a [prepared environment 4. [EESSI Use Cases](use-cases.md) 5. [Installing on top of EESSI](installing-on-top.md) 6. [Using EESSI in CI](ci.md) -7. [Advanced topics](advanced-topics.md) ## Learning Objectives diff --git a/docs/installing-on-top.md b/docs/installing-on-top.md index d68562b..4d13eaa 100644 --- a/docs/installing-on-top.md +++ b/docs/installing-on-top.md @@ -10,7 +10,7 @@ EESSI is sometimes described as "container without a container runtime". What that means is that it effectively provides an alternative operating system to the native one without the need for something to negotiate between the two. When we are _consuming_ software from EESSI, there is no real way to see this. It is only when we try to use EESSI as a -basis for building new sotware that we are exposed to the additional complexity that this can bring. +basis for building new software that we are exposed to the additional complexity that this can bring. ## Building a software project @@ -149,8 +149,8 @@ $ module spider hdf5 We can see there are multiple versions available, but which one do we choose? Our application doesn't specify a specific version so we just choose the latest, `HDF5/1.14.6-gompi-2025b`, for now.The actual version of HDF5 is given by the first part of `1.14.6-gompi-2025b`, in this case `1.14.6`; the final part `gompi-2025b` is related to the -[toolchain concept inside EasyBuild](https://docs.easybuild.io/common-toolchains/) and we won't get into that here -since it is not the purpose of the tutorial. +[toolchain concept used by EasyBuild](https://docs.easybuild.io/common-toolchains/). We won't dive into that toolchain +concept here since it is not the purpose of the tutorial. Having chose to try out `HDF5/1.14.6-gompi-2025b`, we can now load the module to make HDF5 available: ``` { .bash .copy} diff --git a/docs/introduction.md b/docs/introduction.md index 317803e..c9fde87 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -109,7 +109,7 @@ We use custom architecture detection scripts to automatically select the best suited installations from the software stack for a particular host, based on its system architecture. -The software layer is maintained through our [https://github.com/EESSI/software-layer](https://github.com/EESSI/software-layer) GitHub repository. +The software layer is maintained through our [https://github.com/EESSI/software-layer-scripts](https://github.com/EESSI/software-layer) and [https://github.com/EESSI/software-layer](https://github.com/EESSI/software-layer-scripts) GitHub repositories. ## Current status @@ -131,8 +131,17 @@ In February 2022, an open access paper on EESSI was published (https://doi.org/1 During the first half of 2022, the most active partners in the EESSI project worked together on a project proposal to start a EuroHPC Centre-of-Excellence in which EESSI could be developed further. The proposal was accepted, -and hence the [MultiXscale](https://www.multixscale.eu/) EuroHPC Centre-of-Excellence was started. This is a 4-year -project (2023-2026) that is a collaboration between EESSI and [CECAM](https://www.cecam.org/), with goals +and hence the [MultiXscale](https://www.multixscale.eu/) EuroHPC Centre-of-Excellence was started. This was a 4-year +project (2023-2026) forming a collaboration between EESSI and [CECAM](https://www.cecam.org/), with goals that include making EESSI ready for production, and supporting community contributions. +In 2023, the first production release of EESSI under the EESSI production repository +[`software.eessi.io`](https://www.eessi.io/docs/repositories/software.eessi.io/) was made. + +In 2024, EESSI [won the HPCwire Reader's Choice Award at Supercomputing 2024](https://www.eessi.io/docs/blog/2024/11/18/hpcwire-readers-choice-awards-2024-for-eessi/). + +EESSI is also a critical component of the +[EuroHPC Federation Platform (EFP)](https://my-eurohpc.eu/), underpinning the Federated Software Catalogue. The first +release of EFP took place in April 2026. + [*(back to overview page)*](index.md) diff --git a/docs/markdown.md b/docs/markdown.md deleted file mode 100644 index e2da6dc..0000000 --- a/docs/markdown.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -icon: simple/markdown ---- - -# Markdown in 5min - -## Headers - -``` -# H1 Header -## H2 Header -### H3 Header -#### H4 Header -##### H5 Header -###### H6 Header -``` - -## Text formatting - -``` -**bold text** -*italic text* -***bold and italic*** -~~strikethrough~~ -`inline code` -``` - -## Links and images - -``` -[Link text](https://example.com) -[Link with title](https://example.com "Hover title") -![Alt text](image.jpg) -![Image with title](image.jpg "Image title") -``` - -## Lists - -``` -Unordered: - -- Item 1 -- Item 2 - - Nested item - -Ordered: - -1. First item -2. Second item -3. Third item -``` - -## Blockquotes - -``` -> This is a blockquote -> Multiple lines ->> Nested quote -``` - -## Code blocks - -```` -```javascript -function hello() { - console.log("Hello, world!"); -} -``` -```` - -## Tables - -``` -| Header 1 | Header 2 | Header 3 | -|----------|----------|----------| -| Row 1 | Data | Data | -| Row 2 | Data | Data | -``` - -## Horizontal rule - -``` ---- -or -*** -or -___ -``` - -## Task lists - -``` -- [x] Completed task -- [ ] Incomplete task -- [ ] Another task -``` - -## Escaping characters - -``` -Use backslash to escape: \* \_ \# \` -``` - -## Line breaks - -``` -End a line with two spaces -to create a line break. - -Or use a blank line for a new paragraph. -``` \ No newline at end of file diff --git a/docs/prepared-environment.md b/docs/prepared-environment.md index 490a566..84a3cc4 100644 --- a/docs/prepared-environment.md +++ b/docs/prepared-environment.md @@ -4,9 +4,9 @@ Follow the instructions below to get access to a temporary virtual machine that you can use for the hands-on exercises during this tutorial. -!!! note "Only available during EESSI tutorial at ISC'26" +!!! note "Only available during EESSI tutorial at ISC 2026" - This environment is only available during the EESSI tutorial at [ISC'26](https://isc-hpc.com), + This environment is only available during the EESSI tutorial at [ISC 2026](https://isc-hpc.com), on Monday 22 June 2026. Alternatively, you can use a system where EESSI is already available, see [here](https://eessi.io/docs/systems). @@ -20,7 +20,7 @@ that you can use for the hands-on exercises during this tutorial. !!! tip "Do not hesitate to ask for help!" - During the ISC'26 tutorial, raise your hand to ask a question or get help. + During the ISC 2026 tutorial, raise your hand to ask a question or get help. Afterwards, join the EESSI Slack via the "Slack channel" link on the EESSI website [https://eessi.io](https://eessi.io), and ask your question there. @@ -32,7 +32,7 @@ Sign up via https://mokey.tutorial.eessi.science/auth/signup . Accounts will only be approved for access on the day of the tutorial,
**so please take note of your username and password** ! -Note that the *“Reset password”* link does **not** work! +Note that the *"Reset password"* link does **not** work! ## Step 2: Logging in @@ -44,12 +44,13 @@ For shell access, use: ``` ssh tutorial.eessi.science ``` +using the username and password that you created at signup. ### Via web browser Browse to https://tutorial.eessi.science -- Make sure to change default “Time” to 4 hours +- Make sure to change default "Time" to 4 hours - Take 4 cores Alternative, use the login node for hands-on, 16 cores so should be fine to share for a small group. diff --git a/docs/usage.md b/docs/usage.md index 7938d33..f9211e7 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -6,7 +6,7 @@ * Explore the software that EESSI has to offer * Run examples for some software packages included in EESSI -If the EESSI repository is available, all you need to do is set up your shell environment, +If the EESSI repository is available, all you need to do is set up your shell environment and you can start using the software installations that EESSI provides. ## Setting up your environment @@ -17,6 +17,16 @@ To set up the EESSI environment, run the command: source /cvmfs/software.eessi.io/versions/2025.06/init/lmod/bash ``` +!!! note "What if I want a different EESSI version?" + + Indeed there are a few different EESSI versions (`2023.06` and `2025.06`) and this list will continue to grow! You + can always select a different EESSI after initialising by loading the appropriate module. For example, for + `EESSI/2023.06` I can use the initialisation as above with the version changed, or I can use the same + initialisation and switch the `EESSI` module afterwards: + ``` { .bash .copy } + module load EESSI/2023.06 + ``` + This may take a while as data is downloaded from a Stratum 1 server which is part of the CernVM-FS infrastructure to distribute files. You should see the following output: diff --git a/zensical.toml b/zensical.toml index b6edf01..c94ad50 100644 --- a/zensical.toml +++ b/zensical.toml @@ -53,7 +53,6 @@ nav = [ { "Use cases for EESSI" = "use-cases.md" }, { "Installing on top of EESSI" = "installing-on-top.md" }, { "Using EESSI in CI" = "ci.md" }, - { "Advanced topics" = "advanced-topics.md" }, ] # With the "extra_css" option you can add your own CSS styling to customize