Container dependencies for MRtrix3

This repository is not applicable to users of the MRtrix3 software wishing to exploit container technology to utilise that software; it is only to be used by maintainers of the MRtrix3 software. For instructions on how to use container technology to execute MRtrix3 commands, see the relevant online documentation page.

---

This process can only be completed by those with write access to the "MRtrix3 container dependencies" OSF project. These files contain "minified" versions of external neuroimaging software package dependencies, containing only those components that are utilised by MRtrix3 scripts. These files should only need to be updated if:

• An MRtrix3 update introduces a new feature that invokes some new external software tool not previously utilised;
• A requisite update occurs in one of these external softwares.

1. Install Docker however it must be installed for your particular operating system / Linux flavour.

2. Install the docker and neurodocker Python packages.

   pip install docker neurodocker
   

3. Download the ART ACPCdetect tool from NITRC into the working directory.

   This cannot be downloaded directly via e.g. wget, as it requires logging in to NITRC; instead, visit the following link with a web browser: https://www.nitrc.org/frs/download.php/10595/acpcdetect_v2.0_LinuxCentOS6.7.tar.gz

4. Download test data necessary for minification process.

   curl -fL -# https://github.com/MRtrix3/script_test_data/archive/master.tar.gz | tar xz
   

5. Update file Dockerfile to install the desired versions of external software packages.

6. If necessary, update the MRtrix3 git committish so that the container will clone and build a specific version of the MRtrix3 code base; for instance, rebuilding a dependency container to reflect addition of a new feature in some branch. Note however that such a change should not be included in any update commit to this repository.

7. Build Docker image for neurodocker minify, with complete installations of external packages.

   DOCKER_BUILDKIT=1 docker build --tag mrtrix3:minify --build-arg MAKE_JOBS=4 .
   

   DOCKER_BUILDKIT=1 enables BuildKit, which builds separate build stages in parallel. This can speed up Docker build times in some circumstances. In this case, ANTs and MRtrix3 will be compiled in parallel, and other downloads will be performed at the same time as well.

   The MAKE_JOBS argument controls how many cores are used for compilation of ANTs and MRtrix3. If BuildKit is utilised, do not specify all of the available threads; specify half or fewer, so that threads are not unnecessarily split across jobs and RAM usage is not excessive.

8. Create a minified version of the Docker image.

   docker run --rm -itd --name mrtrix3 --security-opt=seccomp:unconfined --volume $(pwd)/script_test_data-master:/mnt mrtrix3:minify
   neurodocker minify --dir /opt --container mrtrix3 "bash cmds-to-minify.sh"
   docker export mrtrix3 | docker import - mrtrix3:minified
   docker stop mrtrix3
   

9. Generate tarballs for each of the utilised dependencies.

   mkdir -p tarballs
   docker run --rm -itd --workdir /opt --name mrtrix3 \
       --volume $(pwd)/tarballs:/output mrtrix3:minified bash
   docker exec mrtrix3 bash -c "find art/ -type f | tar c --files-from=/dev/stdin | pigz -9 > /output/acpcdetect_<version>.tar.gz"
   docker exec mrtrix3 bash -c "find ants/ -type f | tar c --files-from=/dev/stdin | pigz -9 > /output/ants_<version>.tar.gz"
   docker exec mrtrix3 bash -c "find fsl/ -type f | tar c --files-from=/dev/stdin | pigz -9 > /output/fsl_<version>.tar.gz"
   docker stop mrtrix3
   

   For each tarball, manually replace text "<version>" with the version number of that particular software that was installed in the container.

10. Upload these files to OSF.

Files Dockerfile and Singularity in the main MRtrix3 repository can then be modified to download the desired versions of external software packages. As OSF file download links do not contain file names, which would otherwise indicate the version of each software to be downloaded, please ensure that comments within that file are updated to indicate the version of that software within the tarball.