== Using Containers with Brainstorm ==

Authors: Takfarinas Medani & Malte Höltershinken

Some Brainstorm processes rely on external software distributed using '''containers'''
(for example: ''duneuro''). Containers allow Brainstorm to run complex tools
without requiring manual installation of dependencies.

This page explains how to install a supported container runtime on your system.



<<TableOfContents(3)>>



----

== Containers for beginners ==

'''What is a container?'''

A container is a packaged version of a software tool that includes everything it needs to run.

With containers:
 * You do ''not'' need to install additional libraries
 * The software runs the same way on different computers
 * Brainstorm can automatically download and use the required tools

You do ''not'' need prior knowledge of containers to use Brainstorm.

----

== Supported container runtimes ==

Brainstorm supports the following container runtimes:

 * '''Docker''' (recommended for most users)
 * '''Podman''' (Linux alternative to Docker)
 * '''Apptainer / Singularity''' (recommended on HPC clusters)

Brainstorm automatically detects which runtime is available on your system.

You only need to install '''one''' of them.

----

== Which runtime should I install? ==

|| '''Operating system''' || '''Recommended runtime''' ||
|| Windows || Docker Desktop ||
|| macOS || Docker Desktop ||
|| Linux (desktop) || Docker or Podman ||
|| Linux (HPC) || Apptainer / Singularity ||

----

== Windows ==

=== Docker Desktop (recommended) ===

 1. Download Docker Desktop:
    [[https://docs.docker.com/desktop/|Docker Desktop documentation]]

 2. During installation:
    * Enable '''WSL 2''' if prompted
    * Restart your computer if required

 3. Start '''Docker Desktop''' and wait until it reports that Docker is running

No additional configuration is required for Brainstorm.

----

== macOS ==

=== Docker Desktop (recommended) ===

 1. Download Docker Desktop:
    [[https://docs.docker.com/desktop/|Docker Desktop documentation]]

 2. Install and launch Docker Desktop
 3. Wait until Docker reports that it is running

''On macOS, Docker runs inside a virtual machine.
This is normal and fully supported by Brainstorm.''

----

== Linux (desktop or workstation) ==

=== Option 1: Docker ===

Install Docker following the official instructions:
[[https://docs.docker.com/get-docker/|Docker installation guide]]

After installation, verify that Docker is running:
{{{
docker info
}}}

=== Option 2: Podman ===

Podman is a Docker-compatible alternative available on many Linux systems:
[[https://podman.io/get-started|Podman getting started]]

Podman does not require a background service.

----

== Linux (HPC clusters) ==

=== Apptainer / Singularity (recommended) ===

Most HPC systems provide '''Apptainer''' (formerly Singularity) by default.

Check availability:
{{{
apptainer version
}}}
or
{{{
singularity version
}}}

If Apptainer is not available, please contact your system administrator or consult:
[[https://apptainer.org/|Appt contandoer documentation]]

----

== Container images in Brainstorm ==

You do ''not'' need to download container images manually.

When a Brainstorm process requires a container:
 * Brainstorm checks whether the image is already available
 * If not, you will be asked for confirmation
 * The image is downloaded automatically

No additional commands are required.

----

== Frequently Asked Questions ==

=== Do I need to learn Docker or containers to use Brainstorm? ===

No.

Brainstorm manages containers automatically.
You only need to install a supported runtime.

----

=== Docker is installed but Brainstorm says it is not running ===

Make sure '''Docker Desktop is started''' and fully initialized,
then retry the Brainstorm process.

----

=== I don’t have administrator rights on my computer ===

If you are working on a shared system or cluster:
 * Apptainer / Singularity is usually available
 * If not, contact your system administrator

----

=== Are containers slower than native installations? ===

On Linux systems, performance is usually identical.

On Windows and macOS, containers run inside a virtual machine,
which may be slightly slower but is generally negligible for most workflows.

----

== Summary ==

 * Brainstorm supports Docker, Podman, and Apptainer / Singularity
 * Install '''one''' runtime appropriate for your system
 * Brainstorm downloads required container images automatically
 * No container expertise is required

For additional help, please consult the Brainstorm forum:
[[https://neuroimage.usc.edu/forums/|Brainstorm Forum]]