Since there is a pressing need for the use of containers in a specific way, this document will begin limited to that specific context, and then branch from there.

Docker is a fine virtual abstraction system, however it requires administrator privileges to run.

Further, once an image is running, Docker's default preference is to have input and output resources relevant to the container _within_ the container itself.

[Singularity](https://en.wikipedia.org/wiki/Apptainer) overcomes these two issues by running images as the user envoking them, and then exposing the local filesystem on the host from within the running container.

More detailed information can be found [here](https://sylabs.io/guides/3.3/user-guide/quick_start.html#overview-of-the-singularity-interface).

In this contextual need, we would like to be able to run [Tensorflow](https://www.tensorflow.org/learn).

Singularity will allow us to obtain an existing container from a Singularity Container Library, a Singularity Hub, or a Docker Hub. In this particular case of Tensorflow, we'll download one of NVidia's premade Docker containers, which Singularity will convert into its own format.

First, we need to obtain access to NVidia's library of Docker containers, located here:

[Nvidia NGC](https://ngc.nvidia.com/catalog/containers)

This is initially done by requesting access through the [Create Account](https://ngc.nvidia.com/signup) link.

Once an account is granted, the [API key](https://ngc.nvidia.com/setup/api-key) is needed.

Once the API key is obtained, set it usable in the shell:

Now you may log into the Nvidia NGC and browse for containers.

In this example, we'll download [Tensorflow](https://ngc.nvidia.com/catalog/containers/nvidia:tensorflow).

There, it lists the container as:

By default, singularity will write the entire container into your home directory and then the container will be specific to your account, hidden, and available only to you.

To avoid that, we'll write it to a file instead, in Singularity Image Format (SIF).

So, for singularity, we will *pull* the image as such:

Singularity will then download each blob-layer in the `tensorflow:19.09-py3` tag, and cache it into your home directory.

Now our container file is complete:

Before we move on, note that singularity also stored the SIF file in the user's cache, in the home directory (there is now a 3.3G file there, with overhead).

You can view what is stored in the cache:

Clearing the cache is equally simple.

Removes all images in the cache (with the -a parameter).

By default, Singularity caches pulled files in your homedirectory with a structure as:

One can change the default location of the cache by setting `SINGULARITY_CACHEDIR` to your desired location, for example (in bash shell):

Now lets say we built this image but discovered it is lacking software that we need.

We have a few options at this point, depending on how permanent we would like the software to be.

One solution would be to build a new image from the image we pulled and built locally (above).

For updated detailed information, refer to https://docs.sylabs.io/guides/latest/user-guide/build_a_container.html.

To run the container we just built, we need to decide how we would like to execute it.

We can *exec* on the container, which will run a command inside the container:

This will execute any command from within the container, and then immediately exit.

We can also obtain a *shell* within the container:

Notice that the current working directory is `/tmp`, which is not inside the container.

When Singularity executes, it attempts to make available all your existing filespaces, such as your homedirectory, and any common directories existing on the physical host (such as `/tmp`).

Only the files and directories inside the container are exposed over the filespace of the physical host. This makes it rather easy to write any output from the container to the local filesystem, or to an NFS mounted homedirectory.

Now that we're interactively running the container, we can attempt to execute Tensorflow.

Uh oh. The container couldn't locate the CUDA library necessary to execute the Tensorflow Python module in the container.

This is because when the singularity shell was launched, it was not made aware of any NVidia software, and did not map any NVidia drivers/devices into the container.

This is easily remedied with the _--nv_ parameter.

Now, we have built a container from NVidia, and demonstrated it as working, *can someone else use our container*?

_Yes_, as long as you don't need to write anything into the container space, because the container will be mounted __read-only__ by default.

This is likely expected behavior, as it seems undesirable to create a container that allows anyone to write files, creating unforeseen entropy into the otherwise pristine container.

Regarding our example Tensorflow container above, it remains usable as __read-only__ since we are not modifying the binaries/scripts involved in running Tensorflow itself, and any data input or output can live safely and be accessed outside the container.

Consider the following example:

We have a very simple (example) Python script:

That is in the current directory with our Tensorflow container:

We can use our `helloworld.py` script like so:

Likewise, redirecting output as:

Then our `OUTPUT` file will be:

So far, we have run our container with `shell` or `exec` which runs the container in the foreground, meaning the running container terminates when we exit, either by quitting from the `shell` or by the end of execution from `exec`.

We can, however, _detach_ a container and run it as a "service".

In Singularity terms, this is called an *instance*.

Now the instance is running, and we can launch however many as we like, though each instance needs a unique name.

To review what instances we have running:

Now, to access (or "attach") to the running instances, we can use `exec` or `shell` as before, but target the _instance_ like so:

Finally, to terminate our instances:

Or: