singularity (apptainer) instructions

[arokem]

We are using qsiprep on an HPC cluster that requires use of apptainer (i.e., singularity the next generation).

We found that when we run the singularity command as described here, we run into some issues. Basically, our issue was that we started off by converting the docker image into a singularity image and then tried to use the docker command, but there are subtle differences between how this is run in docker and how this should be run in apptainer. Maybe it would be good to document this difference? We believe it should be something like:

apptainer exec --mount type=bind,src=/path/to/data,dst=/data,ro --mount type=bind,src=/path/to/out,dst=/out /path/to/qsiprep_0_13_1.sif qsiprep /data /out participant --fs-license-file /data/fs_license.txt --output-resolution 1.5 --distortion-group-merge average

In contrast to the docker command, this command has an additional qsiprep between the name of the image and the names of the folders (which is not required in the docker image, as it has that as an entrypoint). We would've submitted a PR to fix this, but we don't exactly understand how this section of the documentation gets generated.

CC: @teresamg, @mckenziephagen

[mckenziephagen]

This is the result of using singularity exec vs. singularity run. exec expects to have a command specified, while run runs the runscript if one is in the container (singularity docs). IMO, the distinction between the two isn't the most obvious if you haven't used containers before, so adding a note to the singularity container would clear things up!

[arokem]

Thanks for setting me straight! I agree that it might be nice to have this spelled out in the documentation for the luddites such as myself, but this might also be out of scope for qsiprep, so I'd also be sympathetic if this issue is closed with no further action taken.

[mattcieslak]

For reference, the documentation for this comes from here. This will definitely need an option for supporting apptainer though.

[mckenziephagen]

For now, installs of apptainer alias singularity, but I don't know when that will phase out.

[tsalo]

@arokem you recently updated the Singularity/Apptainer documentation. Do you think this is good to close?

[arokem]

I don't think that I properly addressed the apptainer run / apptainer exec distinction in #846, so I don't think this should be closed yet.