Casa-Distro quickstart

This page contains informations to quickly and simply install the BrainVISA software distribution through container images and an embedded casa-distro inside them.

If you are a developper looking for more details about casa-distro and its installation, you can follow the first steps here to install casa-distro, but skip the casa_distro setup step, then follow the instructions in Developping in the Casa-Distro BrainVISA environment.

What is Casa-Distro ?

Casa-Distro is a cross-paltform ready-to-use environment which is used to install BranVisa and CATI environment. It avoids manual installation of required softwares and librairies.

This is possible by the use of virtualization technology to create a virtual applicance.

Casa-Distro supports a container technology, Singularity and a virtual machine technology : VirtualBox.

Support and installation instructions matrix

  Singularity VirtualBox
Linux ✓ ✓
Windows (✓ (1)) ✓
Mac OS ✓ (2) ✓ (3)

Installation with singularity

To use Casa-Distro with singularity, a user must have a system with the following characteristics:

  • Singularity v3 must be installed and setup for the use on the building system. To install Singularity on Debian based Linux systems (such as Ubuntu),

  • Download the BrainVISA image found in http://brainvisa.info/casa-distro/releases/singularity/. It’s a .sif file, for instance brainvisa-5.0.0.sif. Download it in a “safe” place where it can be reused, typically in a directory casa_distro on your home directory.

  • Create an installation directory for the environment:

    mkdir $HOME/casa_distro/brainvisa-5.0.0

  • Execute the container image it using Singularity, with an option to tell it to run its setup procedure. The installation directory should be passed:

    singularity run -B $HOME/casa_distro/brainvisa-5.0.0:/casa/setup $HOME/casa_distro/brainvisa-5.0.0.sif

  • Python >= 2.7 is necessary to run the bv command. Python is usually installed on most Linux distributions. To check its installation, open a terminal and type: python (you can leave the interpreter using <ctrl>-D or by typing exit(). If it is not installed, do it (https://python.org).

  • set the bin/ directory of the environment installation directory in the PATH environment variable of your host system config, typically in $HOME/.bashrc or $HOME/.bash_profile if you are using a Unix Bash shell:

    export PATH="$HOME/casa_distro/brainvisa-5.0.0/bin:$PATH"

  • Optionally, you may want to run the configuration GUI, through the bv program: as programs are actually running in a container or a virtual machine (transparently), the user may have to configure additional mount points to actually see his data and working directories from his host machine in the container. This is done graphically, simply using:

    bv

  • Installation is finished, you can run programs from the container.

    There are several ways actually:

    1. The simplest way, call commands directly from the above PATH like if they were on the host machine:

      # run programs
AimsFileInfo --info
anatomist
brainvisa
    1. Using bv interface to containers or casa_distro:

    The bv program is found in each environment bin directory in order to be always compatible with this environment.

    • The bv command accepts an executable program name as sub-command, it allows to run programs installed inside the container, for instance:

      bv brainvisa
bv anatomist
bv AimsFileInfo -h

      or to open an interactive shell in the container:

      bv bash

      More options may be used. See the complete documentation of the bv command.

      Technically, bv is a simplified version of casa_distro which is contained inside a single environment (distribution installation) and only allows to run and configure this environment.

    • The casa_distro command accepts run or shell as sub-commands, they both allow to run programs installed inside the container, for instance:

      casa_distro run brainvisa
casa_distro run anatomist
casa_distro run AimsFileInfo -h
casa_distro shell

      Compared to bv, casa_distro allows to handle multiple environments (distribution installations) via parameters, and allows to setup (download/install) or remove environments or container images.

      More options may be used. See the complete documentation of the casa_distro command.

      Note that bv is made available inside each environment (distribution installation) and makes an installation self-contained (it doesn’t depend on a global host installation of bv outside of the environment directory), whereas casa_distro is cross-environments and thus needs to be installed on the host system. Note also that bv still depends on Python which still needs to be installed and working on the host machine.

  • If you are using casa-distro using Singularity or Docker containers, graphical software need to run the containers with a graphical “bridge”: a X server has to be running on the host system, and OpenGL may or may not work. The options gui=yes and opengl of casa_distro try to handle common cases, possibly using Nvidia proprietary OpenGL implementation and drivers from the host system.

    Note that the option gui=yes is now the default, thus it is not needed.

    • On MacOS: MacOS includes its own, XQuartz (which needs some setup).
    • On Windows an external X server software has to be installed.

    For OpenGL, rendering problems may differ between docker and singularity. We tried to handle some of them in the options passed to containers by casa_distro with gui active, but some additional options / tweaking may be helpful. See the OpenGL troubleshooting section for details.

  • see the Troubleshooting section, especially the OpenGL troubleshooting, Singularity on Mac and Singularity on Windows subsections.

  • If you want to develop software using the Casa-Distro / BrainVISA environment, read the Developping in the Casa-Distro BrainVISA environment section.

Installation with VirtualBox

To use Casa-Distro with VirtualBox

  • VirtualBox must be installed for the user of the system.

  • Download a VirtualBox image from http://brainvisa.info/casa-distro/releases/vbox/

  • start virtualbox

  • in VirtualBox, import the downloaded image - some configuration (memory, CPU, video, sound etc) may be useful for it in VirtualBox.

  • some mount points to the host filesystem can be added to see the host filesystem directories from the VM.

  • start it

  • in the running Linux virtual machine, BrainVISA is installed and configured. You can open a terminal and type:

    AimsFileInfo -h
brainvisa
anatomist

The virtual machine has a configured user named “brainvisa”, with the password “brainvisa”, which has sudo (admin) permissions.