Singularity Container Documentation, Release 3.5
2.4.9 Best Practices
Singularity can make use of most Docker and OCI images without complication. However, there exist known cases
where complications can arise. Thus a brief compilation of best practices follows below.
1. Accounting for trust
Docker containers allow for privilege escalation. In a Dockerfile, for example, the USER instruction
allows for user and/or group settings to be made in the Linux operating environment. The trust model
in Singularity is completely different: Singularity allows untrusted users to run untrusted containers in
a trusted way. Because Singularity containers embodied as SIF files execute in user space, there is no
possibility for privilege escalation. In other words, those familiar with Docker, should not expect access
to elevated user permissions; and as a corollary, use of the USER instruction must be avoided.
Singularity does, however, allow for fine-grained control over the permissions that containers require for
execution. Given that Singularilty executes in user space, it is not surprising that permissions need to be
externally established for the container through use of the capability command. Detailed elsewhere in
this documentation, Singularity allows users and/or groups to be granted/revoked authorized capabilties.
Owing to Singularity’s trust model, this fundamental best practice can be stated as follows:
“Employ singularity capability to manage execution privileges for containers”
2. Maintaining containers built from Docker and OCI images
SIF files created by boostrapping from Docker or OCI images are, of course, only as current as the most
recent Singularity pull. Subsequent retrievals may result in containers that are built and/or behave dif-
ferently, owing to changes in the corresponding Dockerfile. A prudent practice then, for maintaining
containers of value, is based upon use of Singularity definition files. Styled and implemented after a
Dockerfile retrieved at some point in time, use of diff on subsequent versions of this same file, can
be employed to inform maintenance of the corresponding Singularity definition file. Understanding build
specifications at this level of detail places container creators in a much more sensible position prior to
signing with an encrypted key. Thus the best practice is:
“Maintain detailed build specifications for containers, rather than opaque runtimes”
3. Working with environment variables
In a Dockerfile, environment variables are declared as key-value pairs through use of the ENV instruction.
Declaration in the build specification for a container is advised, rather than relying upon user (e.g., .
bashrc, .profile) or system-wide configuration files for interactive shells. Should a Dockerfile be
converted into a definition file for Singularity, as suggested in the container-maintenance best practice
above, environment variables can be explicitly represented as ENV instructions that have been converted
into entries in the %environment section, respectively. This best practice can be stated as follows:
“Define environment variables in container specifications, not interactive shells”
4. Installation to /root
Docker and OCI container’s are typically run as the root user; therefore, /root (this user’s $HOME direc-
tory) will be the installation target when $HOME is specified. Installation to /root may prove workable
in some circumstances - e.g., while the container is executing, or if read-only access is required to this
directory after installation. In general, however, because this is the root directory conventional wisdom
suggests this practice be avoided. Thus the best practice is:
“Avoid installations that make use of /root.”
5. Read-only / filesystem
Singularity mounts a container’s / filesystem in read-only mode. To ensure a Docker container meets
Singularity’s requirements, it may prove useful to execute docker run --read-only --tmpfs /run
--tmpfs /tmp godlovedc/lolcow. The best practioce here is:
2.4. Support for Docker and OCI 75