Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
9 changes: 0 additions & 9 deletions docs/advanced-topics.md

This file was deleted.

14 changes: 7 additions & 7 deletions docs/ci.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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".

Expand Down Expand Up @@ -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"
Expand All @@ -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.

Expand Down
Binary file added docs/downloads/EESSI_tutorial_slides_ISC2026.pdf
Binary file not shown.
49 changes: 41 additions & 8 deletions docs/getting-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand All @@ -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).

Expand Down Expand Up @@ -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).
Expand Down
8 changes: 6 additions & 2 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,19 @@ 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:
<a href="downloads/EESSI_tutorial_slides_ISC2026.pdf" download="EESSI_tutorial_slides_ISC2026.pdf">Download PDF</a>

1. [Introduction to EESSI](introduction.md)
2. [Getting Access to EESSI](getting-access.md)
3. [Using EESSI](usage.md)
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

Expand Down
6 changes: 3 additions & 3 deletions docs/installing-on-top.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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}
Expand Down
15 changes: 12 additions & 3 deletions docs/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
111 changes: 0 additions & 111 deletions docs/markdown.md

This file was deleted.

11 changes: 6 additions & 5 deletions docs/prepared-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand All @@ -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.
Expand All @@ -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,<br/>
**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

Expand All @@ -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.
Loading