Configuration of BrainVISA

_images/cort_install.png

BrainVisa now normally runs inside a virtual machine or a virtual container. It does not change “much” on how to use it, but there are a few things to know about it, and this situation also needs a few special configuration considerations.

Using VirtualBox

Home directory

A virtual machine has its own system, and its own users.

Mount points

Using Apptainer

Home directory

A container has its own system, and its own users. But it’s possible to use the same user identifier as on the host system. In BrainVISA containers, the bv command reuses the calling user identifier. But for several reasons we chose to use a separate home directory. In summary it’s the same user, but a different home directory and different configuration files.

Advantages:

  • The user can use the host system data and files, and write data with the same access rights and identifier

  • Configuration files (like Unix .bash_profile and .bashrc files) are not shared, because they may contain items specific to the host sytem which would produce confusion, like PATH pointing to incompatible programs.

Drawbacks:

  • Some of the account configuration would benefit from being shared, but thus is not. For instance ssh configuration and personal keys are not shared by default. See SSH keys.

Mount points

The container is a virtually separate machine from the host system. It does not see the same files and directories tree as the host system. In order to allow access to files (especially data to be processed) on the host filesystems, the container should be configured to mount the wanted directories.

The bv program invoked without arguments will start a configuration user interface which allows to add mount points to the BrainVisa installation.

SSH keys

SSH configuration is stored on Unix systems in a directory $HOME/.ssh. This directory the the files there have restricted access permissions in order to ensure the confidentiality and security of the connections. It is not recommended, in a general way, to copy the private keys there to another location, even the container local home directory. Symbolic links are rejected by ssh for security reasons.

The solution is to use a ssh agent. The agent is not persistent, it has to be started on the host system by some mechanism (session manager, bash_profile…). We use keychain (sudo apt-get install keychain), which starts the agent for you and is able to reuse it in all sessions. We have something along these lines in ~/.profile:

eval $(keychain --eval --agents ssh id_rsa 2> /dev/null)

The needed socket and environment variable pointing to it ($SSH_AUTH_SOCK) will be automatically mounted and setup by the bv command.

Matlab

Matlab is generally installed on the host system and not in a container. In many laboratories Matlab is installed using a network install, and a license manager server. If Matlab has been installed for Linux in such a network, it is still possible to use it from the container.

In order to run MATLAB in the container, we need to:

  • mount the directory where MATLAB is installed;

  • mount/copy the licence file and/or set the MLM_LICENSE_FILE and LM_LICENSE_FILE environment variables.

    Alternately, the user may just make the .matlab config files appear in the local container home directory. From the container shell, do:

    mkdir ~/.matlab
cd ~/.matlab
ln -s $CASA_HOST_HOME/.matlab/R*_licenses/ .

Other external software

The BrainVISA framework is able to use several external neuroimaging software. Such software can be used from the container system, as soon as they have been installed for a compatible architecture (Linux) and can be run from a “normal” system of the same type as the container (Ubuntu 18.04 for this release), and they paths have been configured in BrainVISA, just like we did in former BrainVISA versions nor running in containers.

Namely, SPM (either standalone or using Matlab when it is configured), FSL, Freesurfer and other software can be used normally.

Parallel and distributed execution

Brainvisa is using Soma-Workflow to perform distributed processing.

The documentation of Soma-Workflow contains a section explaining how to use it in a container, both to run the server and to run BrainVisa software inside containers in jobs.