Apptainer (Singularity)
+++++++++++++++++++++++

Apptainer (formerly: Singularity) is a secure, HPC-friendly alternative to :doc:`Docker </common/containers/docker>`. 

Apptainer has its own container image format, but is generally compatible with Docker images.
 
Basic usage
+++++++++++
The Apptainer user guide may be found at https://apptainer.org/docs/user/main/ , which explains, amongst other things, how to pull down Docker images from public repositories (such as Dockerhub) and make them work with Apptainer. :ref:`Let us know<Support>` if you need any help with this. 

On the Research Cluster and other RTIS-managed shared servers, pre-existing shared Apptainer images (.sif) are generally located at :code:`$APPTAINER_IMG`. 

For convenience, shared Apptainer images may have been wrapped in a **modulefile** that will create the necessary aliases to the relevant in-container binaries, so after loading the module these binaries can then be invoked as per usual. e.g.:

.. code-block:: bash

        module avail foo
        module load apptainer/foo/0.1
        foo_bin -v
        
where :code:`foo_bin` will actually be an alias to `apptainer run $APPTAINER_IMG/foo_0.1.sif foo_bin`. 
Run :code:`alias` to display a list of all defined aliases in your shell

To use these aliases in a non-interactive script or via SLURM, add the following in your script before using the alias:

.. code-block:: bash

    shopt -s expand_aliases

Available .sif images can also be run as an executable; 
i.e.: to start a container with the default run command:  :code:`$APPTAINER_IMG/<image.sif>`
(which is identical to: :code:`apptainer run $APPTAINER_IMG/<image.sif>`)
or alternatively add a custom command to run: :code:`$APPTAINER_IMG/<image.sif> <command in the container>` 
or to start an interactive shell in the container: :code:`apptainer shell $APPTAINER_IMG/<image.sif>` 


Bind mounts
^^^^^^^^^^^
Your :code:`$HOME` directory, :code:`/scratch`, and :code:`/projects` will be available within the Apptainer container by default.
Other directories/files on the host filesystem will be inaccessible from within the container, unless explicitely mounted into the container (similar to Docker's volumes). 

If you need access to other arbitrary filesystem paths, specify these with the :code:`--bind`/:code:`-B` option 
e.g. To start the :code:`foo.sif` container with the host directory :code:`/some/host_path/test` mounted on :code:`/tmp/test` within the container:

.. code-block:: bash
    
    apptainer run --bind /some/host_path/test:/tmp/test $APPTAINER_IMG/foo.sif

Refer to https://apptainer.org/docs/user/main/bind_paths_and_mounts.html#user-defined-bind-paths for additional information and examples.
 

GUI applications
^^^^^^^^^^^^^^^^
GUI applications in an Apptainer container can be remotely started from within a graphical environment (e.g. OnDemand, :doc:`X2Go </common/x2go>`, :doc:`FastX </common/fastx>`, X11-forwarded SSH session).


GUI applications with 3D acceleration (OpenGL)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This requires 

* an execution host with GPU(s) set up with NVIDIA drivers
* a specially crafted Apptainer container image containing the necessary libraries and settings for OpenGL and VirtualGL
* the Apptainer image ran with the :code:`--nv` flag
* a Virtual-GL capable VNC client (such as the OnDemand noVNC browser client on the Research Cluster, or a native client supporting VirtualGL (TurboVNC, TigerVNC))


CUDA (GPU compute) support
^^^^^^^^^^^^^^^^^^^^^^^^^^
If the node/server has NVIDIA GPU cores available, starting the Apptainer container with the :code:`--nv` flag will setup the container’s environment to use the NVIDIA GPU and the basic CUDA libraries to run a CUDA enabled application.