Containers with Brainstorm
Authors: Raymundo Cassani, Takfarinas Medani and Malte Höltershinken
An application or software container is a packaged version of a software tool, bundled with everything it needs to run. With in Brainstorm, some Brainstorm functions rely on external software that is distributed as software containers, one example of this is the resection identificaron process that uses the container resection-identification to identify the part of the MRI that was resected based on the pre- and post-operation MRI volumes.
As such, using containers in Brainstorm allow run complex tools without requiring manual installation of all their dependencies. This page explains how containers are managed by Brainstorm, and how set up your system to use them.
Contents
Introduction
Brainstorm makes use of software containers (that follow the OCI standards) to facilitate the installation and use of tools that otherwise would require a complex environment setup.
With containers:
- You do not need to install the tool’s libraries or dependencies manually
- The tool runs the same way across different computers and operating systems
- The same version of the tool is used every time, supporting reproducible analyses
- Brainstorm can automatically download and run the required tool when it is needed
You do not need any prior knowledge of containers to use Brainstorm. The only requirement is a container engine installed on your computer, which handles running the container. Installing and setting this up is described in following section.
Setup in Brainstorm
Installation
First you need to install one of the supported container engines
Brainstorm supports the following container engines:
Docker Desktop
Recommended for most users
- Docker engine and GUI
Available for Linux, Windows and macOS
To install, be sure of follow the instructions for your OS:
Docker Engine
Available only Linux
Docker engine without GUI, usually installed as root
To install, be sure of follow the instructions:
Podman
- BRAINSTORM INTEGRATION ON DEV
Apptainer / Singularity
Recommended on HPC clusters
- BRAINSTORM INTEGRATION ON DEV
Set default container engine
Once installed, set the Container engine command to your preferred container engine.
Interactive management
The Brainstorm interface offers menus to Import and Uninstall the container images, as well as to manually run and stop the containers.
Import image: Downloads the container image using the defined container engine.
Container plugins are are not usually Run manually, their execution is commonly prompted by a process or function that relies on the container to perform the processing.
Uninstall: Removes the container image.
Run container (as daemon): This starts the container without an entrypoint, and keeps the container running so it can be used later by other processes.
Container plugins are are not usually Run manually, their execution is commonly prompted by a process or function that relies on the container to perform the processing.
Stop container: Stop the container.
Website: Opens the website documenting the container plugin.
Usage statistics: Display the number of downloads of the plugin, month by month.
How containers interact with Brainstorm
When a container-based tool is required, Brainstorm starts its container and keeps it running in the background, then executes each command inside the running container as needed. Reusing a single running container, rather than starting a new one for every operation, avoids repeated start-up costs when several commands are run in sequence.
Brainstorm always specifies the exact command to execute inside the container. Because the command is issued explicitly, the tool is invoked the same way whether or not the container image defines a default entry point.
An example of how a container is started and then used to perform an action can be found in process_resection_identification.m
Container definition
In Brainstorm the definition of a container plugin follows the general definition of plugins, with three differences:
The field ImageSource field is mandatory
The field URLzip must be empty
The field CompiledStatus must be always be 1. This is to say, the container can be installed and run with the Standalone version of Brainstorm.
% === ANATOMY: RESECTION IDENTIFICATION ===
p = GetStruct('resection-identification');
p.Version = 'latest';<<BR>>
p.Category = 'Anatomy';
p.URLinfo = 'https://github.com/ajoshiusc/auto_resection_mask/tree/brainstorm-container';
p.ImageSource = ['docker.io/brainstormtools/auto-resection-mask:' p.Version];
p.CompiledStatus = 1;Users can add their own containers as user-defined plugins
Command-line management
The calls to install or manage containers plugins are the same than for (code) plugins, see the plugin tutorial.
An API for low-level interaction between Brainstorm and the container engine has been implemented, this API is documented in the header of bst_containers.m:
