Using Nipoppy with Docker

This guide describes the steps required to run Nipoppy with Docker.

By default, Nipoppy will try to use Apptainer, but support for Docker was added in version 0.4.2.

Study-level configuration

The following changes need to be made to the "CONTAINER_CONFIG" field of the global_config.json file:

  • "COMMAND" should be set to "docker" instead of "apptainer"

  • Any non-Docker argument/option should be removed from "ARGS"

    • In particular, the default global_config.json uses the "--cleanenv" argument, which is specific to Apptainer and needs to be removed if using Docker.

    • Any user-specific bind paths also need to be changed to --volume instead of --bind. The target (destination) path also needs to be explicitly specified (e.g. --volume /source:/target instead of --volume). If using Nipoppy 0.4.6 or later, use the new dedicated "BIND_PATHS" field instead as it is agnostic to the container platform.

 1{
 2    "SUBSTITUTIONS": {
 3        "_comment": "Self-references like NIPOPPY_DPATH_CONTAINERS are resolved from the layout at runtime, making them layout-aware",
 4        "[[NIPOPPY_DPATH_CONTAINERS]]": "[[NIPOPPY_DPATH_CONTAINERS]]",
 5        "[[HPC_ACCOUNT_NAME]]": ""
 6    },
 7    "DICOM_DIR_PARTICIPANT_FIRST": true,
 8    "CONTAINER_CONFIG": {
 9        "COMMAND": "apptainer",
10        "ARGS": [
11            "--cleanenv"
12        ],
13        "BIND_PATHS": [],
14        "ENV_VARS": {
15            "PYTHONUNBUFFERED": "1"
16        }
17    },
18    "HPC_PREAMBLE": [
19        "# (These lines can all be removed if not using HPC functionality.)",
20        "# ========== Activate Python environment ==========",
21        "# Here we need the command to activate your Python environment in an ",
22        "# HPC job, for example:",
23        "# - venv:  source <PATH_TO_VENV>/bin/activate",
24        "# - conda: source ~/.bashrc; conda activate <ENV_NAME>",
25        "# ========== Set environment variables ==========",
26        "export PYTHONUNBUFFERED=1"
27    ],
28    "PIPELINE_VARIABLES": {
29        "BIDSIFICATION": {},
30        "PROCESSING": {},
31        "EXTRACTION": {}
32    },
33    "CUSTOM": {}
34}

Pipeline-level configuration

Similarly to global_config.json, pipeline-specific config.json files also have "CONTAINER_CONFIG" fields. They can appear at the top level or inside individual step configurations. The same changes described above need to be applied to these "CONTAINER_CONFIG" fields. Most commonly, bind paths need to be changed to --volume instead of --bind, and the target (destination) path needs to be explicitly specified (e.g. --volume /source:/target instead of --volume). If using Nipoppy 0.4.6 or later, use the new dedicated "BIND_PATHS" field instead as it is agnostic to the container platform.

 1{
 2    "NAME": "fmriprep",
 3    "VERSION": "24.1.1",
 4    "CONTAINER_INFO": {
 5        "FILE": "[[NIPOPPY_DPATH_CONTAINERS]]/[[PIPELINE_NAME]]_[[PIPELINE_VERSION]].sif",
 6        "URI": "docker://nipreps/[[PIPELINE_NAME]]:[[PIPELINE_VERSION]]"
 7    },
 8    "CONTAINER_CONFIG": {
 9        "ENV_VARS": {
10            "TEMPLATEFLOW_HOME": "[[TEMPLATEFLOW_HOME]]"
11        },
12        "ARGS": [
13            "--bind",
14            "[[FREESURFER_LICENSE_FILE]]",
15            "--bind",
16            "[[TEMPLATEFLOW_HOME]]",
17            "--bind",
18            "[[NIPOPPY_DPATH_PIPELINE_WORK]]:/work",
19            "--bind",
20            "[[NIPOPPY_DPATH_DERIVATIVES]]/freesurfer/7.3.2/output/[[NIPOPPY_BIDS_SESSION_ID]]"
21        ]
22    },
23    "STEPS": [
24        {
25            "INVOCATION_FILE": "invocation.json",
26            "DESCRIPTOR_FILE": "descriptor.json",
27            "HPC_CONFIG_FILE": "hpc.json",
28            "TRACKER_CONFIG_FILE": "tracker.json"
29        }
30    ],
31    "VARIABLES": {
32        "FREESURFER_LICENSE_FILE": "Path to FreeSurfer license file",
33        "TEMPLATEFLOW_HOME": "Path to the directory where TemplateFlow will store templates (can be empty)"
34    },
35    "PIPELINE_TYPE": "processing",
36    "SCHEMA_VERSION": "1"
37}