SIRF SuperBuild on Docker

Docker

Docker is a low-overhead, container-based replacement for virtual machines (VMs).

This works best on a linux system due to:

1. Possibility to get CUDA support within the container
2. X11 windows displayed natively without needing e.g. a vnc server or desktop in the container

This is probably the easiest way to use SIRF due to really short installation instructions essentially consisting of:

docker-compose up --no-start
docker start -ai sirf

Prerequisites

• Docker
  • The free Community Edition (CE) is sufficient
  • docker-compose
• The SIRF-SuperBuild repository
  • download and unzip or git clone this locally

Glossary

A wonderfully tiny list of everything important to know for a basic working knowledge of docker.

• Base image: the starting point for building a Docker image
  • analogous to a clean OS (in this case ubuntu:16.04)
• Layer: a single build step
  • usually represented by a single line in a Dockerfile (e.g. apt-get install cmake)
• Image: a sequence of layers (applied on top of a base image)
  • analogous to a clean OS with SIRF installed (in this case tagged ccppetmr/sirf)
• Container: a sandboxed workspace derived from an image
  • analogous to a running virtual machine (in this case named sirf)
  • easily stoppable, restartable, disposable
  • can be thought of as end-user-created layers which would never be formally part of a redistributable image
  • can share files, network connections, and devices with the host computer

Images are built or pulled. Containers are created from them:

• Build: typically refers to pulling a base image, then building all the layers necessary to form an image
  • usually once-off
• Pull: typically refers to downloading an image from the internet (which someone else built)
  • usually only required when there is no source code available to allow for building locally
• Create: typically refers to making a container from an image
  • often recreated for a semi-clean slate - especially if data is shared with the host computer so that no data is lost on disposal

SIRF Image Building and Container Creation

The docker image can be built from source using CCPPETMR/SIRF-SuperBuild by following the steps below. Alternatively, simply run docker pull ccppetmr/sirf to download a pre-built image.

docker-compose is used to help with creating containers (and even building images). It should be added to your PATH or at least have the executable copied to SIRF-SuperBuild/docker.

Linux

For easier file and window sharing, the image ccppetmr/sirf should be built using the host user's ID and some environment variables:

SIRF-SuperBuild/docker$ docker-compose -f docker-compose.yml \
  -f docker-compose.nix.yml build \
  --build-arg UID=$(id -u) --build-arg GROUPS=$(id -g) sirf

After this a container called sirf is created:

SIRF-SuperBuild/docker$ docker-compose up --no-start

Windows

For the first step, instead of passing user IDs, Windows requires that file sharing is enabled. The container creation will automatically build the image if necessary:

SIRF-SuperBuild/docker> docker-compose up --no-start

Developers

To (re)build ccppetmr/sirf efficiently (e.g. after modifying the Dockerfile):

SIRF-SuperBuild/docker$ docker build -t ccppetmr/sirf \
  --build-arg UID=$(id -u) --build-arg GROUPS=$(id -g) .

Then simply recreate the container with docker-compose up --no-start.

Usage

Well, that was easy. The container can be run interactively for daily use.

SIRF-SuperBuild/docker$ docker start -ai sirf
(py2) sirf:~$ gadgetron >> /dev/null &
(py2) sirf:~$ python SIRF-SuperBuild/SIRF/examples/Python/MR/fully_sampled_recon.py

The first line starts the sirf docker container. The second line starts gadgetron within the container as a background process. Finally, we can then run an example.

Note that the devel folder in the host's SIRF-SuperBuild/docker directory is mounted to /devel in the container.

Notes

• Tests can be run (after gadgetron is started) as follows:

(py2) sirf:~$ cd SIRF-SuperBuild
(py2) sirf:~/SIRF-SuperBuild (master)$ pip install nose
(py2) sirf:~/SIRF-SuperBuild (master)$ ctest -VV

• "Cannot connect to display" errors are usually fixed by running xhost +local:"" on the host linux system
• Non-linux users (e.g. Windows) will need to set up a desktop and vnc server in order to have a GUI (docker files coming soon)
• On host systems with less than 16GB RAM, before docker-compose up ... you may want to edit SIRF-SuperBuild/docker/user_sirf-ubuntu.sh, changing the line make -j... to simply make. This increases build time and reduces build memory requirements.