.. include:: ../substitutions.txt

*************************************
Introduction to Apptainer
*************************************

.. include:: ../site_snippets/apptainer_prereqs.txt

At face value, Apptainer is an alternative container implementation to Docker that has an overlapping set of features but some key differences as well.  Apptainer is commonly available on shared clusters, such as |site|'s HPC systems, because the Docker runtime is not secure on systems where users are not allowed to have "escalated privileges".  Importantly, the Apptainer runtime is compatible with Docker containers!  So in general, we follow the practice of using Docker to develop containers and using Apptainer simply as a runtime to execute containers on HPC systems.

If you are familiar with Docker, Apptainer will feel familiar.


Login to |machine|
==================

For today's training, we will use the |machine| supercomputer.  To login, you need to establish a SSH connection from your laptop to the |machine| system.  |logininstructionslink|_

When you have successfully logged in, you should be greeted with some welcome text and a command prompt.


.. include:: ../site_snippets/apptainer_start.txt


Load the Apptainer Module
===============================

.. include:: ../site_snippets/apptainer_load_module.txt

Core Apptainer Commands
=============================


Pull a Docker container
-----------------------

Containers in the Docker registry may be downloaded and used, assuming the underlying architecture (e.g. x86) is the same between the container and the host.

Create a new directory, then pull a container.

.. code-block:: console

    $ cd
    $ mkdir apptainer
    $ cd apptainer
    $ apptainer pull docker://godlovedc/lolcow
    INFO:    Converting OCI blobs to SIF format
    WARNING: 'nodev' mount option set on /run/user/441890, it could be a source of failure during build process
    INFO:    Starting build...
    Getting image source signatures
    Copying blob 8e860504ff1e done  
    Copying blob d010c8cf75d7 done
    ... # output ommitted
    INFO:    Creating SIF file...
    $ ls
    lolcow_latest.sif

There may be some warning messages, but this command should download the latest version of the "lolcow" container and save it in your current working directory as ``lolcow_latest.sif``.


Interactive shell
-----------------

The ``shell`` command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.

.. code-block:: console

	$ apptainer shell lolcow_latest.sif

	Apptainer>

The change in prompt indicates that you have entered the container (though you should not rely on that to determine whether you are in container or not).

Once inside of an Apptainer container, you are the same user as you are on the host system.  Also, a number of host directories are mounted by default.

.. code-block:: bash

	Apptainer> whoami

	Apptainer> id

	Apptainer> pwd

	Apptainer> exit


.. Note::

	Docker and Apptainer have very different conventions around how host directories are mounted within the container. In many ways, Apptainer has a simpler process for working with data on the host, but it is also more prone to inadvertantly having host configurations "leak" into the container.


Run a container's default command
-------------------------------------

Just like with Docker, Apptainer can run the default "entrypoint" or default command of a container with the ``run`` subcommand.  These defaults are defined in the Dockerfile (or Apptainer Definition file) that define the actions a container should perform when someone runs it.

.. code-block:: console

	$ apptainer run lolcow_latest.sif

     ________________________________________
    < The time is right to make new friends. >
     ----------------------------------------
            \   ^__^
             \  (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||


.. Note::

    You may receive a warning about "Setting locale failed".  This is because, by default, Apptainer sets all shell environment variables inside the container to match whatever is on the host.  To override this behavior, add the ``--cleanenv`` argument to your command.


Executing arbitrary commands
----------------------------

The exec command allows you to execute a custom command within a container. For instance, to execute the ``cowsay`` program within the lolcow_latest.sif container:

.. code-block:: console

	$ apptainer exec --cleanenv lolcow_latest.sif cowsay Apptainer runs Docker containers on HPC systems
     _______________________________________
    / Apptainer runs Docker containers on \
    \ HPC systems                           /
     ---------------------------------------
            \   ^__^
             \  (oo)\_______
                (__)\       )\/\
                    ||----w |
                    ||     ||

.. Note::

	``exec`` also works with the library://, docker://, and shub:// URIs. This creates an ephemeral container that executes a command and disappears.

Once you are finished with your interactive session, you can end it and return to the login node with the exit command:

.. code-block:: console

	$ exit