The topics in this tutorial are experimental. We are working on improving support for rootless containers, but for now, some things may not be compatible.
In some situations using Docker may be impractical because it requires all users to have root access. Several alternatives have been developed to make it possible to run rootless containers, including Singularity and rootless Docker. While Dockstore uses Docker by default, if necessary it may be possible to run your workflows with one of these alternatives. Because the call to Docker or an alternative is made by the workflow runner, usually cwltool or Cromwell, and not Dockstore directly, the difficulty of configuring a Docker alternative depends on the workflow type. Some Dockstore entries will run seamlessly without Docker, and some may be entirely incompatible in a rootless environment.
Experiments with a version of Docker that does not require root permissions have been proposed and experimented with for a while now. In December 2020 with the release of Docker Engine v20.10, “rootless Docker” has officially become part of Docker itself. While this does open the door for some systems, it does require special setup and it has some limitations. You can read all about it on Docker’s own docs about Rootless Mode.
Singularity is perhaps the most well-supported Docker alternative. Singularity can pull Docker images and build them
into its own image format (.sif), but not all Docker features are compatible. For instance, dockerfile
commands are not compatible with Singularity.
A common problem observed when running Dockstore entries with Singularity is that the process fails on
singularity pull because the entry’s dockerfile or its base image contains a
USER root command. In many cases
the use of root may be unnecessary. Whenever possible, dockerfiles on Dockstore should avoid using root.
A best practice when using Docker for workflows is not to rely on a specific user. This is doubly true for Singularity where it is not just best practice but necessary.
Singularity provides a fake root option that might circumvent the problems using root in certain situations. There does not seem to be a way to use this option through cwltool. It can be used with Cromwell by editing the Singularity command format set in your Cromwell config file.
More information about compatibility of dockerfiles with Singularity can be found here.
Singularity can be installed following the instructions
here. Note that the installation is relatively complicated
sudo. Neither the macOS version (Singularity Desktop) nor the Debian/Ubuntu package version currently
available (2.6.1) is compatible. You will need to download a version >3.0.0 and build it from source.
Singularity is available as a command line option for cwltool like this:
cwltool --singularity <workflow> <input json>
To set this option through Dockstore, add the following line to your
Cromwell can be configured to use Singularity instead of Docker as described here. This requires creating a Cromwell config file with a section describing the backend provider settings. Examples of this are available in the Cromwell GitHub here.
To tell Dockstore to run Cromwell with a custom configuration, such as the example config file linked above,
add a line to your
cromwell-vm-options: -Dconfig.file=<absolute path to your Cromwell conf>
Rootless Docker, a product of Docker, is very convenient because no configuration of Dockstore is required to use it.
When it is installed, all
docker commands are run in rootless mode without needing to set this as an option.
Therefore, the normal Docker commands invoked by cwltool and Cromwell will be executed rootlessly.
Rootless Docker installation is simple and does not require root. Regular Docker must not already be installed. Just execute the installation script:
curl -sSL https://get.docker.com/rootless | sh
It may display a message that you need to add it to the PATH or do some other configuration.
You can confirm that rootless Docker is working with
Security Options it should output
support for some Docker alternatives but does not mention rootless Docker. In our testing, it seems the
command issued by cwltool is incompatible with rootless Docker and causes a permissions error with the volume mapping.
cwltool with rootless Docker did not work for any tested workflows.
As rootless Docker does not require any change of configuration to use, it can be used with Cromwell through Dockstore despite the lack of a Cromwell config option.
Cromwell does not document support for rootless Docker, but they seem to be compatible. Most WDL workflows we tried worked smoothly with rootless Docker.
Cromwell supports most CWL features as well as WDL. You can use Cromwell instead of cwltool when running CWL files
with Dockstore by adding the following line to your
This may not work with all CWL entries, but it is a good workaround for the cwltool incompatibility described above.