Differences between revisions 2 and 8 (spanning 6 versions)

Containers with Brainstorm

Authors: Takfarinas Medani, Malte Höltershinken, and Raymundo Cassani

Some Brainstorm functions and plugins rely on external software that is distributed as containers (for example: duneuro 2026). These containers are managed in Brainstorm as container plugins.

Container plugins are not usually installed alone, their installation is commonly as a dependency for a code plugin.

This page explains how containers are used by Brainstorm, and how set up your system to use them.

Contents

Introduction
Container engines
Interactive management
Command-line management

Introduction

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.

To be able to use containers with Brainstorm it is necessary to have a supported container engine.

Container engines

Brainstorm supports the following container engines:

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

Brainstorm automatically detects which runtime is available on your system.

You need to install at least one of them.

Docker Desktop (recommended)

To install, be sure of follow the instructions for your OS:

https://docs.docker.com/desktop/

Interactive management

SHOW THE GUI FOR CONTAINER 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 in bst_containers.m

function varargout = bst_containers(varargin)
% BST_CONTAINERS: Manage containers for container-based plugins in Brainstorm
%
% USAGE: 
%  [errMsg, engineName]    = bst_containers('GetEngine')
%  [errMsg, imageList]     = bst_containers('GetImages')
%  [errMsg, imageSha]      = bst_containers('ImportImage', imageSource, [imageTag])
%   errMsg                 = bst_containers('RunContainer', containerName, imageSha, [volumes], [isDaemon], [containerArgs])
%  [errMsg, cmdout]        = bst_containers('ExecInContainer', containerName, cmdStr)
%  [errMsg, containerInfo] = bst_containers('GetContainerInfo', containerName)
%   errMsg                 = bst_containers('StopContainer', containerName, [isForced=0])
%   errMsg                 = bst_containers('RemoveImage', imageSha/Name, [isForced=0])

% @=============================================================================
% This function is part of the Brainstorm software:
% https://neuroimage.usc.edu/brainstorm
% 
% Copyright (c) University of Southern California & McGill University
% This software is distributed under the terms of the GNU General Public License
% as published by the Free Software Foundation. Further details on the GPLv3
% license can be found at http://www.gnu.org/copyleft/gpl.html.
% 
% FOR RESEARCH PURPOSES ONLY. THE SOFTWARE IS PROVIDED "AS IS," AND THE
% UNIVERSITY OF SOUTHERN CALIFORNIA AND ITS COLLABORATORS DO NOT MAKE ANY
% WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
% MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, NOR DO THEY ASSUME ANY
% LIABILITY OR RESPONSIBILITY FOR THE USE OF THIS SOFTWARE.
%
% For more information type "brainstorm license" at command prompt.
% =============================================================================@
%
% Authors: Raymundo Cassani, 2026
%          Takfarinas Medani, 2026

eval(macro_method);
end


%% ===== GET CONTAINER ENGINE =====
function [errMsg, engineName] = GetEngine(engineName)
% USAGE: [errMsg, engineName] = bst_containers('GetEngine')             % Find, test and set a supported container engine
%        [errMsg, engineName] = bst_containers('GetEngine', engineName) % Test the requested container engine
    errMsg  = '';

    % Get and test all the supported container engines
    if nargin < 1 || isempty(engineName) || strcmpi(engineName, 'auto-detect')
        [~, engineNames] = bst_get('ContainerEngine');
        % Remove 'auto-detect', first element in engineNames
        engineNames(1) = [];
        engineName     = '';
        isSetDefault   = 1;
    % Test only the requested container engine
    else
        engineNames  = {engineName};
        isSetDefault = 0;
    end

    % Tests container engines
    isFound = 0;
    for iEngine = 1 : length(engineNames)
        switch engineNames{iEngine}
            case {'docker'}
                if ispc
                    [status, cmdout] = system(['where ' engineNames{iEngine}]);
                    if status == 0
                        cmdout = strsplit(strtrim(cmdout), '\n');
                        if ~isempty(cmdout)
                            isFound = 1;
                            enginePath = strtrim(cmdout{1});
                        end
                    end
                else
                    [status, cmdout] = system(['which ' engineNames{iEngine}]);
                    if status == 0
                        isFound = 1;
                        enginePath = strtrim(cmdout);
                    end
                end
        end
        % Break loop if found
        if isFound
            engineName = engineNames{iEngine};
            break
        end
    end
    % Return if not found
    if ~isFound
        if isempty(engineName)
            errMsg = 'No valid container engine was found';
        else
            errMsg = ['Container engine ' engineName ' was not found'];
        end
        return
    % Set as default the container engine found
    elseif isSetDefault
        bst_set('ContainerEngine', engineName);
    end

    % Check the container engine status
    switch engineName
        case 'docker'
            [status, cmdout] = system([engineName ' info']);
            cmdout = strtrim(cmdout);
            if status == 1 || ~isempty(strfind(lower(cmdout), 'failed')) || ~isempty(strfind(lower(cmdout), 'error'))
                errMsg = cmdout;
                return
            end
    end
end


%% ===== GET AVAILABLE IMAGES =====
function [errMsg, imageList] = GetImages()
% USAGE:  [errMsg, imageList] = bst_containers('GetImages')
    imageList = cell(0,3); % [Name:Tag, ImageSHA, ManifestSHA]

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % List of available images
    switch engineName
        case 'docker'
            [status, cmdout] = system('docker images --all --digests --no-trunc --format "{{.Repository}}:{{.Tag}} {{.ID}} {{.Digest}}"');
            if status == 0 && ~isempty(cmdout)
                imageList = strsplit(strtrim(strrep(cmdout, char(10), ' ')), ' ');
                if mod(length(imageList), 3) ~= 0
                    errMsg = 'Error parsing Docker image list';
                    return
                end
                imageList = reshape(imageList, 3, [])';
            elseif status ~= 0
                errMsg = cmdout;
            end
    end
end


%% ===== IMPORT IMAGE =====
function [errMsg, imageSha] = ImportImage(imageSource, imageTag)
% Import container image into container engine, and create a tag
% USAGE:  [errMsg, imageSha] = bst_containers('ImportImage', imageSource, [imageTag])
    imageSha = '';

    if (nargin < 2) || isempty(imageTag)
        imageTag = '';
    end

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Default: imageSource is an image reference
    imageType = 'reference';
    % If imageSource is a URL, download image file
    if ~isempty(regexp(imageSource, '^http[s]*://', 'once'))
        % Get tmp dir to bind container
        tmpDir = bst_get('BrainstormTmpDir', 0, 'pull_image');
        imageFile = bst_fullfile(tmpDir, 'image.tgz');
        disp(['BST> Downloading URL : ' imageSource]);
        disp(['BST> Saving to file  : ' imageFile]);
        errMsg = gui_brainstorm('DownloadFile', imageSource, imageFile, 'Download container image: ');
        if ~isempty(errMsg)
            errMsg = ['Impossible to download container image automatically:' 10 errMsg];
            return
        end
        imageSource = imageFile;
        imageType = 'file';
    end

    % Get current available images
    if ~isempty(imageTag)
        [errMsg, imageListOld] = GetImages();
        if ~isempty(errMsg)
            return
        end
    end

    % Import image
    switch engineName
        case 'docker'
            manifestSha = '';
            switch imageType
                case 'reference'
                    [status, cmdout] = system(['docker pull ' imageSource]);
                    if status == 0
                        % If new or existent image, returned SHA256 corresponds to:
                        % Manifest list or Image manifest
                        manifestSha = regexp(cmdout, 'sha256:[a-f0-9]+', 'match', 'once');
                    end

                case 'file'
                    [status, cmdout] = system(['docker load --input ' imageSource]);
                    if status == 0
                        % If new or existent image, Image name (or SHA256 for nameless image) is returned in output
                        token = regexp(cmdout, '[a-z0-9._-]+:[a-zA-Z0-9._-]+', 'match', 'once');
                        parts = strsplit(token, ':');
                        if strcmp(parts{1}, 'sha256') && ~isempty(regexp(parts{2}, '^[a-f0-9]+$', 'once'))
                            manifestSha = token;
                        else
                            [~, imageListNew] = GetImages();
                            manifestSha = imageListNew{strcmpi(imageListNew(:,1), token), 3};
                        end
                    end
            end
            if status ~= 0
                errMsg = cmdout;
                return
            end
            % Get image SHA from its Manifest list or Image manifest
            [~, imageListNew] = GetImages();
            iImage = find(strcmpi(imageListNew(:,3), manifestSha));
            if ~isempty(iImage)
                imageSha = imageListNew{iImage,2};
            else
                imageSha = manifestSha;
            end

            % Tag image
            if status == 0 && ~isempty(imageTag)
                % Find newly added image by its Image ID
                iOld = find(strcmpi(imageListOld(:,2), imageSha));
                iNew = find(strcmpi(imageListNew(:,2), imageSha));
                % Tag image
                [status, cmdout] = system(['docker tag ', imageSha, ' ', imageTag]);
                % Keep only the tag image IF the image was added in this call to ImportImage()
                if status == 0 && (length(iNew) - length(iOld)) == 1
                    if ~isempty(imageListOld)
                        [imageDel, iNew] = setdiff(imageListNew(iNew, 1), imageListOld(iOld, 1));
                    else
                        imageDel = imageListNew{iNew, 1};
                    end
                    if ~strcmpi(imageDel, '<none>:<none>')
                        [status, cmdout] = system(['docker rmi ', imageListNew{iNew, 1}]);
                    end
                end
            end
            if status ~= 0
                errMsg = cmdout;
                return
            end
    end
end


%% ===== RUN CONTAINER AS DAEMON =====
function errMsg = RunContainer(containerName, imageSha, volumes, isDaemon, containerArgs)
% USAGE: errMsg = bst_containers('RunContainer', containerName, imageSha, volumes, isDaemon, containerArgs)
    % Validate inputs
    if nargin < 5 || isempty(containerArgs)
        containerArgs = '';
    end
    if nargin < 4 || isempty(isDaemon)
        isDaemon = 0;
    end
    if nargin < 3 || ~iscell(volumes) || size(volumes,2) ~=2
        volumes = [];
    end

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Create volumes pairs
    volumesStr = '';
    if ~isempty(volumes)
        nPairs = size(volumes, 1);
        pairs = cell(nPairs, 1);
        for iPair = 1 : nPairs
            pairs{iPair} = ['-v ' volumes{iPair, 1} ':' volumes{iPair, 2}];
        end
        volumesStr = strjoin(pairs, ' ');
    end

    % Use GPU with container engine
    gpuStr = '';
    if bst_get('ContainerUseGpu') && system('which nvidia-smi') == 0
        gpuStr = '--gpus all';
    end

    % Run container
    switch engineName
        case 'docker'
            if ~isDaemon
                % Run ENTRYPOINT
                cmdStr = sprintf('docker run --rm --name %s %s %s %s %s', containerName, gpuStr, volumesStr, imageSha, containerArgs);
            else
                % Replace ENTRYPOINT (if any) with `sleep infinity`
                cmdStr = sprintf('docker run -d --name %s %s %s --entrypoint sleep %s infinity', containerName, gpuStr, volumesStr, imageSha);
            end
            [status, cmdout] = system(cmdStr);
    end
    if status ~= 0
        errMsg = cmdout;
    end
end


%% ===== EXECUTE COMMAND IN CONTAINER =====
function [errMsg, cmdout] = ExecInContainer(containerName, cmdStr)
    cmdout = '';

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end
    % Check if container is running
    [errMsg, containerInfo] = GetContainerInfo(containerName);
    if ~isempty(errMsg) || ~containerInfo.isRunning
        return
    end

    % Flag to track interruption
    processState = containers.Map({'isInterruptCleanup'}, {1});
    % Clean up on function end, errors or Ctrl+C is pressed
    cleanupObj = onCleanup(@() ProcessInterrupted(containerName, processState));
    % Run command
    switch engineName
        case 'docker'
            if ispc
                commandWrapper = '"';  % Double quote
            else
                commandWrapper = ''''; % Single quote
            end
            % Execute the running container
            commandExec = ['docker exec ' containerName ' sh -c ' commandWrapper cmdStr commandWrapper];
            [status, cmdout] = system(commandExec, '-echo');
            if status ~= 0
                errMsg = strtrim(cmdout);
            end
    end
    % Code in container ended normally
    processState('isInterruptCleanup') = 0;
end


%% ===== CHECK CONTAINER STATUS =====
function [errMsg, containerInfo] = GetContainerInfo(containerName)
% [containerNameOut, isRunning, volumePairs, imageSha]
    containerInfo = struct();
    containerInfo.name      = '';
    containerInfo.isRunning =  0;
    containerInfo.volumes   = [];
    containerInfo.imageSha  = '';

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Search for existent container with the same name and image reference
    switch engineName
        case 'docker'
            % Find containers with same name
            [status, cmdout] = system(['docker inspect ' containerName ' --format "{{.Name}}"']);
            if status ~= 0
                errMsg = strtrim(cmdout);
                return
            end
            containerInfo.name = strrep(strtrim(cmdout), '/', '');
            [status, cmdout] = system(['docker inspect ' containerName ' --format "'...
                '{{.State.Status}} # {{.HostConfig.Binds}} # {{.Image}}"']);
            if status ~= 0
                errMsg = strtrim(cmdout);
                return
            end
            cmdout = strsplit(strtrim(cmdout), '#');
            containerInfo.isRunning = strcmpi('running', strtrim(cmdout{1}));
            volumes = regexprep(strtrim(cmdout{2}), '^\[|\]$', '');
            volumes = regexprep(volumes, ':\', ';\');
            volumePairs = strsplit(volumes, ':');
            volumePairs = cellfun(@(x) regexprep(x, ';\', ':\'), volumePairs, 'UniformOutput', 0);
            containerInfo.volumes = reshape(volumePairs, 2, [])';
            tokens = regexp(cmdout{3}, 'sha256:[a-f0-9]+', 'match');
            containerInfo.imageSha = strtrim(tokens{1});
    end
end


%% ===== STOP CONTAINER =====
function errMsg = StopContainer(containerName, isForce)
    % Validate inputs
    if nargin < 2 || isempty(isForce)
        isForce = 0;
    end

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Stop container
    switch engineName
        case 'docker'
            if ~isForce
                % Stop and remove
                [status, cmdout] = system(['docker stop ' containerName ' && docker rm ' containerName]);
            else
                % Kill
                [status, cmdout] = system(['docker rm -f ' containerName]);
            end
            if status ~=0
                errMsg = strtrim(cmdout);
            end
    end
end


%% ===== REMOVE IMAGE =====
function errMsg = RemoveImage(imageSha, isForce)
    % Validate inputs
    if nargin < 2 || isempty(isForce)
        isForce = 0;
    end

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Remove image
    switch engineName
        case 'docker'
            if ~isForce
                % Remove image
                [status, cmdout] = system(['docker rmi ' imageSha]);
            else
                % Force remove image
                [status, cmdout] = system(['docker rmi -f ' imageSha]);
            end
            if status ~=0
                errMsg = strtrim(cmdout);
            end
    end
end


%% ===== PROCESS INTERRUPTED =====
function ProcessInterrupted(containerName, processState)
    if processState('isInterruptCleanup')
        bst_plugin('Unload', regexprep(containerName, '^bst_', ''));
        bst_error('The process running in the container was interrupted', 'Container', 0);
    end
end


%% ===== GET ONLINE MANIFEST DIGEST =====
function [errMsg, manifestSha] = GetOnlineManifest(imageSource)
    manifestSha = '';

    % Check status of default container engine
    [errMsg, engineName] = GetEngine(bst_get('ContainerEngine'));
    if ~isempty(errMsg)
        return
    end

    % Get Manifest list or Image manifest
    switch engineName
        case 'docker'
            [status, cmdout] = system(['docker buildx imagetools inspect ' imageSource ' --format "{{.Manifest}}"']);
            if status == 0
                % Digest
                manifestSha = regexp(cmdout, 'sha256:[a-f0-9]+', 'match', 'once');
            end
    end
    if status ~= 0
        errMsg = strtrim(cmdout);
        return
    end
end


For additional help, please consult the Brainstorm Forum

-  ⇤ ← Revision 2 as of 2026-02-09 07:25:30 → 
  Size: 4736
  Editor: TakfarinasMedani
  Comment:
+   ← Revision 8 as of 2026-04-29 20:57:37 → ⇥
  Size: 2605
  Editor: RaymundoCassani
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-= Using Containers with Brainstorm =
Authors: Takfarinas Medani & Malte Höltershinken
+= Containers with Brainstorm =
''Authors: Takfarinas Medani, Malte Höltershinken, and Raymundo Cassani''
 Line 4:
-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.
+Some Brainstorm functions and plugins rely on external software that is distributed as containers (for example: ''duneuro 2026''). These containers are managed in Brainstorm as '''container''' plugins.
 Line 6:
-This page explains how to install a supported container runtime on your system.
+{{{#!wiki note
Container plugins are not usually installed alone, their installation is commonly as a dependency for a code plugin.
}}}
-Line 8:
+Line 10:
-<<TableOfContents(3)>>
+This page explains how containers are used by Brainstorm, and how set up your system to use them.
-Line 10:
+Line 12:
+<<TableOfContents(2,2)>>
-Line 11:
+Line 14:
-== Containers for beginners ==
'''What is a container?'''
+== Introduction ==
-Line 23:
+Line 24:
-You do ''not'' need prior knowledge of containers to use Brainstorm.
+You do ''not'' need prior knowledge of containers to use Brainstorm. {{attachment:bstContainer.jpg}}
-Line 25:
+Line 26:
-----
+To be able to use containers with Brainstorm it is necessary to have a supported container engine.
-Line 27:
+Line 28:
-== Supported container runtimes ==
Brainstorm supports the following container runtimes:
+== Container engines ==
Brainstorm supports the following container engines:
-Line 30:
+Line 31:
- * '''Docker''' (recommended for most users)
 * '''Podman''' (Linux alternative to Docker)
 * '''Apptainer / Singularity''' (recommended on HPC clusters)
+ * '''Docker Desktop''' (recommended for most users)
 * TODO '''Podman''' (Linux alternative to Docker)
 * TODO '''Apptainer / Singularity''' (recommended on HPC clusters)
-Line 36:
+Line 37:
-You only need to install '''one''' of them.
+You need to install at least '''one''' of them.
-Line 38:
+Line 39:
-----
+=== Docker Desktop (recommended) ===
-Line 40:
+Line 41:
-== Which runtime should I install? ==
||'''Operating system''' ||'''Recommended runtime''' ||
||Windows ||Docker Desktop ||
||macOS ||Docker Desktop ||
||Linux (desktop) ||Docker or Podman ||
||Linux (HPC) ||Apptainer / Singularity ||
+To install, be sure of follow the instructions for your OS: <<BR>>
 https://docs.docker.com/desktop/
-Line 48:
+Line 45:
-----
+== Interactive management ==
SHOW THE GUI FOR CONTAINER PLUGINS
-Line 50:
+Line 48:
-== Windows ==
=== Docker Desktop (recommended) ===
 1. Download Docker Desktop:
  . [[https://docs.docker.com/desktop/|Docker Desktop documentation]]
+== Command-line management ==
The calls to install or manage containers plugins are the same than for (code) plugins, see the [[https://neuroimage.usc.edu/brainstorm/Tutorials/Plugins#Command-line_management|plugin tutorial]].
-Line 55:
+Line 51:
-. During installation:
  * Enable '''WSL 2''' if prompted
  * Restart your computer if required
+An API for low-level interaction between Brainstorm and the container engine has been implemented in `bst_containers.m`
-Line 59:
+Line 53:
-. Start '''Docker Desktop''' and wait until it reports that Docker is running
+<<HTML(<div    style="border:1px solid black;  background-color:#EEEEFF;  width:720px;   height:400px; overflow:scroll;  padding:10px;  font-family:   Consolas,Menlo,Monaco,Lucida  Console,Liberation  Mono,DejaVu Sans   Mono,Bitstream Vera Sans  Mono,Courier  New,monospace,sans-serif;   font-size: 13px; white-space:  pre;">)>><<EmbedContent("https://neuroimage.usc.edu/bst/viewcode.php?core=bst_containers.m")>><<HTML(</div >)>>
-Line 61:
+Line 55:
-No additional configuration is required for Brainstorm.

----

== macOS ==
=== Docker Desktop (recommended) ===
 1. Download Docker Desktop:
  . [[https://docs.docker.com/desktop/|Docker Desktop documentation]]

 1. Install and launch Docker Desktop
 1. 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]]
+For additional help, please consult the [[https://neuroimage.usc.edu/forums/|Brainstorm Forum]]

Software

Users

Development