Put singularity download instructions in the documentation

[zohimchandani]

Required prerequisites

• Search the issue tracker to check if your feature has already been mentioned or rejected in other issues.

Describe the feature

Most HPC centres use singularity or apptainer and not docker.

One can convert docker containers to the ones mentioned above.

Can we please have instructions on how to do this in the documentation?

Thanks team.

[oryarnitzky-classiq]

We used Apptainer for the QAL workshop, so we can share our experience here. As mentioned in the issue, Apptainer can convert docker images to Apptainer images, but we did encounter few obstacles during this experience which are worth noting:

First, creating and running the image - This is the command I used to generate the Apptainer image from the docker image:

apptainer build --fakeroot <path to image> docker://<url to image at registry>

• The fakeroot argument was recommended in some page they had in SURF’s confluence (the organizers of the QAL workshop), but I’m not entirely sure what is its purpose
• The created image’s architecture (e.g arm64, x86_64) matches the architecture of the docker image, so keep that in mind when creating an image on, e.g., an M1 computer and trying to run it on an Intel computer..

This is the command I used to run the image on SURF’s host:

apptainer shell --nv --no-mount hostfs <path to image>

• The --nv argument allows Apptainer to access Nvidia’s GPUs
• The --no-mount hostfs prevents Apptainer from mounting the host’s filesystem inside the container. This is important for the cuda-quantum docker image because most of the binaries are installed at /opt, which is overriden by default.

Another obstacle when setting up the workshop was remote work (using SSH) on the Apptainer, which is also likely to be a common necessity when working with HPCs.

To run the Apptainer in VSCode’s Remote Shell, I changed the following settings:

  "remote.SSH.enableRemoteCommand": true,
  "remote.SSH.useLocalServer": true,
  "remote.SSH.serverInstallPath": {
        "<host name>": "<some path for the server directory (e.g. ~/.vscode-container/my_apptainer)>" 
    }

• I’ll admit I’m not entirely sure why useLocalServer is explicitly there because true seems to be the default, and actually false may be better (see below)
• enableRemoteCommandallows to use RemoteCommand in the SSH config
• Having a custom path for the remote server will prevent conflicts with a remote server outside of the Apptainer.

Then, I added the following to the SSH config file

Host <host name>
  RemoteCommand kill -9 $(pgrep -U $UID -f vscode | grep -v  ^$$\$); apptainer shell --nv --no-mount hostfs --writable-tmpfs <path to image>
  RequestTTY yes

• The first part of the command (kill ...) kills older VSCode processes on the machine. This seemed to improve my experience when disconnecting and reconnecting to the same apptainer. This may be related to the fact that useLocalServer is true, and maybe setting it to false would’ve allowed to avoid it.
• The --writable-tmpfs seems to help VSCode to run, it seems to create a bunch of temporary files while running