Build containers
================

The standard SingularityCE_ way to build ``.sif``
containers is from ``.def`` `definition files`_.

Definition file
---------------

Rat-Containers_ contains several `SingularityCE Definition
Files`_ available on GitLab at `rat-containers/singularityCE`_.

These files follow a general structure:

.. code-block:: singularity
    :caption: ``example.def``

    # Header section
    # To boostrap from local image, first run:
    #   singularity pull <agent>://<provider>/<name>.sif
    # and point to this image with the following header.
    Bootstrap: localimage
    From: ./<name>.sif
    # Otherwise to use provider directly:
    # Bootstrap: <agent>
    # From: <provider>/<name>.sif

    # Commands to run post creation of the OS in container
    %post

        # Common steps are:
        # 1. Update package manager and packages
        apt-get update

        # 2. Install dependencies and setup environment
        apt-get install -y xeyes

        # 3. Build desired packages
        make stuff-up

        # 4. Clean-up
        rm -rf cache

    # Scripts to run for `singularity run <container> [<args>]`
    # Will be used to print info and exit in Rat-Containers cases
    %runscript
        
        # Script to run, if needed
        echo "Cycling..."

    # Metadata: printed by `singularity inspect <container>`
    %labels

        # Key value pairs defining labels, parsed as:
        <attribute> <value>

        # e.g.
        author vacuuous.rom@byrg.com
        program.version 1.0.0

    # Help: printed by `singularity run-help <container>`
    # Raw text to print to the console
    %help
    SingularityCE Definition File structure example

    Check out Rat-Containers on GitLab:
    https://gitlab.com/project-rat-extras/rat-containers

Build command
-------------

These files can then be used to build containers like so:

.. code-block:: bash

    sudo singularity build --force <container>.sif <definition_file>.def

.. note::

    The ``--force`` flag overwrite labels and metadata
    from previous images if bootstrapped from them.

Chaining images
---------------

Building containers from scratch can get quite cumbersome iterations
after iterations. Moreover one might need to acquire a custom base
image to bootstrap from for different containers.

One solution to this is "chaining images":

- Bootstrap from online base image of interest
  (e.g. Rocky Linux 8 with CUDA) to generate
  local image with complete desired environment.

- Bootstrap from generated local
  image and so on and so forth.

.. note::

    The `rat-containers/singularityCE`_ directory contains chained images
    for Project-Rat_ and for pyRat_. One could of course "flatten" the
    recipes in order to have a full self contained definition file for
    their container instead of building each one of them incrementally.

.. Links
.. _Docker: https://www.docker.com/
.. _Docs: https://gitlab.com/project-rat-extras/docs
.. _Nix: https://en.wikipedia.org/wiki/Nix_(package_manager)
.. _Project-Rat: https://gitlab.com/project-rat
.. _PRE Docs: https://gitlab.com/project-rat-extras/docs
.. _pyRat: https://gitlab.com/project-rat-extras/pyrat
.. _Rat-Docs: https://gitlab.com/project-rat/rat-documentation
.. _Rat-Containers: https://gitlab.com/project-rat-extras/rat-containers
.. _rat-containers/singularityCE: https://gitlab.com/project-rat-extras/rat-containers/-/blob/main/singularityCE/
.. _Rat-vcpkg: https://gitlab.com/project-rat-extras/rat-vcpkg
.. _Singularity: https://sylabs.io/singularity/
.. _SingularityCE: https://sylabs.io/singularity/
.. _SingularityCE definition files: https://docs.sylabs.io/guides/4.4/user-guide/definition_files.html
.. _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