SingularityCE
=============

SingularityCE_ (formerly Singularity) is the standard
option for HPC platforms given its non ``sudo``
requirements to run code on nodes unlike Docker_.

Such privileges are however required at build time.

.. topic:: Singularity VS SingularityCE_ VS Apptainer_

    Singularity was the original open-source project created for
    scientific/HPC environments allowing to run containers without
    requiring root privileges.

    Governance changed in 2021 and the project split into two parts:

    - SingularityCE_ (Community Edition) fork:
        - Maintained by Sylabs, founded by the original creator
        - Sylabs-led

    - Apptainer_ fork:
        - Maintained by Linux foundation
        - Community-led

    Apptainer_ remains the most *Linux* part given its
    community-governed aspect and thus most distributions 
    standardized it instead of SingularityCE_. It is therefore
    straightforward to install compared to its Sylabs counterpart.

    Both projects remain very similar for now but they might
    slowly drift away from each other as times goes since
    they prioritize different aspects in their codebases.

    **One should be able to interchange the CLI commands without
    noticable differences for now** but this might change in the future.

.. important::

    The documentation will emphasize on SingularityCE_ since
    it is the standard HPC module installed at CEA, Saclay.
    
    It should however also work with Apptainer_
    containers but has not been tested.

SingularityCE_ allows to build Linux-based containers ``.sif`` from
`SingularityCE Definition Files`_ ``.def``. These definition files
are very similar to Docker_'s ``Dockerfiles`` but in a more
transparent manner with explicit shell scripts running at build time.

This build method ensures the most repdroducible containers.
Other sandbox methods are also available, but less reliable
when it comes to defining build consistent build environments.

Most container images are based on:

- a Linux distribution (e.g. Ubuntu, CentOS, Rocky, ...),
- some more base environment (e.g. Python, CUDA, Qt, ...).

SingularityCE_ containers and images can of course be
based of (or rather bootstrapped from) Docker_ images.
See `SingularityCE preferred bootstrap agents`_.
For instance the ``rocky-cuda.def`` recipe defines a
Rocky Linux 8 container from a Docker_ NVIDIA CUDA
development image: ``cuda_11.5.2-devel-rockylinux8``.
It is then possible to chain different images
for a more broad and modular approach.

Follow the subsections below to get started using SingularityCE_:

.. Rat-Containers: Singularity table of contents
.. toctree::
   :maxdepth: 2
   :caption: SINGULARITY COMMUNITY EDITION CONTENTS

   install
   build_containers
   build_examples
   use_containers
   use_examples

.. Links
.. _Apptainer: https://apptainer.org/
.. _Docker: https://www.docker.com/
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers
.. _rat-containers/singularity: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/singularity/
.. _SingularityCE: https://sylabs.io/singularity/
.. _SingularityCE definition files: https://docs.sylabs.io/guides/4.4/user-guide/definition_files.html
.. _SingularityCE preferred bootstrap agents: https://docs.sylabs.io/guides/4.3/user-guide/definition_files.html#preferred-bootstrap-agents