Add documentation on running EESSI from a virtual machine (via Lima on macOS, WSL on Windows)

docs/getting_access/eessi_limactl.md

@@ -0,0 +1,218 @@
+# Installing EESSI with Lima on MacOS
+
+## Installation of Lima
+
+See Lima documentation: [https://lima-vm.io/docs/installation/](https://lima-vm.io/docs/installation/)
+
+``` { .bash .copy }
+brew install lima
+```
+
+## Installing EESSI in `limactl` with EESSI template
+
+### Example `eessi.yaml` file
+
+Use the EESSI template to install a virtual machine with eessi installed. Create a `eessi.yaml` file
+
+=== "Install a virtual machine with a Debian image"
+    ``` { .bash .copy }
+    # A template to use the EESSI software stack (see https://eessi.io) on macOS
+    # $ limactl start ./eessi.yaml
+    # $ limactl shell eessi
+
+    images:
+    # Try to use release-yyyyMMdd image if available. Note that release-yyyyMMdd will be removed after several months.
+    - location: "https://cloud.debian.org/images/cloud/bookworm/20240429-1732/debian-12-genericcloud-amd64-20240429-1732.qcow2"
+      arch: "x86_64"
+      digest: "sha512:6cc752d71b390c7fea64b0b598225914a7f4adacd4a33fa366187fac01094648628e0681a109ae9320b9a79aba2832f33395fa13154dad636465b7d9cdbed599"
+    - location: "https://cloud.debian.org/images/cloud/bookworm/20240429-1732/debian-12-genericcloud-arm64-20240429-1732.qcow2"
+      arch: "aarch64"
+      digest: "sha512:59afc40ad0062ca100c9280a281256487348c8aa23b3e70c329a6d6f29b5343b628622e63e0b9b4fc3987dd691d5f3c657233186b3271878d5e0aa0b4d264b06"
+    # Fallback to the latest release image.
+    # Hint: run `limactl prune` to invalidate the cache
+    - location: "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-amd64.qcow2"
+      arch: "x86_64"
+    - location: "https://cloud.debian.org/images/cloud/bookworm/latest/debian-12-genericcloud-arm64.qcow2"
+      arch: "aarch64"
+
+    mounts:
+    - location: "~"
+    - location: "/tmp/lima"
+      writable: true
+    containerd:
+      system: false
+      user: false
+    provision:
+    - mode: system
+      script: |
+        #!/bin/bash
+        wget -P /tmp https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
+        sudo dpkg -i /tmp/cvmfs-release-latest_all.deb
+        rm -f /tmp/cvmfs-release-latest_all.deb
+        sudo apt-get update
+        sudo apt-get install -y cvmfs
+        if [ ! -f /etc/cvmfs/default.local ]; then
+            sudo echo "CVMFS_HTTP_PROXY=DIRECT" >> /etc/cvmfs/default.local
+            sudo echo "CVMFS_QUOTA_LIMIT=10000" >> /etc/cvmfs/default.local
+        fi
+        sudo cvmfs_config setup
+    probes:
+    - script: |
+        #!/bin/bash
+        set -eux -o pipefail
+        if ! timeout 30s bash -c "until ls /cvmfs/software.eessi.io >/dev/null 2>&1; do sleep 3; done"; then
+          echo >&2 "EESSI repository is not available yet"
+          exit 1
+        fi
+      hint: See "/var/log/cloud-init-output.log" in the guest
+    ```
+=== "Install a virtual machine with an Ubuntu image"
+    ``` { .bash .copy }
+    # A template to use the EESSI software stack (see https://eessi.io) on macOS
+    # $ limactl start ./eessi.yaml
+    # $ limactl shell eessi
+
+    images:
+    # Try to use release-yyyyMMdd image if available. Note that release-yyyyMMdd will be removed after several months.
+    - location: "https://cloud-images.ubuntu.com/releases/22.04/release-20240514/ubuntu-22.04-server-cloudimg-amd64.img"
+      arch: "x86_64"
+      digest: "sha256:1718f177dde4c461148ab7dcbdcf2f410c1f5daa694567f6a8bbb239d864b525"
+    - location: "https://cloud-images.ubuntu.com/releases/22.04/release-20240514/ubuntu-22.04-server-cloudimg-arm64.img"
+      arch: "aarch64"
+      digest: "sha256:f6bf7305207a2adb9a2e2f701dc71f5747e5ba88f7b67cdb44b3f5fa6eea94a3"
+    # Fallback to the latest release image.
+    # Hint: run `limactl prune` to invalidate the cache
+    - location: "https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img"
+      arch: "x86_64"
+    - location: "https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-arm64.img"
+      arch: "aarch64"
+
+    mounts:
+    - location: "~"
+    - location: "/tmp/lima"
+      writable: true
+    containerd:
+      system: false
+      user: false
+    provision:
+    - mode: system
+      script: |
+        #!/bin/bash
+        wget -P /tmp https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
+        sudo dpkg -i /tmp/cvmfs-release-latest_all.deb
+        rm -f /tmp/cvmfs-release-latest_all.deb
+        sudo apt-get update
+        sudo apt-get install -y cvmfs
+        if [ ! -f /etc/cvmfs/default.local ]; then
+            sudo echo "CVMFS_HTTP_PROXY=DIRECT" >> /etc/cvmfs/default.local
+            sudo echo "CVMFS_QUOTA_LIMIT=10000" >> /etc/cvmfs/default.local
+        fi
+        sudo cvmfs_config setup
+    probes:
+    - script: |
+        #!/bin/bash
+        set -eux -o pipefail
+        if ! timeout 30s bash -c "until ls /cvmfs/software.eessi.io >/dev/null 2>&1; do sleep 3; done"; then
+          echo >&2 "EESSI repository is not available yet"
+          exit 1
+        fi
+       hint: See "/var/log/cloud-init-output.log" in the guest
+    ```
+=== "Install a virtual machine with a Rocky 9 image"
+    ```
+    # A template to use the EESSI software stack (see https://eessi.io) on macOS
+    # $ limactl start ./eessi.yaml
+    # $ limactl shell eessi
+
+    images:
+    - location: "https://dl.rockylinux.org/pub/rocky/9.3/images/x86_64/Rocky-9-GenericCloud-Base-9.3-20231113.0.x86_64.qcow2"
+      arch: "x86_64"
+      digest: "sha256:7713278c37f29b0341b0a841ca3ec5c3724df86b4d97e7ee4a2a85def9b2e651"
+    - location: "https://dl.rockylinux.org/pub/rocky/9.3/images/aarch64/Rocky-9-GenericCloud-Base-9.3-20231113.0.aarch64.qcow2"
+      arch: "aarch64"
+      digest: "sha256:1948a5e00786dbf3230335339cf96491659e17444f5d00dabac0f095a7354cc1"
+    # Fallback to the latest release image.
+    # Hint: run `limactl prune` to invalidate the cache
+    - location: "https://dl.rockylinux.org/pub/rocky/9/images/x86_64/Rocky-9-GenericCloud.latest.x86_64.qcow2"
+      arch: "x86_64"
+    - location: "https://dl.rockylinux.org/pub/rocky/9/images/aarch64/Rocky-9-GenericCloud.latest.aarch64.qcow2"
+      arch: "aarch64"
+
+    mounts:
+    - location: "~"
+    - location: "/tmp/lima"
+      writable: true
+    containerd:
+      system: false
+      user: false
+    provision:
+    - mode: system
+      script: |
+        #!/bin/bash
+        sudo yum install -y https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest.noarch.rpm
+        sudo yum install -y cvmfs
+        if [ ! -f /etc/cvmfs/default.local ]; then
+            sudo echo "CVMFS_HTTP_PROXY=DIRECT" >> /etc/cvmfs/default.local
+            sudo echo "CVMFS_QUOTA_LIMIT=10000" >> /etc/cvmfs/default.local
+        fi
+        sudo cvmfs_config setup
+    probes:
+    - script: |
+        #!/bin/bash
+        set -eux -o pipefail
+        if ! timeout 30s bash -c "until ls /cvmfs/software.eessi.io >/dev/null 2>&1; do sleep 3; done"; then
+          echo >&2 "EESSI repository is not available yet"
+          exit 1
+        fi
+      hint: See "/var/log/cloud-init-output.log" in the guest
+    ```
+
+### Create the virtual machine with the `eessi.yaml` file
+
+``` { .bash .copy }
+limactl create --name eessi ./eessi.yaml
+```
+
+### Start and enter the virtual machine
+
+``` { .bash .copy }
+limactl start eessi
+limactl shell eessi
+```
+
+EESSI should now be available in the virtual machine
+
+```
+user@machine:/Users/user$ source /cvmfs/software.eessi.io/versions/2023.06/init/bash
+  Found EESSI repo @ /cvmfs/software.eessi.io/versions/2023.06!
+  archdetect says x86_64/intel/haswell
+  Using x86_64/intel/haswell as software subdirectory.
+  Found Lmod configuration file at /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/.lmod/lmodrc.lua
+  Found Lmod SitePackage.lua file at /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/.lmod/SitePackage.lua
+  Using /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/modules/all as the directory to be added to MODULEPATH.
+  Using /cvmfs/software.eessi.io/host_injections/2023.06/software/linux/x86_64/intel/haswell/modules/all as the site extension directory to be added to MODULEPATH.
+  Initializing Lmod...
+  Prepending /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/modules/all to $MODULEPATH...
+  Prepending site path /cvmfs/software.eessi.io/host_injections/2023.06/software/linux/x86_64/intel/haswell/modules/all to $MODULEPATH...
+  Environment set up to use EESSI (2023.06), have fun!
+```
+
+### Cleanup virtual machine
+
+``` { .bash .copy }
+limactl stop eessi
+limactl delete eessi
+limactl prune
+``` 
+
+### Advanced: Set resources for new virtual machine
+
+``` { .bash .copy }
+# Set resources
+RATIO_RAM=0.5
+RAM=$(numfmt --to=none --to-unit=1073741824 --format=%.0f  $(echo $(sysctl hw.memsize_usable | awk '{print $2}' ) "*$RATIO_RAM" | bc -l))
+CPUS=$(sysctl hw.physicalcpu | awk '{print $2}')
+# Create VM
+limactl create --cpus $CPUS --memory $RAM --name eessi ./eessi.yaml
+limactl list
+```

docs/getting_access/eessi_wsl.md

@@ -0,0 +1,126 @@
+# Installing EESSI with Windows Subsystem for Linux
+
+## Basic commands with WSL
+
+### List the available linux distributions for installation
+
+```
+C:/users/user>wsl --list --online
+The following is a list of valid distributions that can be installed.
+Install using 'wsl.exe --install <Distro>'.
+
+NAME                                   FRIENDLY NAME
+Ubuntu                                 Ubuntu
+Debian                                 Debian GNU/Linux
+kali-linux                             Kali Linux Rolling
+Ubuntu-18.04                           Ubuntu 18.04 LTS
+Ubuntu-20.04                           Ubuntu 20.04 LTS
+Ubuntu-22.04                           Ubuntu 22.04 LTS
+Ubuntu-24.04                           Ubuntu 24.04 LTS
+OracleLinux_7_9                        Oracle Linux 7.9
+OracleLinux_8_7                        Oracle Linux 8.7
+OracleLinux_9_1                        Oracle Linux 9.1
+openSUSE-Leap-15.5                     openSUSE Leap 15.5
+SUSE-Linux-Enterprise-Server-15-SP4    SUSE Linux Enterprise Server 15 SP4
+SUSE-Linux-Enterprise-15-SP5           SUSE Linux Enterprise 15 SP5
+openSUSE-Tumbleweed                    openSUSE Tumbleweed
+```
+
+### List the installed machines
+
+```
+C:/users/user>wsl --list --verbose
+  NAME      STATE           VERSION
+* Debian    Stopped         2
+```
+
+### Reconnecting to a Virtual machine with wsl
+
+```
+C:/users/user>wsl --distribution Debian
+user@id:~$
+```
+
+For more documentation on using WSL you can check out the following pages:
+
+* [Install WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
+
+* [Basic commands for WSL](https://learn.microsoft.com/en-us/windows/wsl/basic-commands)
+
+## Installing a linux distribution with WSL
+
+```
+C:/users/user>wsl --install --distribution Debian
+Debian GNU/Linux is already installed.
+Launching Debian GNU/Linux...
+Installing, this may take a few minutes...
+Please create a default UNIX user account. The username does not need to match your Windows username.
+For more information visit: https://aka.ms/wslusers
+Enter new UNIX username: user
+New password:
+Retype new password:
+passwd: password updated successfully
+Installation successful!
+```
+
+## Installing EESSI in the virtual machine
+
+``` { .bash .copy }
+# Installation commands for Debian-based distros like Ubuntu, ...
+
+# install CernVM-FS
+sudo apt-get install lsb-release
+sudo apt-get install wget
+wget https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
+sudo dpkg -i cvmfs-release-latest_all.deb
+rm -f cvmfs-release-latest_all.deb
+sudo apt-get update
+sudo apt-get install -y cvmfs
+
+# install EESSI configuration for CernVM-FS
+wget https://github.com/EESSI/filesystem-layer/releases/download/latest/cvmfs-config-eessi_latest_all.deb
+sudo dpkg -i cvmfs-config-eessi_latest_all.deb
+
+# create client configuration file for CernVM-FS (no squid proxy, 10GB local CernVM-FS client cache)
+sudo bash -c "echo 'CVMFS_CLIENT_PROFILE="single"' > /etc/cvmfs/default.local"
+sudo bash -c "echo 'CVMFS_QUOTA_LIMIT=10000' >> /etc/cvmfs/default.local"
+
+# make sure that EESSI CernVM-FS repository is accessible
+sudo cvmfs_config setup
+```
+
+## Start cernVM-FS in Windows Subsystem for Linux
+
+When the virtual machine is restarted CernVM-FS needs to be remounted with following command.
+
+``` { .bash .copy }
+# start CernVM-FS on WSL
+sudo cvmfs_config wsl2_start
+```
+
+If you do not wish to do this you can set up the automounter. Examples are available [here](https://klust.github.io/windows-client-HPC/4_Cluster_Stack/4_01_EESSI/#example-setup-on-fedora-remix-in-wsl2).
+
+EESSI should now be available in the virtual machine
+
+```
+user@id:~$ source /cvmfs/software.eessi.io/versions/2023.06/init/bash
+  Found EESSI repo @ /cvmfs/software.eessi.io/versions/2023.06!
+  archdetect says x86_64/intel/haswell
+  Using x86_64/intel/haswell as software subdirectory.
+  Found Lmod configuration file at /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/.lmod/lmodrc.lua
+  Found Lmod SitePackage.lua file at /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/.lmod/SitePackage.lua
+  Using /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/modules/all as the directory to be added to MODULEPATH.
+  Using /cvmfs/software.eessi.io/host_injections/2023.06/software/linux/x86_64/intel/haswell/modules/all as the site extension directory to be added to MODULEPATH.
+  Initializing Lmod...
+  Prepending /cvmfs/software.eessi.io/versions/2023.06/software/linux/x86_64/intel/haswell/modules/all to $MODULEPATH...
+  Prepending site path /cvmfs/software.eessi.io/host_injections/2023.06/software/linux/x86_64/intel/haswell/modules/all to $MODULEPATH...
+  Environment set up to use EESSI (2023.06), have fun!
+```
+
+## Cleanup of the virtual machine
+
+```
+C:/users/user>wsl --terminate Debian
+C:/users/user>wsl --unregister Debian
+```
+

mkdocs.yml

@@ -26,6 +26,9 @@ nav:
     - Is EESSI already installed?: getting_access/is_eessi_accessible.md
     - Native: getting_access/native_installation.md
     - Container: getting_access/eessi_container.md
+    - Virtual machine on Windows and macOS:
+      - Windows with WSL: getting_access/eessi_wsl.md
+      - macOS with Lima: getting_access/eessi_limactl.md
   - Basic usage:
     - Set up environment: using_eessi/setting_up_environment.md
     - Basic commands: using_eessi/basic_commands.md