# Setup

In this document we use the names *Apptainer* and *Singularity* interchangeably. See the [Introduction](01-introduction.md)
for more details about existing Apptainer and Singularity versions and the differences between them.

## Option 1: Use pre-installed apptainer on a cluster

Apptainer/Singularity has become popular and usually it is available in the institutional computing resources.
Check if apptainer or singularity are available with
```bash
apptainer --version
singularity --version
```
If installed, you will see `apptainer version ...` or `singularity version ...`, depending on the flavor installed.
Apptainer is preferable but either one is OK, so if apptainer is there, no need to check for singularity (which most likely will be a link to apptainer).
This tutorial requires at least Apptainer 1.0.x or Singularity 3.5.x. Previous versions may not have all the required features.
If none is in your [`$PATH`](https://www.makeuseof.com/set-path-variable-in-linux/#what-is-path-in-linux) or if the available version is too old,
you may still be able to use an updated apptainer via [CVMFS](https://cernvm.cern.ch/fs/): check if you have user namespaces enabled and CVMFS to run singularity that way:
```bash
[[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && ls /cvmfs/oasis.opensciencegrid.org/mis/ &>/dev/null && { export PATH=/cvmfs/oasis.opensciencegrid.org/mis/apptainer/bin/:"$PATH"; echo "Success: Added to PATH"; singularity --version; } || echo "Failure: Unable to run Apptainer/Singularity via CVMFS"
```
If this works, it will be added to your path and you will see your apptainer/singularity version.

If your local computing system does not have Apptainer/Singularity installed, you may
[request it to your system administrator as suggested here](https://apptainer.org/docs/user/main/quick_start.html#apptainer-on-a-shared-resource).

## Option 2: Install Apptainer/Singularity

You will need a **Linux system** to run Apptainer/Singularity natively.
If you have Linux, go to the Linux install instructions below.

On Windows you can use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/about).
You can run a Linux system on your Windows computer. We recommend [AlmaLinux9](https://wiki.almalinux.org/documentation/wsl.html).
Then follow the Linux instructions to install Apptainer as root.

On macOS you also need a Linux VM to be able to use Apptainer.
There are different solutions; here we describe how to use [Lima](https://lima-vm.io/).

### Install on a Mac
To avoid architecture problems we recommend using an x86\_64 VM also on ARM Macs.
It will be less performant but you'll avoid architecture errors when images are available only for x86\_64.
To do so you can use [QEMU](https://www.qemu.org/) and [Lima](https://lima-vm.io/) via [Homebrew](https://brew.sh/).

1. Install QEMU and Lima via Homebrew:

    ```bash
    # Install Homebrew if you don't have it already
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    # Install QEMU and Lima
    brew install qemu lima
    ```

2. Prepare an x86\_64 VM. Here we use an Ubuntu image:

    ```bash
    # Prepare the VM configuration file
    cat > ubuntu-x86_64.yaml << EOF
    arch: "x86_64"
    images:
      - location: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img"
        arch: "x86_64"
      - location: "https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-arm64.img"
        arch: "aarch64"
    # Disable mounts and containerd, otherwise booting up may time out if the host is slow
    mounts: []
    containerd:
      system: false
      user: false
    EOF
    # Create and start the VM
    limactl start ubuntu-x86_64.yaml --name=ubuntu
    limactl shell ubuntu
    ```

3. In the VM install and use apptainer:

    ```bash
    sudo add-apt-repository -y ppa:apptainer/ppa
    sudo apt install -y apptainer
    # Check your Apptainer version
    apptainer --version
    # You can exit the VM with Ctrl+D (exit)
    ```


Now you're ready to use Apptainer on your Mac. To use Apptainer (and all commands in this tutorial) you have to first
enter your VM with `limactl shell ubuntu` and when you are done you can go back to the Mac shell using `exit` (Ctrl+d).
If you reboot your Mac you may have to restart the VM with `limactl start ubuntu`.
For more commands to control and configure the Lima VM you can check [Lima's documentation](https://lima-vm.io/docs/).

### On Linux, If you have root access

It is easiest to
[install if you have root access](https://apptainer.org/docs/user/main/quick_start.html#quick-installation).

### On Linux, If not

If the above is not possible and you cannot use the CVMFS distribution you still have an option if user namespaces are enabled on your system:
1. Check if user namespaces are enabled:

    ```bash
    # on Debian/Ubuntu
    grep -q 'kernel.unprivileged_userns_clone=1' /etc/sysctl.d/90-unprivileged_userns.conf && \
        echo "User namespaces enabled, continue the Apptainer installation" || \
        echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
    # on RHEL/CentOS check that /proc/sys/user/max_user_namespaces is bigger than 0
    [[ $(cat /proc/sys/user/max_user_namespaces) -gt 0 ]] && \
        echo "User namespaces enabled, continue the Apptainer installation" || \
        echo "User namespaces NOT enabled, your use of Apptainer will be very limited"
    ```

   See [these full instructions](https://apptainer.org/docs/admin/main/user_namespace.html#user-namespace-requirements) for more about checking for and enabling user namespaces.
1. If enabled, install unprivileged Apptainer with one of these three methods (in order of preference):
    1. Choose your `INSTALL_DIR` and [install there the relocatable Apptainer (recommended)](https://apptainer.org/docs/admin/main/installation.html#install-unprivileged-from-pre-built-binaries). Run:

        ```bash
        curl -s https://raw.githubusercontent.com/apptainer/apptainer/main/tools/install-unprivileged.sh | \
            bash -s - INSTALL_DIR
        ```

    1. Alternatively [install from source without root privileges](https://github.com/apptainer/apptainer/blob/main/INSTALL.md).
    1. Or use [cvmfsexec](https://github.com/cvmfs/cvmfsexec) to get CVMFS. This is a bit more complex, you can follow the instructions summarized also in
[this paper](https://indico.cern.ch/event/885212/contributions/4120683/attachments/2181040/3684201/CernVMWorkshopCvmfsExec20210201.pdf).

If user namespaces are not enabled, apptainer/singularity is not installed, and you have no root access to the host, then your use of apptainer/singularity will be very limited even if you install it with one of the three methods above. You need to request to your system administrator to either [install Apptainer/Singularity](https://apptainer.org/docs/user/main/quick_start.html#apptainer-on-a-shared-resource) or to enable [user namespaces](https://apptainer.org/docs/admin/main/user_namespace.html).