2. Installation

BrainSuite BIDS App can be downloaded using either of two methods, both of which use lightweight container technologies (Docker or Singularity). Docker requires admin privileges, so if you do not have admin privileges on your computer or system, it is best to use the Singularity-based BrainSuite BIDS App. Additionally, for multi-user compters/systems, it is recommended that you use the Singularity-based BrainSuite BIDS App, because Docker may pose security risks.

In short, to use the BrainSuite BIDS App:

Install a container technology (Docker or Singularity).
Download BrainSuite BIDS App image file.

Detailed information is available in the following sections.

2.1. Docker-based installation

2.1.1. Install Docker

To run the Docker-based BrainSuite BIDS App, you (or your IT support) will need to install Docker on the system where you will be running the Docker-based BrainSuite BIDS App. If you have not yet installed Docker, please install Docker from here. Docker is available on all platforms. For Linux, you may have to perform additional post-installation steps.

2.1.2. Pulling pre-built Docker image

After installing Docker, you can directly pull the BrainSuite BIDS App from the Docker Hub repository by running the following command in the terminal:

docker pull bids/brainsuite:v23a

The above command will pull all layers of the Docker image (17 GB total), which may take a while depending on your download speed.

2.1.3. Building from source

To build from source (not recommended due to constantly changing third party repositories), you can clone our BrainSuite BIDS App Github repo by running:

git clone https://github.com/bids-apps/BrainSuite.git
cd BrainSuite
docker build -t brainsuite .

where brainsuite is modifiable and is the name used for the Docker image that you will build.

2.2. Singularity-based installation

Using a Singularity version of BrainSuite BIDS App is often required for multi-user systems with shared resources due to security concerns. Docker requires admin privileges, which can pose risks. Singularity addresses this issue by restricting escalated privileges.

2.2.1. Install Singularity

To run the converted Singularity-compatible BrainSuite BIDS App, you will need to install Singularity on the system where you will be running the Singularity-based BrainSuite BIDS App. You (or your IT support) can install Singularity as described here.

2.2.2. Downloading a pre-built Singularity image

A pre-built Singularity version of the BrainSuite BIDS App image (6.6 GB total) is available here.

2.2.3. Converting Docker image to Singularity image

If you would like to convert the Docker image to a Singularity image instead of downloading a pre-built Singularity image, you can do so by completing the following instructions. Note that the conversion to a Singularity-compatible image additionally requires Docker to be installed on your system, because the conversion is performed using a Docker image called quay.io/singularity/docker2singularity.

Install Docker if you have not yet done so already.
Define the directory where you want to store the Singularity-converted image:
```
outputDirectory=/path/to/singularityImg
```

Now, run the following command line call to convert the Docker version of the BrainSuite BIDS App into a Singularity-compatible BrainSuite BIDS App:

docker run -v /var/run/docker.sock:/var/run/docker.sock \
    -v ${outputDirectory}:/output \
    --privileged -t --rm \
    quay.io/singularity/docker2singularity \
    bids/brainsuite:v23a

This conversion takes approximately 6 minutes on a machine with 64 GB of RAM and 4 cores (8 total threads). The result is a 6.6 GB Singularity-compatible image.