Many users first come to Singularity because they want to run an existing Docker container on a system where they can’t run Docker natively. Later on, they may build their own containers via Singularity definition files, often using a Docker image as a starting point. Most of the time things just work with singularity run docker://… and will act just as you expect, dropping you inside your container. However, there are some differences between Singularity and Docker that you may run into when using some of the more complicated containers available on the Docker Hub and elsewhere. Let’s take a look at the issues, some which are addressed in Singularity 2.5 which will be released soon!
Whiteout Files
Singularity images are a single file containing the state of a container’s file system. Docker, on the other hand, constructs containers at run-time from layers. Each layer is a tar archive, containing files that make up the container. A layer is created for each step in the Dockerfile that was used to build the container. The layers must be extracted in the right order to reproduce the container properly.
Some complexity comes in when existing files or directories are deleted during a Dockerfile step. A tar archive can’t represent deletion of a file or folder, so Docker uses special whiteout files, beginning with .wh., to show something needs to be deleted when a layer is processed.
Singularity hasn’t always handled these whiteout files correctly, which can lead to strange errors, like the one below, when you run e.g. complex python-based containers: