diff --git a/docs/source/howto/installation_guide.rst b/docs/source/howto/installation_guide.rst index 9bf90da6..b5124605 100644 --- a/docs/source/howto/installation_guide.rst +++ b/docs/source/howto/installation_guide.rst @@ -76,3 +76,24 @@ This image may be useful if you want an all-in-one image for pre-processing and You can pull the latest of this image or use a specific commit or tag as well:: docker pull ghcr.io/nrdg/afqsi:latest + + +How to build an Apptainer (Singularity) image +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If the user intends to execute pyAFQ as a program from the command line (``$pyAFQ /path/to/config.toml``) +in an administered environment where root access is not available (e.g., High Performance Computing cluster) +then one solution is to build an Apptainer (also known as Singularity) image from a local pull of the pyAFQ docker container. + +Start by running a docker registry:: + + docker run -d -p 5000:5000 --restart=always --name registry registry:2 + +Next, create a local tag which allows a push of the pyAFQ container to the local registry:: + + docker tag ghcr.io/nrdg/pyafq:latest localhost:5000/pyafq + docker push localhost:5000/pyafq:latest + +Finally build the singularity file referencing the local registry:: + + APPTAINER_NOHTTPS=1 apptainer build pyafq_latest.sif docker://localhost:5000/pyafq:latest diff --git a/docs/source/howto/usage/singularity.rst b/docs/source/howto/usage/singularity.rst new file mode 100644 index 00000000..c652505e --- /dev/null +++ b/docs/source/howto/usage/singularity.rst @@ -0,0 +1,16 @@ +The pyAFQ singularity image +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Assuming the singularity image ``pyafq_latest.sif`` exists, trigger the +entrypoint ``pyafq`` to run the workflow with:: + + apptainer run \ + --bind bids_dir:bids_dir \ + pyafq_latest.sif bids_dir/config.toml + +.. note:: + + It may be necessary to set the global variable TEMPLATEFLOW_HOME to + reference a pull of `TemplateFlow `_: + + ``export TEMPLATEFLOW_HOME=/path/to/templateflow``