Skip to content

Commit

Permalink
DOC: Remove the destination paths in container documentation (#621)
Browse files Browse the repository at this point in the history
* DOC: Remove the destination paths in container documentation

Remove the destination paths for the input and output binding input
arguments in the `Docker` and `Singularity` container usage instructions.

Avoids, for example, errors that mean that no (BIDS) data was
effectively found, e.g.:
```
Process Process-2:
Traceback (most recent call last):
  File "/usr/local/miniconda/lib/python3.8/multiprocessing/process.py", line 315, in _bootstrap
    self.run()
  File "/usr/local/miniconda/lib/python3.8/multiprocessing/process.py", line 108, in run
    self._target(*self._args, **self._kwargs)
  File "/usr/local/miniconda/lib/python3.8/site-packages/qsiprep/cli/run.py", line 833, in build_qsiprep_workflow
    layout = BIDSLayout(
  File "/usr/local/miniconda/lib/python3.8/site-packages/bids/layout/layout.py", line 135, in __init__
    root, description = validate_root(root, validate)
  File "/usr/local/miniconda/lib/python3.8/site-packages/bids/layout/validation.py", line 70, in validate_root
    raise ValueError("BIDS root does not exist: %s" % root)
ValueError: BIDS root does not exist: /mnt/data/my/path/
```

* make sure paths reflect the mount points

---------

Co-authored-by: Matt Cieslak <mattcieslak@gmail.com>
  • Loading branch information
jhlegarreta and mattcieslak authored Aug 31, 2023
1 parent 8942e25 commit 1844872
Showing 1 changed file with 33 additions and 33 deletions.
66 changes: 33 additions & 33 deletions docs/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -21,51 +21,57 @@ Docker Container
In order to run qsiprep in a Docker container, Docker must be `installed
<https://docs.docker.com/engine/installation/>`_.
Once Docker is installed, the recommended way to run qsiprep is to use the
``qsiprep-docker`` wrapper, which requires Python and an Internet connection.
``qsiprep-docker`` wrapper, which requires Python and an Internet connection
and that you install the ``qsiprep-container`` package with ``pip``.

.. note:: If running Docker Desktop on MacOS, be sure to set the memory to 6 or more GB.
Too little memory assigned to Docker Desktop can result in a message like ``Killed.``
.. note:: If running Docker Desktop on MacOS (or via Docker Desktop), be sure to set
the memory to 6 or more GB. Too little memory assigned to Docker Desktop can result
in a message like ``Killed.``

When run, ``qsiprep-docker`` will generate a Docker command line for you,
print it out for reporting purposes, and then run the command, e.g.::

$ qsiprep-docker /path/to/data/dir /path/to/output/dir participant
RUNNING: docker run --rm -it -v /path/to/data/dir:/data:ro \
-v /path/to_output/dir:/out pennbbl/qsiprep:1.0.0 \
RUNNING: docker run --rm -it -v /path/to/data/dir:/data \
-v /path/to_output/dir:/out pennbbl/qsiprep:latest \
/data /out participant
...

You may also invoke ``docker`` directly::

$ docker run -ti --rm \
-v filepath/to/data/dir:/data:ro \
-v filepath/to/output/dir:/out \
-v /filepath/to/data/dir \
-v /filepath/to/output/dir \
-v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
pennbbl/qsiprep:latest \
/data /out participant
/filepath/to/data/dir /filepath/to/output/dir participant \
--fs-license-file /opt/freesurfer/license.txt

For example: ::

$ docker run -ti --rm \
-v $HOME/fullds005:/data:ro \
-v $HOME/dockerout:/out \
-v $HOME/fullds005 \
-v $HOME/dockerout \
-v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
pennbbl/qsiprep:latest \
/data /out participant \
--ignore fieldmaps
$HOME/fullds005 $HOME/dockerout participant \
--ignore fieldmaps \
--fs-license-file /opt/freesurfer/license.txt

If you are running Freesurfer as part of QSIPrep,
If you are running Freesurfer as part of QSIPrep,
you will need to mount your Freesurfer license.txt file when invoking ``docker`` ::

$ docker run -ti --rm \
-v $HOME/fullds005:/data:ro \
-v $HOME/dockerout:/out \
-v $HOME/fullds005 \
-v $HOME/dockerout \
-v ${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
pennbbl/qsiprep:latest \
/data /out participant \
$HOME/fullds005 -v $HOME/dockerout participant \
--fs-license-file /opt/freesurfer/license.txt


See `External Dependencies`_ for more information (e.g., specific versions) on
what is included in the latest Docker images.
See `External Dependencies`_ for more information on what is included in the Docker image
and how it's built.



Expand All @@ -77,28 +83,22 @@ The easiest way to get a Sigularity image is to run::
$ singularity build qsiprep-<version>.sif docker://pennbbl/qsiprep:<version>

Where ``<version>`` should be replaced with the desired version of qsiprep that you want to download.
Do not use ``latest``.
Do not use ``latest`` or ``unstable`` unless you are performing limited testing.

As with Docker, you will need to bind the Freesurfer license.txt when running Singularity ::

$ singularity run --cleanenv \
-B $HOME/fullds005:/data:ro,$HOME/dockerout:/out,${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
$ singularity run --containall --writable-tmpfs \
-B $HOME/fullds005,$HOME/dockerout,${FREESURFER_HOME}/license.txt:/opt/freesurfer/license.txt \
qsiprep-<version>.sif \
/data /out participant \
$HOME/fullds005 $HOME/dockerout participant \
--fs-license-file /opt/freesurfer/license.txt


External Dependencies
---------------------

qsiprep is written using Python 3.6 (or above), and is based on
nipype_.

qsiprep requires some other non-python neuroimaging software tools:

- ANTs_ (version 2.3.9)
- AFNI_ (version Debian-16.2.07)
- FreeSurfer_ (6.0.1)
- FSL_ (6.0.3)
- `DSI Studio`_
- MRtrix_
qsiprep is written using Python 3.8 (or above), and is based on
nipype_. The external dependencies are built in the `qsiprep_build
<https://github.com/PennLINC/qsiprep_build>`_ repository. There
you can find the URLs used to download the dependency source code
and the steps to compile each dependency.

0 comments on commit 1844872

Please sign in to comment.