Using Containers with Brainstorm

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

THIS PAGE IS DEPRECATED, AND WILL REDIRECT TO THE MAIN PAGE FOR CONTAINER:

https://neuroimage.usc.edu/brainstorm/Tutorials/Containers

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.

Contents

Containers for beginners
Supported container runtimes
Which runtime should I install?
Windows
macOS
Linux (desktop or workstation)
Linux (HPC clusters)
Container images in Brainstorm
Frequently Asked Questions
Summary
Command-line management

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.

Note: Docker requires a running daemon (a background service).

Podman and Apptainer do not.

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)

Download Docker Desktop:
- Docker Desktop documentation
During installation:
- Enable WSL 2 if prompted
- Restart your computer if required
Start Docker Desktop and wait until it reports that Docker is running

No additional configuration is required for Brainstorm.

macOS

Docker Desktop (recommended)

Download Docker Desktop:
- Docker Desktop documentation
Install and launch Docker Desktop
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: 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: 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

singularity version

If Apptainer is not available, please contact your system administrator or consult: 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: Brainstorm Forum

Command-line management

The calls to install or manage plugins are all documented in the header of bst_plugin.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


Software

Users

Development

Using Containers with Brainstorm

Containers for beginners

Supported container runtimes

Which runtime should I install?

Windows

Docker Desktop (recommended)

macOS

Docker Desktop (recommended)

Linux (desktop or workstation)

Option 1: Docker

Option 2: Podman

Linux (HPC clusters)

Apptainer / Singularity (recommended)

Container images in Brainstorm

Frequently Asked Questions

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

Docker is installed but Brainstorm says it is not running

I don’t have administrator rights on my computer

Are containers slower than native installations?

Summary

Command-line management

Feedback on the documentation (typos, unclear sections, missing information)
For questions, bug reports, and feature requests, please use the Brainstorm Forum.

Email address (if you expect an answer):