1.3. Work with Docker/Containerized AFNI

1.3.1. Install the Docker Engine

Notes on installing the Docker Engine on various OSs/platforms are available here:
https://docs.docker.com/engine/install/
For example, I have followed the installation steps for Ubuntu here:
https://docs.docker.com/engine/install/ubuntu/
... and my computer did not burst into flames (yet!).

1.3.2. Use pre-built dockerfile

The continuous integration set up on AFNI’s Github uses CircleCi and pushes to a Docker Hub account when it succeeds (thanks, Dylan and Jakub!). It is built with the Dockerfile in the base directory of the AFNI codebase and uses the CircleCi yml file here.

Get the image

To get the image from the online repository (here, Docker Hub), run:

docker pull afni/afni_make_build

This should only have to be done once.

Sidenote: the list of AFNI-built containers that are distributed on Docker Hub is here:
https://hub.docker.com/u/afni
Here, we show an example using the afni_make_build container; this is the best starting point at present, while afni_cmake_build could be reasonable (if not essentially the same), as well.

Start the container environment

To use the contents of the container, copy+paste:

docker run --rm -ti  afni/afni_make_build

After that, the docker environment should be up and running in that terminal, and which afni should output a value under /opt/.... The non-GUI programs should work fine.

To do that while also mounting your home directory (to access those files), you can run:

docker run --rm -ti  -v ${HOME}:/opt/home  afni/afni_make_build

... after which everything in your typical home directory would be accessible under /opt/home/.

Finally, to do both of those things and to have the ability to open up the afni and suma GUIs (see this note if using macOS 12 with an Apple Silicon CPU), you could run:

docker run --rm -ti                  \
    --user=`id -u`                   \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -e DISPLAY=${DISPLAY}            \
    -v ${HOME}:/opt/home             \
    afni/afni_make_build

Note that to be able to use the above command, your local computer itself must be set up to open the GUIs.

(Thanks, Vinai, for many helpful pointers with this!)

Exit the container

Select the terminal and hit Ctrl+d, or type the command exit.

A note if you are using macOS 12

Things are slightly more complicated to be able to run the GUIs through Docker. The following still assumes you have already installed XQuartz on your computer following the AFNI install instuctions.

First, set your XQuartz security preferences as follows (which should only have to be done once):

  1. Launch XQuartz, open its menu, and select Preferences

  2. Go to the Security tab, and ensure “Allow connections from network clients” is checked.

Then, you can run your docker container as follows (yes, two commands):

xhost + ${hostname}

docker run --rm -ti                    \
    --user=`id -u`                     \
    -v /tmp/.X11-unix:/tmp/.X11-unix   \
    -e DISPLAY=host.docker.internal:0  \
    -v ${HOME}:/opt/home               \
    afni/afni_make_build

The above is derived from notes and further discussion here. As written, the xhost command may just apply in zsh/bash shells.

1.3.3. Neurodocker

Please also check out Neurodocker for examples of commands to build Dockerfiles and Singularity with AFNI (thanks, Jakub!):

https://github.com/ReproNim/neurodocker