Understanding Bind Mounts
- Docker containers are isolated from your computer, which makes it difficult for them to process data ON your computer!
- A bind mount solves this problem by providing Docker access to a directory on your computer (i.e., the "outside") as if it were inside the container.
- The
-vbind mount flag is quite common. After the-vflag, you must specify the bind using the correct order:outside:inside. - outside = the absolute path to the directory on your computer.
"${PWD}"can be that absolute path if you run the Docker command from the directory you want to mount.
- inside = the absolute path to some mount point inside the container.
- Because it is an absolute path, the path must start with
/. - For BIDS, the inside mount points are usually something like
/dataand/out. - Try to stick to the examples provided with the BIDS app (but, if you make up a name for the inside mount, that usually works fine with the
-vflag).
- Because it is an absolute path, the path must start with
Read-Only
- You can optionally specify that the mounted directory is read-only
:ro: This is suggested for the BIDS data directory in most cases. - An exception to mounting the BIDS data directory read-only: If you are defacing the structural image, then you must create and remove files from the BIDS data directory. In this case, it can't be read-only.
Note
Regardless of the permissions you have set for the data directory on your local machine, you can still set the bind-mount to be read-only.
- Download the Docker-Singularity_Rosetta_Stone.pdf to compare Docker and Singularity commands: The Rosetta stone focuses on bind mounts. Generally, Docker is much pickier about bind mounts than Singularity, but a mount that works for Docker should work for Singularity.
Example
- In this example, the BIDS container has two bind mounts indicated by
-vflags:
</div> language-'></div>">- `"${PWD}/nifti"` (on the outside) is bound to `/data` (on the inside), and mounted read-only: `-v "${PWD}/nifti":/data:ro`
- `"${PWD}/derivatives"` (on the outside) is bound to `/out` (on the inside). Processing results will be written here.
- By running the Docker command from a particular location in the directory tree, `$PWD` can help specify the absolute path:
- The external mount points, `"${PWD}/nifti"` and `"${PWD}/derivatives"`, assume you are located in the parent directory of `nifti` and `derivatives`.
- It is safer to enclose the PWD path in double quotes, in case there are any spaces in the pathname.
## Freesurfer License File
- It is not uncommon to need to mount the Freesurfer license file in addition to mounting an input and output directory:
`-v /Users/dpat/license.txt:/opt/freesurfer/license.txt:ro`
- In this case, you need to use the suggested internal mount point, e.g., `/opt/freesurfer/license.txt`
- Most people store the license file in their home directory.
- Don't put `license.txt` in your BIDS data directory because the bids-validator will reject it!
## Lots of Bind Mounts!
- *In the following examples `\` is used to escape the line-break and facilitate reading the long command. The examples can be entered literally in a script or in the terminal with or without the `\` (of course, the external mount points must be altered for your machine).*
- Some containers need a lot of bind mounts! For example, QSIprep requires four bind mounts for preprocessing: the freesurfer license, input, output, and work directories!
<div class='oc-markdown-activatable oc-markdown-custom-container' data-value='```
docker run --rm -it \
-v /Users/dpat/license.txt:/opt/freesurfer/license.txt:ro \
-v /QSIPrep/data:/data:ro \
-v /QSIPrep/derivatives:/out \
-v /QSIPrep/work:/work \
pennbbl/qsiprep /data /out participant \
--output-resolution 1.3 --do-reconall -w /work -v -v
'>
- QSIprep requires 5 bind mounts for the reconstruction!
- In the figure below, the container and the internal mount points are in red.
- The container is running on a computer. The computer and its mount points are in blue.
- The arrows illustrate how the external mount points are bound to each of the internal mount points:
-v external_mount:internal_mount
Docker Bind mount
Was this helpful?
(Voting helps us personalize your learning experience!)
In this 21-minute video, Tom Hicks explains bind mounts.
Containers: Docker Bind Mounts 2
Was this helpful?
(Voting helps us personalize your learning experience!)
Summary
This lesson focused on understanding bind mounts. Bind mounts are absolutely crucial to running BIDS apps. Conceptually, you must understand relative vs absolute paths and the isolation of the container to specify bind mounts correctly.
Stop and think about these concepts and terms
bind mount
absolute path
inside vs outside the container
read-only
absolute path
inside vs outside the container
read-only