It is meant to be used from outside a container, and runs commands inside a
container.

Used without parameter, it starts a graphical interface
allowing the configuration of the environment.

optional arguments:
-h, --help     show this help message and exit
-v, --verbose

Currently bv is just a shorthand to the "casa_distro run" command, and follows
the same syntax and options. In the future it will change to more
"conventional" arguments syntax (say, "--opengl container" instead of
"opengl=container").

Currently bv is just a shorthand to the “casa_distro run” command, and follows
“conventional” arguments syntax (say, “–opengl container” instead of
“opengl=container”).

Creation and publication of casa-distro releases and container images.

Casa_distro is the BrainVISA suite distribution swiss knife.
It allows to setup a virtual environment and launch BrainVISA software.
See http://brainivsa.info/casa-distro and
https://github.com/brainvisa/casa-distro for more information

See 

casa_distro_admin <general options> <command> [<command parameters>...]

general optional arguments:
-v, --verbose   Display as much information as possible.
--version       Display casa-distro version number and exit.
-h, --help      Display help message and exit.
                If used after command name, display only the help of this
                command.

Display help message and exit.
If used after command name, display only the help of this
command.

command.

Many subcommands need :ref:`environment` selection specifications: :ref:`see the documentation on how to specify an environment <environment_options>`.

:ref:`see the documentation on how to specify an environment <environment_options>`

base_directory
default= ``$HOME/casa_distro``

Directory where images and environments are stored. This parameter
can be passed on the commandline, or set via the
``CASA_BASE_DIRECTORY`` environment variable.

format
format help text in a given text format. Valid values are "text"
(default) for raw text, or rst (RST/sphinx format).

format help text in a given text format. Valid values are “text”

full
if ``true`` or ``yes`` or ``1``, display each subcommand parameters
documentation in the general help.

, display each subcommand parameters

Create a Debian package to install Singularity.
Perform the whole installation process from a rw system and Singularity
source. Then put the result in a ``*.deb`` file.

source. Then put the result in a 

dockerhub:
default=ubuntu:20.04

Name of the base image system to pull from DockerHub.

output_dir:
default=/casa/host/src/development/casa-distro/5.1/doc/source

Location of the resulting Debian package file.

version:
default=3.8.3

Version of Singularity to use. This must be a valid release version.
Go language is not included in the final package.

For Singularity you need to run these commands in order to create the
casa-system image::

    cd "$CASA_BASE_DIRECTORY"
    singularity pull ubuntu-18.04.sif docker://ubuntu:18.04

Then you can directly use the ubuntu image as base for the run image. You
may build a "system" image as follows, but it's not needed::

    casa_distro_admin create_base_image base=ubuntu-18.04.sif \
        type=system image_version=5.0

casa-system image:

cd "$CASA_BASE_DIRECTORY"
singularity pull ubuntu-18.04.sif docker://ubuntu:18.04

may build a “system” image as follows, but it’s not needed:

casa_distro_admin create_base_image base=ubuntu-18.04.sif \
    type=system image_version=5.0

For VirtualBox:

1. Download a Ubuntu image to your CASA base directory, e.g.
   lubuntu-22.04.1-desktop-amd64.iso

2. Run create_user_image::

    casa_distro_admin create_user_image \
        container_type=vbox \
        type=system \
        base=lubuntu-22.04.1-desktop-amd64.iso \
        image_version=5.3

3. Follow the instructions that are printed in the terminal to install
   and configure Lubuntu appropriately.

Download a Ubuntu image to your CASA base directory, e.g.
lubuntu-22.04.1-desktop-amd64.iso

Run create_user_image::

 casa_distro_admin create_user_image \
     container_type=vbox \
     type=system \
     base=lubuntu-22.04.1-desktop-amd64.iso \
     image_version=5.3

casa_distro_admin create_user_image \
    container_type=vbox \
    type=system \
    base=lubuntu-22.04.1-desktop-amd64.iso \
    image_version=5.3

Follow the instructions that are printed in the terminal to install
and configure Lubuntu appropriately.

type
type of image to publish. Either "system" for a base system image, or
"run" for an image used in a user environment, or "dev" for a developer
image.

image.

type of image to publish. Either “system” for a base system image, or
“run” for an image used in a user environment, or “dev” for a developer
image.

:ref:`name <env_name>`
default=casa-{type}-{image_version}

If given, select environment by its name. It replaces type, distro,
branch and system and is shorter to select one.

base
Source file used to build the image. The default value depends on image
type and container type.

output
default=/casa/home/casa_distro/{name}.{extension}

File location where the image is created.

container_type
default=singularity

Type of virtual appliance to use. Either "singularity", "vbox" or
"docker".

"docker".

Type of virtual appliance to use. Either “singularity”, “vbox” or
“docker”.

verbose
default=True

Print more detailed information if value is ``yes``, ``true`` or ``1``.

cleanup (effective only if container_type=singularity)
default=yes

If "no", "false" or "0", do not cleanup after a failure during image
building. This may allow to debug a problem after the failure. For
instance, with Singularity one can use a command like::

    sudo singularity run --writable
    /tmp/rootfs-79744fb2-f3a7-11ea-a080-ce9ed5978945 /bin/bash

If “no”, “false” or “0”, do not cleanup after a failure during image
instance, with Singularity one can use a command like:

sudo singularity run --writable
/tmp/rootfs-79744fb2-f3a7-11ea-a080-ce9ed5978945 /bin/bash

force (allowed only if container_type=singularity)
default=no

If ``yes``, ``true`` or 1, erase existing image without asking any
question.

question.

fakeroot (allowed only if container_type=singularity)

If ``yes``, ``true`` or 1, use singularity --fakeroot for building the
images (this is the recommended wby). Otherwise, "sudo singularity"
must be used so singularity has root access on the host.

 or 1, use singularity –fakeroot for building the
images (this is the recommended wby). Otherwise, “sudo singularity”

memory (allowed only if container_type=vbox)
default=8192

Size in MiB of memory allocated for virtual machine.

video_memory (allowed only if container_type=vbox)
default=50

Size in MiB of video memory allocated for virtual machine.

disk_size (allowed only if container_type=vbox)
default=131072

For vbox container type only. Size in MiB of maximum disk size of
virtual machine.

gui (allowed only if container_type=vbox)

For vbox container type only. If value is "yes", "true" or "1", display
VirtualBox window.

For vbox container type only. If value is “yes”, “true” or “1”, display

This directory location can be customized with
the following environment variables::

the following environment variables:

BRAINVISA_PUBLISH_LOGIN (default=brainvisa)
BRAINVISA_PUBLISH_SERVER (default=brainvisa.info)
BRAINVISA_PUBLISH_DIR (default=/var/www/html/brainvisa.info_download)

:ref:`image`
Force usage of a specific virtual image instead of the one defined
in the environment configuration.

"docker".

"docker".

“docker”.

verbose

Create a "user" image given a development environment.
The development environment is selected among existing ones its
distro and system or simply by its name. Only development environments
using the master branch are considered.
This command can perform three steps. Each step can be ignored by setting
the corresponding option to "no" :

Create a “user” image given a development environment.
the corresponding option to “no” :

install: perform an installation of the development environment into its
installation directory. This modify the development environment by
updating its installation directory.

generate: generate a new image for the development environment. The new
image is based on base_image and the installation directory of the
development environment is copied into the image in /casa/install.

name
default={distro}-{version}
Name given to the created image.

base_image
default={base_directory}/casa-run-{image_version}{extension}
Name of the "run" image used to generate the new user image

Name of the “run” image used to generate the new user image

:ref:`distro`
default=None

If given, select environment having the given distro name.

:ref:`branch`

If given, select environment having the given branch.

:ref:`system`

If given, select environments having the given system name.

:ref:`image_version`

If given, select environments having the given image version.

"docker".

"docker".

“docker”.

output
default={base_directory}/{name}{extension}
Path of the output image.

force
If "yes", "true" or 1, erase existing image without asking any
question.

question.

If “yes”, “true” or 1, erase existing image without asking any
question.

install
If "true", "yes" or "1", perform the installation steps:
'make install-runtime', as well as 'make install-doc' and
'make install-test', depending on the install_doc and install_test
parameters.
If "false", "no" or "0", skip all installation steps

If “true”, “yes” or “1”, perform the installation steps:
‘make install-runtime’, as well as ‘make install-doc’ and
‘make install-test’, depending on the install_doc and install_test
If “false”, “no” or “0”, skip all installation steps

install_doc
If "true", "yes" or "1", run 'make install-doc' as part of the install
step.
If "false", "no" or "0", skip this step

step.

If “true”, “yes” or “1”, run ‘make install-doc’ as part of the install
step.
If “false”, “no” or “0”, skip this step

install_test
If "true", "yes" or "1", run 'make install-test' as part of the install
step.

step.

If “true”, “yes” or “1”, run ‘make install-test’ as part of the install
step.

install_thirdparty
default=none
If "none", no third-party software is installed in the image. If
"all", all available software will be installed during the ``generate``
step. If "default", a default list of software will be installed. If
starting with "file://", then the thirdparty install list will be read
from a JSON file. Other values are understood as a list of software
("spm12-standalone,freesurfer"). Each will be installed from their host
system location into ``/usr/local`` on the container image. Software
location will be searched in a small search list (/usr/local,
/drf/local, /i2bm/local). If installed in another location, this
location may be passed after a ``=`` sign in the software name, ex:
``spm12-standalone=/opt/spm,freesurfer``.
If a JSON file is used, then the file syntax is a dictionary, keys are
thirdparty software names ("spm12-standalone"), and values are
directories. If default locations are expected, then the value may be
null.

null.

If “none”, no third-party software is installed in the image. If
“all”, all available software will be installed during the 

step. If “default”, a default list of software will be installed. If
starting with “

”, then the thirdparty install list will be read
(“spm12-standalone,freesurfer”). Each will be installed from their host
system location into 

 on the container image. Software
location may be passed after a 

.
thirdparty software names (“spm12-standalone”), and values are
null.

generate
If "true", "yes" or "1", perform the image creation step.

If “true”, “yes” or “1”, perform the image creation step.

cleanup
If "false", "no" or "0", do NOT clean up the temp image during the
generate step after failed build, can be helpful for debugging

If “false”, “no” or “0”, do NOT clean up the temp image during the

zip
If "true", "yes" or "1", zip the installed files for an "online"
installation.

If “true”, “yes” or “1”, zip the installed files for an “online”

In BrainVISA Build Infrastructure (BBI), the ``casa_distro_admin
bbi_daily`` command orchestrates automated builds and tests in a given
*base directory*. The ``bbi_daily`` command will run the following steps,
while (optionally) logging detailed output to a Jenkins server. See
:doc:`nightly` for a complete introduction to automated tests.

 command will run the following steps,

Self-update casa_distro using 'git pull' and restart itself for the next
steps

Self-update casa_distro using ‘git pull’ and restart itself for the next
steps

Select *dev* environments based on the provided filters (distro, branch,
system, image_version, name)

 environments based on the provided filters (distro, branch,

Update casa-dev and casa-run images used by the selected environments to
the latest version available from the BrainVISA website

For every selected *dev* environment, perform the following tasks:

1. ``bv_maker sources``
2. ``bv_maker configure``
3. ``bv_maker build``
4. ``bv_maker doc``
5. perform all tests in the *dev* environment (running the same commands
   as ``bv_maker test``)
6. create or update a user image with ``casa_distro_admin
   create_user_image`` (i.e. install the compiled software in a new
   *user image* based on the ``casa-run`` image, where the software is
   installed under ``/casa/install``)
7. install that user image into  a fresh *user* environment (reference
   test data are automatically linked from the *dev* environment)
8. perform all tests in that *user* environment

perform all tests in the *dev* environment (running the same commands
as ``bv_maker test``)

create or update a user image with ``casa_distro_admin
create_user_image`` (i.e. install the compiled software in a new
*user image* based on the ``casa-run`` image, where the software is
installed under ``/casa/install``)

install that user image into  a fresh *user* environment (reference
test data are automatically linked from the *dev* environment)

 environment (reference
test data are automatically linked from the 

The process can be controlled with the command-line options described
below, as well as some configuration keys that can be added to the
``casa_distro.json`` of each dev environment:

``ctest_options``: list of command-line options to pass to ``ctest`` on
the command-line. ``ctest`` is used for listing the tests, so you may
pass filtering options to restrict the set of tests being run (e.g.
``["-R", "disco"]``).

 is used for listing the tests, so you may

``bbi_user_config``: an optional dictionary for customizing the creation
of a the user image and the user environment, where tests of the user
image will be run. This dictionary can contain these keys:

- ``name``: the name of the environment where the user image will be set
  up. Default: ``dev_config['name'] + '-userimage'``
- ``directory``: the full path where the user environment will be set up.
  **Warning: this directory is erased every time ``bbi_daily`` is run.**
  Default: ``{base_directory} + name``
- ``image``: the full path where the user image will be created.
  Default: ``{base_directory} + name + extension``
- ``version``: the version string that will be set in the user image,
  e.g. available as the ``CASA_VERSION`` environment variable and as the
  ``version`` metadata key. This value ``version`` is passed to
  :func:`time.strftime`. Default: ``'%Y-%m-%d'``.
- ``setup_commands``: list of shell commands that will be run in the
  newly created user environment. May be used to run post-setup tasks,
  such as configuring additional files in the home directory of the user
  (e.g. configuring MATLAB licences...).

: an optional dictionary for customizing the creation

``name``: the name of the environment where the user image will be set
up. Default: ``dev_config['name'] + '-userimage'``

: the name of the environment where the user image will be set
up. Default: 

``directory``: the full path where the user environment will be set up.
**Warning: this directory is erased every time ``bbi_daily`` is run.**
Default: ``{base_directory} + name``

Warning: this directory is erased every time ``bbi_daily`` is run.

``image``: the full path where the user image will be created.
Default: ``{base_directory} + name + extension``

``version``: the version string that will be set in the user image,
e.g. available as the ``CASA_VERSION`` environment variable and as the
``version`` metadata key. This value ``version`` is passed to
:func:`time.strftime`. Default: ``'%Y-%m-%d'``.

: the version string that will be set in the user image,
e.g. available as the 

``setup_commands``: list of shell commands that will be run in the
newly created user environment. May be used to run post-setup tasks,
such as configuring additional files in the home directory of the user
(e.g. configuring MATLAB licences...).

: list of shell commands that will be run in the
(e.g. configuring MATLAB licences…).

jenkins_server
default = None
Base URL of the Jenkins server used to send logs (e.g.
https://brainvisa.info/builds). If none is given, logs are
written to standard output.

jenkins_auth
default = {base_directory}/jenkins_auth
Name of a file containing user name and password (can be a token)
to use to contact Jenkins server REST API. The file must have only
two lines with login on first line and password on second.

update_casa_distro
default = yes
If true, yes or 1, update casa_distro

update_base_images
Boolean indicating if the update images step must be done

bv_maker_steps
default = sources,configure,build,doc
Coma separated list of bv_maker commands to perform on dev
environments. May be empty to do nothing.

dev_tests
Boolean indicating if the tests must be performed on dev environments

update_user_images
Boolean indicating if images of user environment must be recreated

recreate_user_envs
Boolean indicating if user environments must be wiped and recreated
using singularity --bind <dir>:/casa/setup ...

using singularity –bind <dir>:/casa/setup …

user_tests
Boolean indicating if the tests must be performed on user environments

default = none
passed to "create_user_image" when update_user_images is true

passed to “create_user_image” when update_user_images is true

verbose

Run the installation procedure to create a run or dev image on the
local machine. Installation can be don step by step. This command
is typically used in a VirtualBox machine to debug image creation
scenario.

action

If not given, list the possible actions for the selected type and
indicate if they were done or not. Can have one of the following
values::

    "next": perform the nex action not already done
    "all": perform all action not already done
    coma separated list of acions:
        perform all selected actions even if they were already done

values::

values:

"next": perform the nex action not already done
"all": perform all action not already done
coma separated list of acions:
    perform all selected actions even if they were already done

version
default=*

Image version to use for searching an image builder file. This is
used as a shell pattern, the default value match any version.

log_file
default=/etc/casa_local_install.log

File where information about steps that have been performed is stored.

user
default=brainvisa

Name of the user account to use for non root commands.

default=docker

"docker".

convert_from

Convert from this container type. If not specified, take it from the
source container metadata.

#. **Create release plan:** selection of the software components that

are going to be upgraded in the next release of the distribution.

#. **Apply release plan:** update the version of generic branches

(*latest\_release*, *bug\_fix* and *trunk*) in the source code of all

#. **Compilation, testing and packaging:** creation of environments,

All these steps are done by CASA admin team using ``casa_distro`` command. The

release plan is discussed with distros managers and eventually modified before

being applied. The current status of the release plan can be found on a

`BioProj wiki page <https://bioproj.extra.cea.fr/redmine/projects/catidev/wiki/Release_plan>`_.

A casa-distro release is done by a member of the BrainVISA team using the ``casa_distro_admin`` command. This document contains all the steps that are necessary to build and publish all versions of casa-distro images.

A casa-distro release is done by a member of the BrainVISA team using the 

 command. This document contains all the steps that are necessary to build and publish all versions of casa-distro images.

The base VirtualBox image is a minimal configuration of a system image downloaded from internet as an ``*.iso`` file. It serves as starting point for the building of run and dev images. Once created, the image is published on BrainVISA website in the following URL ``http://brainvisa.info/casa-distro/casa-<iso_name>.ova`` where ``<iso name>̀`` is the name of the ``*.iso`` file of the distribution. For instance if one uses ``ubuntu-18.04.4-desktop-amd64.iso``, the uploaded image name would be ``casa-ubuntu-18.04.4-desktop-amd64.ova``.

The base VirtualBox image is a minimal configuration of a system image downloaded from internet as an 

 file. It serves as starting point for the building of run and dev images. Once created, the image is published on BrainVISA website in the following URL 

Download an Ubuntu iso file from internet (any Debian based distro may work but only recent Ubuntu LTS are tested).

Run `casa_distro_admin create_system` to create an empty VirtualBox image with appropriate base settings (e.g. enough maximum disk size)

 to create an empty VirtualBox image with appropriate base settings (e.g. enough maximum disk size)

Perform Ubuntu minimal installation with an autologin account named "brainvisa" and with password "brainvisa"

Perform Ubuntu minimal installation with an autologin account named “brainvisa” and with password “brainvisa”

Perform system updates and install kernel module creation packages :

Set root password to "brainvisa" (this is necessary to automatically connect to the VM to perform post-install)

Set root password to “brainvisa” (this is necessary to automatically connect to the VM to perform post-install)

Configure the VM in VirualBox (especially 3D acceleration, processors and memory)

In a general way, we designed casa-distro first using `Docker <https://www.docker.com>`_, and then extended it to `Singularity <https://www.sylabs.io/>`_. We use Singularity by actually converting Docker images, so images should be built first using Docker. So Docker is needed to build Singularity images for Casa-distro (this is not needed for regular users, which just download system images, and can use singularity alone, or docker alone).

. We use Singularity by actually converting Docker images, so images should be built first using Docker. So Docker is needed to build Singularity images for Casa-distro (this is not needed for regular users, which just download system images, and can use singularity alone, or docker alone).

Thus, to build a singularity image, one needs to use first ``casa_distro_admin create_docker``, then ``casa_distro_admin create_singularity``.

Images can be uploaded to a centralized place to allow other users to use them.

By default ``publish_docker`` will use `Docker Hub <https://hub.docker.com/>`_, which requires an account and access rights to push images.

Singularity did not have a public hub by the time we started casa-distro, so ``publish_singularity`` will push by default somewhere on the `BrainVISA web site <http://brainvisa.info>`_, which also requires to have access to the website account to push. We could use `Singularity Hub <https://singularity-hub.org/>`_ in the future.

Singularity did not have a public hub by the time we started casa-distro, so 

, which also requires to have access to the website account to push. We could use 

Downloading and updating images do not need any access rights, they are public.

*create_docker* may be used to update and rebuild the images which are proposed inside the *casa-distro* distribution, but this specific use has a limited benefit since they are normally pre-built and are downloaded from the hubs when needed.

 may be used to update and rebuild the images which are proposed inside the 

 distribution, but this specific use has a limited benefit since they are normally pre-built and are downloaded from the hubs when needed.

*create_docker* may prove useful however for an application designer who needs to ship specific or additional system packages in the images. In this situation a new image type needs to be designed.

 may prove useful however for an application designer who needs to ship specific or additional system packages in the images. In this situation a new image type needs to be designed.

New image types correspond to subdirectories which will looked for in the following directory trees (when they exist):

``<workflow_repository>`` is the main workflow repository either passed via the ``--repository`` option, or via the ``CASA_DEFAULT_REPOSITORY`` environment variable, or in the default location ``$HOME/casa_distro``

``<casa_builtin>`` if the builtin share directory of casa-distro (or its sources)

``<image_name>`` is a name (or type name) for the image, like the builtin ones ``casa-test``, ``casa-dev`` etc.

``<system>`` is the name of the system running inside the docker image (the builtin ones are ``ubuntu-18.04``, ``ubuntu-16.04``, ``ubuntu-14.04``, ``ubuntu-12.04``, ``centos-7.4``, ``windows-7-32``, ``windows-7-64``.

 is the name of the system running inside the docker image (the builtin ones are 

So custom, user-defined images can be added in a personal directory.
Such an image definition directory should contain at least two files:

``casa_distro_docker.yaml`` is a Yaml file definig dependencies, name and tags for the image. Ex:

 is a Yaml file definig dependencies, name and tags for the image. Ex:

dependencies:
    - ../../casa-dev
image_sources:
  - name: pytorch
    tags:
      - ubuntu-16.04
    visibility: public

a `Dockerfile <https://docs.docker.com/engine/reference/builder/>`_
The Dockerfile may (should) be based on another image, in the usual way of building docker images. Thus an existing casa-distro image can be the base for a new one.

Once an image is created with docker, it can be converted to singularity using ``casa_distro create_singularity``.

Once an image is created with docker, it can be converted to singularity using 

If you are a toolbox developer and want to share a modified BrainVISA distribution with your additional tools and dependencies in it, here is a recipe to build a singularity/apptainer image for your needs. You will need sudo permission on your host system to do so.

create the modified run image::

    sudo apptainer build -s casa-run-5.3-23 casa-run-5.3-23.sif
    sudo apptainer run -w casa-run-5.3-23 bash

in this bash, install whatever you need, like (just examples)::

    apt update
    apt install -y whatever
    pip3 install something_else
    cp -a /home/someone/my_additional_software /usr/local/
    ln -s /usr/local/my_additional_software/bin/* /usr/local/bin/

and so on. Then exit the container shell

sudo apptainer build -s casa-run-5.3-23 casa-run-5.3-23.sif
sudo apptainer run -w casa-run-5.3-23 bash

apt update
apt install -y whatever
pip3 install something_else
cp -a /home/someone/my_additional_software /usr/local/
ln -s /usr/local/my_additional_software/bin/* /usr/local/bin/

Optionally you can test the image with an existing dev environment, using::

    my_environment/bin/bv image=casa-run-5.3-23 bash

here, test the software you have installed etc. You can test brainvisa tools with the "bv_env" wrapper which sets up env variables and paths::

    /casa/host/build/bin/bv_env anatomist

When you're done, exit the container shell

Optionally you can test the image with an existing dev environment, using:

here, test the software you have installed etc. You can test brainvisa tools with the “bv_env” wrapper which sets up env variables and paths:

recreate a .sif file::

    sudo apptainer build casa-run-mod-5.3-23.sif casa-run-5.3-23

(the creation of the user image doesn't seem to work using a sandbox as a source image, so we need to convert it back to .sif)

(the creation of the user image doesn’t seem to work using a sandbox as a source image, so we need to convert it back to .sif)

In order to use the new run image as a base for a new user image, we need to have a .json metadata file. Just copy it from the original .sif one::

    cp casa-run-5.3-23.sif.json casa-run-mod-5.3-23.sif.json

(well to do things right we should generate another ID and update the md5 there, but never mind)

In order to use the new run image as a base for a new user image, we need to have a .json metadata file. Just copy it from the original .sif one:

create the user image::

    # this is not needed after you have done it once
    sudo apptainer config fakeroot --add $(id -u -n)

    casa_distro_admin create_user_image base_image=$(pwd)/casa-run-mod-5.3-23.sif name=brainvisa-spn image_version=5.3 environment_name=brainvisa-master-ubuntu-22.04 container_type=singularity install_thirdparty="spm12-standalone=/usr/local/spm12-standalone" version=1.0.0

note that:

- the new user image will contain brainvisa projects which have been configured and built in your environment (here I use "brainvisa-master-ubuntu-22.04" which is my dev environment), and only them. If you have not all the projects we ship, then your distribution will not contain them.
- in our user images we now include a copy of spm12 standalone, which we specify with the parameter install_thirdparty="spm12-standalone=/usr/local/spm12-standalone", which copies an already installed SPM12.

# this is not needed after you have done it once
sudo apptainer config fakeroot --add $(id -u -n)

casa_distro_admin create_user_image base_image=$(pwd)/casa-run-mod-5.3-23.sif name=brainvisa-spn image_version=5.3 environment_name=brainvisa-master-ubuntu-22.04 container_type=singularity install_thirdparty="spm12-standalone=/usr/local/spm12-standalone" version=1.0.0

the new user image will contain brainvisa projects which have been configured and built in your environment (here I use "brainvisa-master-ubuntu-22.04" which is my dev environment), and only them. If you have not all the projects we ship, then your distribution will not contain them.

the new user image will contain brainvisa projects which have been configured and built in your environment (here I use “brainvisa-master-ubuntu-22.04” which is my dev environment), and only them. If you have not all the projects we ship, then your distribution will not contain them.

in our user images we now include a copy of spm12 standalone, which we specify with the parameter install_thirdparty="spm12-standalone=/usr/local/spm12-standalone", which copies an already installed SPM12.

in our user images we now include a copy of spm12 standalone, which we specify with the parameter install_thirdparty=”spm12-standalone=/usr/local/spm12-standalone”, which copies an already installed SPM12.

Hyperlink target "casa-distro-admin-help-help" is not referenced.

Hyperlink target "casa-distro-admin-singularity-deb-help" is not referenced.

Hyperlink target "casa-distro-admin-create-base-image-help" is not referenced.

Hyperlink target "casa-distro-admin-publish-base-image-help" is not referenced.

Hyperlink target "casa-distro-admin-create-user-image-help" is not referenced.

Hyperlink target "casa-distro-admin-publish-user-image-help" is not referenced.

Hyperlink target "casa-distro-admin-bbi-daily-help" is not referenced.

Hyperlink target "casa-distro-admin-local-install-help" is not referenced.

Hyperlink target "casa-distro-admin-convert-image-help" is not referenced.

verbose

casa_distro <general options> <command> [<command parameters>...]

List run or dev environments created by "setup"/"setup_dev" command.

List run or dev environments created by “setup”/”setup_dev” command.

:ref:`type <env_type>`

If given, select environment having the given type.

json
default = no
The output is written as a list of configuration dictionaries in
JSON format.

version
If given, select environment by its version (only applicable to user
environments, not dev)

gui

If ``no``, ``false`` or ``0``, command is not using a graphical user
interface (GUI). Nothing is done to connect the container to a
graphical interface. This option may be necessary in context where
a graphical interface is not available.

, command is not using a graphical user

opengl
default=auto

Setup different ways of trying to use OpenGL 3D rendering and GPU.
``auto``, ``container``, ``nv``, or ``software``.

* ``auto``: use a heuristic to choose the best option that is safe
  based on the host configuration
* ``container``: passes no special options to Singularity: the mesa
  installed in the container is used
* ``nv`` tries to mount the proprietary NVidia driver of the host (linux)
  system in the container
* ``software`` sets LD_LIBRARY_PATH to use a software-only OpenGL
  rendering. This solution is the slowest but is a fallback when no
  other solution works.

``auto``: use a heuristic to choose the best option that is safe
based on the host configuration

: use a heuristic to choose the best option that is safe

``container``: passes no special options to Singularity: the mesa
installed in the container is used

: passes no special options to Singularity: the mesa

``nv`` tries to mount the proprietary NVidia driver of the host (linux)
system in the container

 tries to mount the proprietary NVidia driver of the host (linux)

``software`` sets LD_LIBRARY_PATH to use a software-only OpenGL
rendering. This solution is the slowest but is a fallback when no
other solution works.

 sets LD_LIBRARY_PATH to use a software-only OpenGL

root
default=False

If ``yes``, ``true`` or ``1``, start execution as system administrator. For
Singularity container, this requires administrator privileges on host
system.

system.

, start execution as system administrator. For
system.

cwd
Set current working directory to the given value before launching
the command. By default, it is the same working directory as on the
host

host

env
Comma separated list of environment variables to pass to the command.
Each variable must have the form name=value.

container_options
Comma separated list of options to add to the command line used to
call the container system.

Update the container images. By default the current image and
all images that are used by at least one casa-distro environment
are selected (these environments are listed by the ``list`` command).
There are two ways of selecting the image(s) to be updated:

are selected (these environments are listed by the 

 command).

filtered by environment, using the ``name`` selector, or a combination
of ``distro``, ``branch``, and ``image_version``.

    casa_distro pull_image type=dev image_version=5.0

directly specifying an image file name

    casa_distro pull_image image=/home/me/casa-run-5.0.sif

Then the command look for an updated version of selected images in the
site given by ``url`` parameter. These files are downloaded (as well as
the corresponding JSON metadata file) and the config files using the
current images are modified to use the updated ones. Finally, the original
images are deleted (unless ``cleanup=no`` is used).

site given by 

 parameter. These files are downloaded (as well as
images are deleted (unless 

Updated images are located using file name pattern. An updatable image
file name must match the following pattern:

``{name}`` is the name of the image (e.g ``casa-dev``)
``{version}`` is the image version with pattern x.y[.z]
``{patch}`` is an integer
``{version}`` is the file name extension (e.g. ``sif``)

An updated version of a given image is any other image with the same
pattern having the same ``name``, ``version`` and ``extension`` and a
higher ``patch``. If several updated version are available for an image,
the one with the greatest ``patch`` is selected.

pattern having the same 

. If several updated version are available for an image,
the one with the greatest 

url
default=https://brainvisa.info/download
URL where to download images.

mode
default=standard
Possible values are:
    - standard: download only newer version of existing image
    - force: re-download of images even if they are locally present
      and up-to-date.
    - fake: don't change anything to images. Just display what images
      and config files would be modified by other modes.

- standard: download only newer version of existing image
- force: re-download of images even if they are locally present
  and up-to-date.
- fake: don't change anything to images. Just display what images
  and config files would be modified by other modes.

force: re-download of images even if they are locally present
and up-to-date.

fake: don't change anything to images. Just display what images
and config files would be modified by other modes.

fake: don’t change anything to images. Just display what images

cleanup
if true (or 1, or yes), remove current image when succesfully finished
to download new one.

Start a bash shell in the configured container with the given pository
configuration.

Start any command in one or several container with the given
repository configuration. By default, command is executed in
all existing build workflows.

# Launch bv_maker on all build workflows using any version of Ubuntu
casa_distro mrun bv_maker system=ubuntu-*

Start a bv_maker in the configured container with the given repository

default=dev

verbose

As casa_distro runs a chain of sub-commands, each of them passing some user-provided arguments, there may be some ambiguity on who should receive arguments. The argument delimiter ``--`` should be used appropriately.
For instance:

As casa_distro runs a chain of sub-commands, each of them passing some user-provided arguments, there may be some ambiguity on who should receive arguments. The argument delimiter 

casa_distro -r ~/casa_distro run branch=bug_fix gui=1 anatomist /casa/tests/some_image.nii

Casa_distro will run the ``anatomist`` command through Docker or Singularity, which also parses its commandline options:

 command through Docker or Singularity, which also parses its commandline options:

Casa_distro gets arguments ``run``, ``branch=bug_fix``, and ``gui=1``, and identifies the remaining args as the command to run.

It invokes ``docker`` or ``singularity``, passing it some specific arguments, and the remaining ``anatomist`` and ``/casa/tests/some_image.nii``, which will be executed in a bash shell inside docker.

casa_distro -r ~/casa_distro run branch=bug_fix bv_maker gui=1 --directory=/tmp

The last argument, ``--directory=/tmp``, will be interpreted by ``casa_distro``, and you will get an error from the ``casa_distro`` command which does not know this option (but even if it did, it would not pass it to the ``bv_maker`` command). But as it is located, you likeky expected to get passed to ``bv_maker``... At the moment ``casa_distro`` intercetps all arguments in the shape ``argument=value`` for himself.

 command which does not know this option (but even if it did, it would not pass it to the 

 command). But as it is located, you likeky expected to get passed to 

In the first example there was not this ambiguity since ``casa_distro`` did not recognize the arguments ``anatomist`` and ``/casa/tests/some_image.nii``, so passed them to the following (docker or singularity) command. But now, ``--directory=/tmp`` is understood by ``casa_distro``, used, and consumed by it.

, so passed them to the following (docker or singularity) command. But now, 

You have to stop arguments parsing inside ``casa_distro`` and make it pass the remaining arguments to the following command, using ``--``:

 and make it pass the remaining arguments to the following command, using 

casa_distro -r ~/casa_distro run branch=bug_fix gui=1 -- bv_maker --directory=/tmp

The other useful option is to pass options to the container program (docker for instance) (not to the command executed inside docker), typically to mount host directories etc. This is done using the ``container_optioins`` option, followed by more options:

The other useful option is to pass options to the container program (docker for instance) (not to the command executed inside docker), typically to mount host directories etc. This is done using the 

casa_distro -r ~/casa_distro run branch=bug_fix gui=1 container_options='-v /home/albert/my_data:/docker_data' -- anatomist /docker_data/image.nii

An environment may also be given as its unique :ref:`name <env_name>` insead of the above variables.

Rather than systematically passing options, some environment variables may be used to specify some parameters to `̀ casa_distro``:

Rather than systematically passing options, some environment variables may be used to specify some parameters to 

# replaces the -r option
CASA_DEFAULT_REPOSITORY=/home/someone/casa_distro

The ``casa_distro.json`` file found in each :ref:`environment` subdirectory (in the ``conf`` subdirectory, actually) is a dictionary which contains variables used to define the environment, the type of container used (docker or singularity), mounted directories in the container image, etc.

 subdirectory, actually) is a dictionary which contains variables used to define the environment, the type of container used (docker or singularity), mounted directories in the container image, etc.

Some variables substitution can occur in the string values, in a "pythonic" shape: ``%(variable)s`` will be replaced by the contents of a variable ``variable``. The following variables are available:

Some variables substitution can occur in the string values, in a “pythonic” shape: 

name
casa_distro_compatibility
image
system
branch
mounts
type
distro

Moreover some environment variables replacement also takes place, in the shape: ``${VARIABLE}``.

Moreover some environment variables replacement also takes place, in the shape: 

branch: string
name of the source and build branch (``master``, ``latest_release``, ``release_candidate``)

container_env: dictionary
environment variables set when running a container.

container_gui_env: dictionary
environment variables set when running a container in gui mode.

container_gui_options: list
list of commandline options passed to the container command in gui mode: depends on the container types.

image: string
container image name. May be a filename, or a docker-style identifier. Docker-style identifiers are converted into filenames when using singularity, thus are still understood, so ``cati/casa-dev:ubuntu-16.04`` is a valid name.

container image name. May be a filename, or a docker-style identifier. Docker-style identifiers are converted into filenames when using singularity, thus are still understood, so 

container_options: list
list of commandline options passed to the container command: depends on the container types, options passed to docker and to singularity actually differ.

container_type: string
``docker`` or ``singularity``. New container types, ``virtualbox`` for instance, may be added in future extensions.

mounts: dictionary
mount points in the container. Directories from the host filesystem (source) are exported to the container (dest). The dictionary is a map of destination:source directories.

distro: string
name of the distribution (set of configured sources built in the build workflow).

system: string
system the container runs (``ubuntu-18.04``, etc.).

Hyperlink target "casa-distro-pull-image-help" is not referenced.

verbose

The *repository* is the root directory for all casa-distro files. It contains :ref:`container images <image>` and :ref:`environments <environment>`.

An *environment* is a workspace, directory and associated container image(s), containing a user installation of the applications (|bv| software) or a developer build (sources and build).

 is a workspace, directory and associated container image(s), containing a user installation of the applications (

It represents all what is necessary to work on a :ref:`distro` at
a given version for a given operating system. In ``casa_distro``, an
environment is identified by several variables:

Note that in casa-distro 2, we used to call this environment "*build workflow*". We changed the name after extending it to user "run" environments which are not designed to build the software but just to use it.

”. We changed the name after extending it to user “run” environments which are not designed to build the software but just to use it.

An environment is based on an :ref:`image` located at the :ref:`repository` level. In some situations (developer environments with tests, release building) several :ref:`images <image>` may be used within a single environment.

 level. In some situations (developer environments with tests, release building) several 

The hardware representation of an environment is a set of directories in the :ref:`repository`, under the sub-directory named after th :ref:`env_name`:

The hardware representation of an environment is a set of directories in the 

For a **user environment**:

| - **host/conf:** configuration of the environment (config file, etc.). There are some predefined content for ``conf`` that can be generated with the command ``casa_distro setup`` but the whole environment can be customized by editing files in this directory.
| - **host/host_bin:** directory containing run scripts for all |bv| executable programs, and also the :doc:`bv_command`. Programs here are meant to be run from the *host machine*, not from within the container. This directory can safely be setup in the host system ``PATH`` environment variable.
| - **host/python:** contains the python modules needed to run the :doc:`bv_command` on the *host machine* side.
| - **home:** a "home directory" for the user inside the casa-distro container of the environment. This is separated from the host home directory because as it is a container, the configuration here may differ from the host one, and cause confusions and incompatibilities.
| - **install:** the |bv| distribution directory. This directory is actually in the container image, and is not visible from the host machine.

- **host/conf:** configuration of the environment (config file, etc.). There are some predefined content for ``conf`` that can be generated with the command ``casa_distro setup`` but the whole environment can be customized by editing files in this directory.

 configuration of the environment (config file, etc.). There are some predefined content for 

 but the whole environment can be customized by editing files in this directory.

- **host/host_bin:** directory containing run scripts for all |bv| executable programs, and also the :doc:`bv_command`. Programs here are meant to be run from the *host machine*, not from within the container. This directory can safely be setup in the host system ``PATH`` environment variable.

, not from within the container. This directory can safely be setup in the host system 

- **host/python:** contains the python modules needed to run the :doc:`bv_command` on the *host machine* side.

- **home:** a "home directory" for the user inside the casa-distro container of the environment. This is separated from the host home directory because as it is a container, the configuration here may differ from the host one, and cause confusions and incompatibilities.

 a “home directory” for the user inside the casa-distro container of the environment. This is separated from the host home directory because as it is a container, the configuration here may differ from the host one, and cause confusions and incompatibilities.

- **install:** the |bv| distribution directory. This directory is actually in the container image, and is not visible from the host machine.

 distribution directory. This directory is actually in the container image, and is not visible from the host machine.

for a **developer environment**:

| - **host/conf:** configuration of the environment (config file, BioProj passwords, ``bv_maker.cfg``, etc.). The content of this directory is the input of the compilation, packaging and testing steps. There are some predefined content for ``conf`` that can be generated with the command ``casa_distro setup_dev`` but the whole environment can be customized by editing files in this directory.
| - **host/src:** source of selected components for the workflow. The content
  of this directory is first created by ``bv_maker`` from within a
  Docker container running the targeted operting system. Simply call
  ``casa_distro bv_maker`` for this. The same command can be used to
  update sources to latest revision or to recompile when source code has
  been modified.
| - **host/build:** build directory used for compilation. Like the ``src``
  directory, the content of this directory is created by commands such
  as ``casa_distro bv_maker``.
| - **host/install:** directory containing distribution packages. Packages that
  are created by bv\_maker are stored in that directory.
| - **test:** directory used during testing. Typically reference data
  will be downloaded in this directory and compared to test data
  generated, in this directory, by test commands.

- **host/conf:** configuration of the environment (config file, BioProj passwords, ``bv_maker.cfg``, etc.). The content of this directory is the input of the compilation, packaging and testing steps. There are some predefined content for ``conf`` that can be generated with the command ``casa_distro setup_dev`` but the whole environment can be customized by editing files in this directory.

 configuration of the environment (config file, BioProj passwords, 

, etc.). The content of this directory is the input of the compilation, packaging and testing steps. There are some predefined content for 

- **host/src:** source of selected components for the workflow. The content
of this directory is first created by ``bv_maker`` from within a
Docker container running the targeted operting system. Simply call
``casa_distro bv_maker`` for this. The same command can be used to
update sources to latest revision or to recompile when source code has
been modified.

 source of selected components for the workflow. The content
of this directory is first created by 

 from within a

 for this. The same command can be used to

- **host/build:** build directory used for compilation. Like the ``src``
directory, the content of this directory is created by commands such
as ``casa_distro bv_maker``.

as 

- **host/install:** directory containing distribution packages. Packages that
are created by bv\_maker are stored in that directory.

- **test:** directory used during testing. Typically reference data
will be downloaded in this directory and compared to test data
generated, in this directory, by test commands.

 directory used during testing. Typically reference data

There are two environment types:
* ``user``: the environment is an installation of a ready-to-run, precompiled |bv| distribution in a container image. It is designed for users who just need to run the software.
* ``dev``: the environment is a developer environment, it is using a container image containing all development tools, and will hold source code and compilation files.

: the environment is an installation of a ready-to-run, precompiled 

 distribution in a container image. It is designed for users who just need to run the software.
* 

: the environment is a developer environment, it is using a container image containing all development tools, and will hold source code and compilation files.

Identifier for the :ref:`environment`. The *name* has to be unique in a :ref:`repository` and can be used as a shortcut to select a specific environment, once setup and installed: it can replace :ref:`distro`, :ref:`branch`, :ref:`version`, :ref:`system` and :ref:`type <env_type>` to select an existing environment.

 and can be used as a shortcut to select a specific environment, once setup and installed: it can replace 

The identifier of the *distro* (distribution). It represents a set of software handled (installed or built) in the :ref:`environment`. Software distributions managed by casa-distro are composed of many versioned software components
(more than 50 at the time of this writing).

 (distribution). It represents a set of software handled (installed or built) in the 

. Software distributions managed by casa-distro are composed of many versioned software components

``opensource``: brainvisa projects subset which are fully open-source and don't need a personal login/password to access the sources repositories. The contain the core libraries and software infrastructure (Aims, Anatomist, Axon, Soma-Workflow, Capsul, and more)

: brainvisa projects subset which are fully open-source and don’t need a personal login/password to access the sources repositories. The contain the core libraries and software infrastructure (Aims, Anatomist, Axon, Soma-Workflow, Capsul, and more)

``cea``: complete |bv| components, including internal (non-publicly distributed) components

 components, including internal (non-publicly distributed) components

the operating system the :ref:`distro` is built for (*e.g.* ``ubuntu-18.04``, ``ubuntu-20.04``, we used to have also ``win32`` or ``win64``).

The name of the virtual :ref:`branch` used to select software component sources (``latest_release``, ``master`` or ``integration``) in an :ref:`environment`. This variable is only used in *developer environments*, when *user environments* use :ref:`version` instead.

Container image file, located in the :ref:`repository`. Casa-distro can use Singularity images (``.sif`` or ``.simg`` files), Docker images (located in the docker images repository, not in Casa-distro repository directory), or VirtualBox images (``.vdi`` or ``.ova`` files).

 files), Docker images (located in the docker images repository, not in Casa-distro repository directory), or VirtualBox images (

An images may be of three types:
* **user image:** user-oriented, it contains a full system with |bv| already installed in it.
* **dev image:** developer-oriented, it contains a system with all needed development tools, but not the |bv| software which are meant to be built by the developer, in the :ref:`environment` but outside of the image.
* **run image:** normally not used by users nor by developers, but used by distribution maintainers to build a |bv| release (user image): it contains a system with the needed runtime third-party libraries and modules required to run the |bv| software. It is thus lighter than the corresponding dev image. A user image is a run image with |bv| additionally installed in it.

 developer-oriented, it contains a system with all needed development tools, but not the 

 normally not used by users nor by developers, but used by distribution maintainers to build a 

 release (user image): it contains a system with the needed runtime third-party libraries and modules required to run the 

 software. It is thus lighter than the corresponding dev image. A user image is a run image with 

Version of the image. This should not be confused with the branch or versions of the software to be built and packaged in the final user image (this is the :ref:`version` tag). This more represents the system and variants (for instance in BrainVisa, image_version 5.3 corresponds to an Ubuntu 22.04 system with python 3.10 and Qt 5).

Version of the image. This should not be confused with the branch or versions of the software to be built and packaged in the final user image (this is the 

 tag). This more represents the system and variants (for instance in BrainVisa, image_version 5.3 corresponds to an Ubuntu 22.04 system with python 3.10 and Qt 5).

Casa-distro project is the metronome and swiss knife for the management of compilation and publication of CASA software distributions. It contains all tools to create and publish the virtual images as well as tools for the management of the whole distro creation pipeline (configuration source retrieval, compilation, packaging, publication, etc.).

* I develop toolboxes, I need to build and release them as binary compatible with the official BrainVisa distrtibutions

* I am a contributor of Cati/BrainVisa environment, and need to get started quickly

* I am release maintainer of BrainVisa and need to produce a new release yesterday

The :bv:`BrainVisa download / install section <download.html>` explains how to install both a released, compiled, version of BrainVISA (This is what a "regular user" needs), or a developer environment which will build from sources.

 explains how to install both a released, compiled, version of BrainVISA (This is what a “regular user” needs), or a developer environment which will build from sources.

Alternatively it is possible to install Casa-Distro from its sources on GitHub. To get the latest release you can simply download it from https://github.com/brainvisa/casa-distro, using  the ``git`` command::

  git clone https://github.com/brainvisa/casa-distro.git /tmp/casa-distro

Once downloaded, no "install step" is required, you can use the casa_distro command directly::

  /tmp/casa-distro/bin/casa_distro help

Alternatively it is possible to install Casa-Distro from its sources on GitHub. To get the latest release you can simply download it from 

git clone https://github.com/brainvisa/casa-distro.git /tmp/casa-distro

Once downloaded, no “install step” is required, you can use the casa_distro command directly:

Casa-distro is pre-setup to handle CATI/BrainVisa open-source projects. In this situation, once casa-distro has been downloaded or installed, a user has to follow the next steps:

Developers will need access to source and development tools. Thus instead of installing a "user" release of BrainVISA using the ``casa_distro setup`` command, they will rather install a developer image and setup. This is done (once casa-distro is installed) using the command ``casa_distro setup_dev``::

    casa_distro setup_dev system=ubuntu-18.04 distro=brainvisa branch=master

This will setup an :ref:`environment` dedicated to development.

This command specifies to setup a developer :ref:`environment` for the open-source projects set (``distro_source=opensource`` is actually the default and can be omitted), for the ``master`` branch (default is ``latest_release``), using a container system based on Ubuntu 18.04.

Directories and files will be created accordingly in the :REF:`repository` directory (location of casa-distro container images and :ref:`environments <environment>`), here the default is ``$HOME/casa_distro``.

The location of casa-distro :ref:`repository` can be specified either using the ``base_directory=`` parameter to many sub-commands, or if the environment variable ``CASA_DEFAULT_REPOSITORY`` is set to an appropriate directory.

Such an :ref:`environment` will use source code from BrainVisa code repositories (partly on https://github.com and partly on https://bioproj.extra.cea.fr). The code needs to be downloaded and built using a build system: :bv-cmake:`bv_maker <index.html>`

Developers will need access to source and development tools. Thus instead of installing a “user” release of BrainVISA using the 

 command, they will rather install a developer image and setup. This is done (once casa-distro is installed) using the command 

casa_distro setup_dev system=ubuntu-18.04 distro=brainvisa branch=master

 parameter to many sub-commands, or if the environment variable 

 will use source code from BrainVisa code repositories (partly on 

). The code needs to be downloaded and built using a build system: 

Setup credentials for source code reposotories

This step is optional and is especially not need if just retrieving only the open-source projects.
The file ``svn.secret`` may be created / edited to store login / password information for the svn `BioProj <http://bioproj.extra.cea.fr>`_ server. If not filled, the ``svn`` program will ask for them interactively, and propose to store them.

The file 

 may be created / edited to store login / password information for the svn 

 program will ask for them interactively, and propose to store them.

build everything::

    casa_distro bv_maker name=opensource-dev-ubuntu-18.04

If :ref:`name <env_name>`, :ref:`distro`, :ref:`branch`, or :ref:`system` are not provided, all matching :ref:`environments <environment>` will be processed.

Additional options can be passed to the underlying :bv-cmake:`bv_maker <index.html>` command, which will run inside the container. Typically, the documentation can be built, testing and packaging can be performed.

 command, which will run inside the container. Typically, the documentation can be built, testing and packaging can be performed.

Once an environment has been initialized, and at least source code has been updated (using ``casa_distro bv_maker``), most :ref:`distributions <distro>` actually include the *casa-distro* project, which will be updated with the rest of the source code. As it is python-only, it can be run from the host system (if stored on the host filesystem), so it may be a good idea to use this updated ``casa_distro`` command instead of the oned previously installed (either via pip or from `github <https://github.com>`_ sources) to initialize the process.

Once an environment has been initialized, and at least source code has been updated (using 

 project, which will be updated with the rest of the source code. As it is python-only, it can be run from the host system (if stored on the host filesystem), so it may be a good idea to use this updated 

 command instead of the oned previously installed (either via pip or from 

This can be done by "updating" a build-workflow (actually any one which contains casa-distro):

python /tmp/casa-distro/bin/casa_distro update distro=opensource branch=master system=ubuntu-18.04

Then the run script will use the casa-distro from this source tree.

You can setup your host environment (``$HOME/.bashrc`` typically) to use it by default by setting it first in the ``PATH`` environment variable:

Here you should of course replace the path ``$HOME/casa_distro/opensource-dev-ubuntu-18.04`` with the environment path listed by the command ``casa_distro list``.

Bash completion scripts have been developed for ``casa_distro`` and ``bv_maker``. Inside a casa-distro container, these completions are already setup and should be active as soon as environments have been built, and the container is restarted (exit a casa-distro shell and re-run it).
On the host, it is possible to *source* the bash completion scripts. You can set it in your ``$HOME/.bashrc`` file by adding to it::

. Inside a casa-distro container, these completions are already setup and should be active as soon as environments have been built, and the container is restarted (exit a casa-distro shell and re-run it).
On the host, it is possible to 

BUILD_WF=$HOME/casa_distro/opensource-dev-ubuntu-18.04
if [ -f "$BUILD_WF/host/src/development/casa-distro/*/etc/bash_completion.d/casa_distro-completion.bash" ]; then
    . "$BUILD_WF/host/src/development/casa-distro/*/etc/bash_completion.d/casa_distro-completion.bash"
fi
if [ -f "$BUILD_WF/host/src/development/brainvisa-cmake/*/etc/bash_completion.d/bv_maker-completion.bash" ]; then
    . "$BUILD_WF/host/src/development/brainvisa-cmake/*/etc/bash_completion.d/bv_maker-completion.bash"
fi

This completion will help typing the commands and its options by providing possible options and values by typing ``<tab>`` or ``<tab> <tab>`` when typing the command code, which will significantly speed-up working intensively with casa_distro and bv_maker.

This completion will help typing the commands and its options by providing possible options and values by typing 

 when typing the command code, which will significantly speed-up working intensively with casa_distro and bv_maker.

To update to the most recent versions of the projects sources, and rebuild, it is simply a matter of re-running ``casa_distro bv_maker`` (with corresponding options, if needed).

To update to the most recent versions of the projects sources, and rebuild, it is simply a matter of re-running 

It is possible to customize the projects list to be retrieved and built. It is done by editing the :bv-cmake:`bv_maker.cfg file <configuration.html>` in the environment, which can be found in the directory ``<repository>/<environment>/host/conf/``

It is possible to customize the projects list to be retrieved and built. It is done by editing the 

where ``<repository>`` is the base casa-distro :ref:`repository` directory (passed as the ``base_directory`` option of casa_distro if needed), ``<environment>`` is the :ref:`environment` :ref:`env_name`.

The :doc:`concepts` document shows the vocabulary used to describe the elements of Casa-Distro.

 document shows the vocabulary used to describe the elements of Casa-Distro.

What we call "administration" in Casa-Distro is handling tools to build a new (BrainVISA) release, to build new images, not just developing code. This part is the job of :doc:`casa_distro_admin_command`.

What we call “administration” in Casa-Distro is handling tools to build a new (BrainVISA) release, to build new images, not just developing code. This part is the job of 

If you want to install simply casa-distro as a user, you can directly see the :bv:`BrainVisa download / install section <download.html>`.

If you want to install simply casa-distro as a user, you can directly see the 

CASA = `CATI <http://cati-neuroimaging.com>`_ + `BrainVISA <http://brainvisa.info>`_

When these two projects decided to use the same development and software delivery environment, the name CASA was chosen to name this environment.

**Short answer:** it's the way to **run or develop BrainVISA software** in a containerized environment or a virtual machine.

It's a cross-platform environment which is used by users to install/use BrainVisa and CATI environments, and by developers to provide a common working development environment for BrainVISA and CATI tools. It avoids the manual installation of required development software and libraries, which can cause the use of different versions on different systems.
It was not unusual to discover differences of behaviour in software that was only due to diferrences between development environments. The more developers were involved in the projects, the more difficulties were encountered. It was become too difficult to maintain good quality software without a unified development environment.

It’s a cross-platform environment which is used by users to install/use BrainVisa and CATI environments, and by developers to provide a common working development environment for BrainVISA and CATI tools. It avoids the manual installation of required development software and libraries, which can cause the use of different versions on different systems.

Therefore, it was decided to create casa-distro to provide a complete development environment using a virtual appliance to host the compilation system. casa_distro will support two container technologies, `Singularity <https://www.sylabs.io/>`_ and `Docker <https://www.docker.com>`_ (soon) and one virtual machine technology : `VirtualBox <https://www.virtualbox.org/>`_.

Therefore, it was decided to create casa-distro to provide a complete development environment using a virtual appliance to host the compilation system. casa_distro will support two container technologies, 

**Note**: in version 3.0 the support for Docker has been temporarily dropped (but should come back as soon as possible).

: in version 3.0 the support for Docker has been temporarily dropped (but should come back as soon as possible).

Users will use Casa-Distro to install and run `BrainVISA <http://brainvisa.info>`_ software.

See the :bv:`BrainVisa download / install section <download.html>` explains how to install it.

The containerization allows to have a single binary distribution for all host operating systems and versions.

Casa-Distro is not a build system: this is the job of :bv-cmake:`BrainVisa-Cmake <index.html>`. Casa-distro brings a wrapper for the build system: it provides Docker images of Linux systems which contain :bv-cmake:`BrainVisa-Cmake <index.html>` and many other thirdparty development tools and libraries, which are already setup for development and distribution of tools.

. Casa-distro brings a wrapper for the build system: it provides Docker images of Linux systems which contain 

 and many other thirdparty development tools and libraries, which are already setup for development and distribution of tools.

The user will be able to use the build system (:bv-cmake:`bv_maker <bv_maker.html>`), inside Singularity, Docker, or VirtualBox, in a way that ensures to build, run, and ship software that is compatible with public distributions of BrainVisa.

), inside Singularity, Docker, or VirtualBox, in a way that ensures to build, run, and ship software that is compatible with public distributions of BrainVisa.

Follow roughly the same procedure as for user setup, as axplained in: :bv:`BrainVisa download / install section <download.html#developers-install>`.

Follow roughly the same procedure as for user setup, as axplained in: 

:doc:`bv_command` is the lightest, user-oriented command in casa-distro. It supports a single :ref:`environment` and allows the minimum required to configure and run commands (or open a shell) in an installed environment container.

 is the lightest, user-oriented command in casa-distro. It supports a single 

 and allows the minimum required to configure and run commands (or open a shell) in an installed environment container.

:doc:`casa_distro_command` supports multiple :ref:`environments <environment>` using selection parameters (see :doc:`concepts`) and allows also to run commands inside containers, but also to setup / install, manage, delete :ref:`environments <environment>` and :ref:`container images <image>`.

) and allows also to run commands inside containers, but also to setup / install, manage, delete 

:doc:`casa_distro_admin_command` is used to create new container images and publish them on a web server for other users.

 is used to create new container images and publish them on a web server for other users.

BBI stands for *BrainVISA Build Infrastructure*. The ``casa_distro_admin
bbi_daily`` command orchestrates automated builds and tests in a given *base
directory*. This page is written as a guide to setting up automated tests, see
:ref:`bbi-daily-help` for the reference documentation.

. This page is written as a guide to setting up automated tests, see

Here is a detailed log of how nightly builds are set up in NeuroSpin. You can
take inspiration from it to create your own personalized set-up.

Install ``singularity``. Configure the *fakeroot* functionality of
Singularity, as explained `in the Singularity Admin Guide
<https://sylabs.io/guides/3.7/admin-guide/user_namespace.html#fakeroot-feature>`_.
In short, you need admin rights on your machine, and you have to run::

  sudo singularity config fakeroot --add $USER

(with ``$USER`` being ``a-sac-ns-brainvisa`` in this case).

`in the Singularity Admin Guide
<https://sylabs.io/guides/3.7/admin-guide/user_namespace.html#fakeroot-feature>`_

.
In short, you need admin rights on your machine, and you have to run:

Create a directory dedicated to the nightly builds and ``cd`` into it::

  export CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly
  mkdir "$CASA_BASE_DIRECTORY"
  cd "$CASA_BASE_DIRECTORY"

export CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly
mkdir "$CASA_BASE_DIRECTORY"

Create the ``jenkins_auth`` file in the *base directory*. This text file
must consist of two lines: the first line contains the username on the
Jenkins server, the second line contains the *token* that can be generated
in the Jenkins web interface (click on the user on top right corner, select
*Configure* and create a new API token). This token will be used instead of
the account password to upload build results. One advantage of using a token
is the possibility to revoke it at any time. It is recommended to use one
token per BrainVISA Build Environment and name the token accordingly.

:warning: You should make this file non-readable by others, e.g. create it
          with::
            chmod 0600 jenkins_auth

. This text file
Jenkins server, the second line contains the 

 that can be generated

 and create a new API token). This token will be used instead of

You should make this file non-readable by others, e.g. create it
with::
  chmod 0600 jenkins_auth

with::

with:

Download the ``casa-dev`` image using the link found on the Downloads page
of <https://brainvisa.info/>. Also download the associated JSON file (to be
extra safe, check that the md5sum of the image matches that stored in the
JSON file).::

  wget https://brainvisa.info/download/casa-dev-5.0.sif
  wget https://brainvisa.info/download/casa-dev-5.0.sif.json
  md5sum casa-dev-5.0.sif

>. Also download the associated JSON file (to be
JSON file).:

wget https://brainvisa.info/download/casa-dev-5.0.sif
wget https://brainvisa.info/download/casa-dev-5.0.sif.json
md5sum casa-dev-5.0.sif

Create a directory for your development environment and set it up::

  mkdir brainvisa-master-5.0
  singularity run -c --bind ./brainvisa-master-5.0:/casa/setup \
      casa-dev-5.0.sif distro=brainvisa branch=master

Create a directory for your development environment and set it up:

mkdir brainvisa-master-5.0
singularity run -c --bind ./brainvisa-master-5.0:/casa/setup \
    casa-dev-5.0.sif distro=brainvisa branch=master

Edit the ``conf/svn.secret`` file with your BioProj login and password.

Check out and compile an initial build while you do the rest of the
configuration (until you run ``bbi_daily``)::

  "$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/bin/bv_maker

configuration (until you run 

Put the reference test data in
``"$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/tests/ref/``. Best is to copy
it from a known-good source.

``bbi_daily`` will install the compiled software in a user image, create a
fresh user environment from that user image, and run tests in there. You can
control this process with a few optional parameters, that you should insert
in the ``conf/casa_distro.json`` of the dev environment, as a new dictionary
under the ``bbi_user_config`` key. Below is the list of keys in this
dictionary with their default values::

  "bbi_user_config": {
      "name": "<dev_name>-userimage",
      "directory": "<dev_directory>/../<user_name>",
      "image": "{base_directory}/<user_name>{extension}",
      "version": "%Y-%m-%d"
  }

Note that the value of ``version`` will be interpreted by
:func:`time.strftime`.

 will install the compiled software in a user image, create a
in the 

 key. Below is the list of keys in this
dictionary with their default values:

"bbi_user_config": {
    "name": "<dev_name>-userimage",
    "directory": "<dev_directory>/../<user_name>",
    "image": "{base_directory}/<user_name>{extension}",
    "version": "%Y-%m-%d"
}

Check that the whole ``bbi_daily`` process is able to run successfully::

  "$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/bin/casa_distro_admin \
      bbi_daily

This will take a long time. Beware that the output of each step is
displayed only when that step is finished, so the command may seem to hang
for a long time.

"$CASA_BASE_DIRECTORY"/brainvisa-master-5.0/bin/casa_distro_admin \
    bbi_daily

Set the ``bbi_daily`` command to run on a regular basis using ``crontab -e``::

  MAILTO=your.email@host.example
  37 5 * * * PATH=/usr/local/bin:/usr/bin:/bin CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly SINGULARITY_TMPDIR=/volatile/tmp /volatile/a-sac-ns-brainvisa/bbi_nightly/brainvisa-master-5.0/bin/casa_distro_admin bbi_daily jenkins_server='https://brainvisa.info/builds'

:note: Remember to set all the needed environment variables. ``PATH`` may
       need to be set additionally, in case your Singularity installation
       is under ``/usr/local`` (by default cron limits ``PATH`` to
       ``/usr/bin:/bin``).

MAILTO=your.email@host.example
37 5 * * * PATH=/usr/local/bin:/usr/bin:/bin CASA_BASE_DIRECTORY=/volatile/a-sac-ns-brainvisa/bbi_nightly SINGULARITY_TMPDIR=/volatile/tmp /volatile/a-sac-ns-brainvisa/bbi_nightly/brainvisa-master-5.0/bin/casa_distro_admin bbi_daily jenkins_server='https://brainvisa.info/builds'

Remember to set all the needed environment variables. ``PATH`` may
need to be set additionally, in case your Singularity installation
is under ``/usr/local`` (by default cron limits ``PATH`` to
``/usr/bin:/bin``).

 may
is under 

The :bv:`BrainVisa download / install section <download.html>` explains how to install casa-distro and a released, compiled, version of BrainVISA. This is what a "regular user" needs.

 explains how to install casa-distro and a released, compiled, version of BrainVISA. This is what a “regular user” needs.

Developers can find information on the :doc:`developer` section.

This document explains how to setup and use some container systems (Singularity, Docker), and tries to solve some technical issues which can occur when using them.

Home directory and configuration files in casa-distro containers

The virtual machine variant of ``casa-distro`` images (VirtualBox) are self-contained and are using an internal user (``brainvisa`` in |bv| distributions). The remaining of this section thus applies to the container-based variants of ``casa-distro`` (singularity and docker).

 images (VirtualBox) are self-contained and are using an internal user (

 distributions). The remaining of this section thus applies to the container-based variants of 

To run the container, ``casa-distro`` (any of ``bv``, ``casa_distro`` and ``casa_distro_admin`` commands) is using an :ref:`environment` directory on the host filesystem. It is used to read configuration before starting the container, and to store files which may be shared between the container and the host filesystem.

 directory on the host filesystem. It is used to read configuration before starting the container, and to store files which may be shared between the container and the host filesystem.

The environment directory may be a personal user installation (if a user installs BrainVisa, or a developer environment, for himself), which we name *user environment*, or a *shared environment* (if an administrator installs BrainVisa for all users on a network filesystem, typically). In the first case the user has full access to the environment files (he owns the directory and files), but in the second case the shared environment directory and files belong to the administrator, and are read-only for the user.

The environment directory may be a personal user installation (if a user installs BrainVisa, or a developer environment, for himself), which we name 

 (if an administrator installs BrainVisa for all users on a network filesystem, typically). In the first case the user has full access to the environment files (he owns the directory and files), but in the second case the shared environment directory and files belong to the administrator, and are read-only for the user.

A first configuration file is read by ``casa-distro``, located on the host filesystem at the following location::

This environment file is completed by a user file, which is located in the host system user directory, at the following location::

This environment file is completed by a user file, which is located in the host system user directory, at the following location:

The mount points configured in the ``bv`` graphical tool are saved in this latter file, which is shared across all environments run by the user.

 graphical tool are saved in this latter file, which is shared across all environments run by the user.

Containers are running with the same user as the host system user, in order to have the same permissions and identity, especially in regards to files access and ownership. However they are running with a *separate user home directory*. The reasons is to avoid sharing copnfigs and paths which would be specific to the host system and those for the container, which may be incompatible.

Containers are running with the same user as the host system user, in order to have the same permissions and identity, especially in regards to files access and ownership. However they are running with a 

. The reasons is to avoid sharing copnfigs and paths which would be specific to the host system and those for the container, which may be incompatible.

In "user environments" (those owned by the user with read-write permissions on the environment directory), the container user home directory is located inside the environment directory. On host side, this is::

    <environment_dir>/home/

Inside the container, the same directory is seen under::

    /casa/host/home

In “user environments” (those owned by the user with read-write permissions on the environment directory), the container user home directory is located inside the environment directory. On host side, this is:

In "shared environments", the user cannot write in the environment directory, thus the user home directory has to be outside of it. ``casa-distro`` is using the following location rule::

    $HOME/.local/share/casa-distro/<environment_full_dir>

where ``<environment_full_dir>`` is obtained by replacing, in the full path of the environment directory, directory separators (``/`` on Unix systems or ``\`` on Windows systems) by underscores (``_``). Ex::

  /opt/brainvisa/brainvisa-5.0.0  ->  $HOME/.local/share/casa-distro/opt_brainvisa_brainvisa-5.0.0

In “shared environments”, the user cannot write in the environment directory, thus the user home directory has to be outside of it. 

 is obtained by replacing, in the full path of the environment directory, directory separators (

/opt/brainvisa/brainvisa-5.0.0  ->  $HOME/.local/share/casa-distro/opt_brainvisa_brainvisa-5.0.0

home directory and configuration files in casa-distro containers

|bv| can perform distributed execution, using :soma-workflow:`Soma-Workflow <index.html>`.

in an installed :ref:`environment`, commands are also available via "run scripts", located in ``<environment>/host/bin/``. If this directory is in the computing resource nodes ``PATH`` environment variable, then the commands will run the container transparently.

 environment variable, then the commands will run the container transparently.

Alternately, soma-workflow 3.1 brings support to spawn Docker or Singularity (or casa_distro) in remote processing. However it needs some additional configuration on server side to specify how to run the containers.

For commands run directly through the ``python`` command, more work will be required because the system ``python`` is, of course, not overloaded in BrainVISA/Casa run scripts.

Please read :soma-workflow:`Soma-Workflow documentation about it <install_config.html#running-servers-and-jobs-in-a-container>`.

Remember that software running that way live in a container, which is more or less isolated from the host system. To access data, casa_distro will likeky need additional directories mount options. It can be specified on ``casa_distro`` commandline, or in the file ``container_options`` item in ``<casa_distro_environment>/host/conf/casa_distro.json``.

Remember that software running that way live in a container, which is more or less isolated from the host system. To access data, casa_distro will likeky need additional directories mount options. It can be specified on 

* To enable users other than root and users with sudo access to be able to run Docker commands:

Users who can run Docker commands have effective root control of the system. Only grant this privilege to trusted users.

The following procedure applies to version 1.5 and later of Docker.

#. Create the ``docker`` group (maybe group ``docker`` already exists):

For some os system version (Ubuntu 14.04-15.10) use **docker.io** instead of **docker**

The UNIX socket ``/var/run/docker.sock`` is now readable and writable by members of the docker group.

3. Add the users that should have Docker access to the docker group:

Or use the following command to open a new shell forcing to take group updates into account:

By default, docker images are stored in will be ``/var/lib/docker/aufs`` but can fall back to ``btrfs``, ``devicemapper`` or ``vfs``.

* ``/var/lib/docker/{driver-name}`` will contain the driver specific storage for contents of the images.

* ``/var/lib/docker/graph/`` now only contains metadata about the image, in the ``json`` and ``layersize`` files.

* ``/var/lib/docker/aufs/diff/`` has the file contents of the images.

* ``/var/lib/docker/repositories-aufs`` is a JSON file containing local image information. This can be viewed with the command ``docker images``.

You can change Docker's storage base directory (where container and images go) using the ``-g`` option when starting the Docker daemon.

* Ubuntu/Debian: edit your ``/etc/default/docker`` file with the ``-g`` option:

DOCKER_OPTS="-dns 8.8.8.8 -dns 8.8.4.4 -g /mnt/docker" # (or write it if the line doesn't exist in this file)

* Fedora/Centos: edit ``/etc/sysconfig/docker``, and add the ``-g`` option in the ``other_args`` variable: ex.

If there's more than one option, make sure you enclose them in ``" "``.

These steps depend on your current /var/lib/docker being an actual directory (not a symlink to another location).

2. Double check docker really isn't running. Take a look at the current docker directory:

tar -zcC /var/lib docker > /mnt/pd0/var_lib_docker-backup-$(date +%s).tar.gz

6. Take a peek at the directory structure to make sure it looks like it did before the ``mv``:

To search available images on docker hub (example with ubuntu) :

* An open source brainvisa repository is available on docker hub: https://hub.docker.com/r/cati

docker run -it --rm cati/casa-dev:ubuntu-18.04-bug_fix /bin/bash

docker ps --filter status=dead --filter status=exited -aq | xargs -r docker rm -v

docker ps --filter "status=exited" | grep 'weeks ago' | awk '{print $1}' | xargs --no-run-if-empty sudo docker rm

REPOSITORY                  TAG                    IMAGE ID            CREATED             VIRTUAL SIZE

cati/casa-dev       ubuntu-12.04           7c1691e1e9d1        2 days ago          2.264 GB

If one or more containers are using the image, use the option ``-f`` to force the command ``rmi``:

docker images --no-trunc | grep '<none>' | awk '{ print $3 }' | xargs -r docker rmi

To add an external library, modify the Dockerfile of ``casa-dev`` for ubuntu-16.04 or ubuntu-18.04:

<your_library> \  ###### HERE INSERT THE NAME OF THE EXTERNAL LIBRARY

RUN wget -q http://download.qt.io/official_releases/qt-installer-framework/2.0.3/QtInstallerFramework-linux-x64.run -O /tmp/QtInstallerFramework-linux-x64.run && \

xvfb-run /tmp/QtInstallerFramework-linux-x64.run --script /tmp/qt_installer_script && \

rm /tmp/QtInstallerFramework-linux-x64.run /tmp/qt_installer_script

###### OR WRITE THE COMMAND LINES TO INSTALL THE LIBRARY FROM SOURCES

After, run the script called create_images (``[sources]/casa-distro/[trunk|bug_fix]/docker/create_images``).

This script will rebuild ``casa-test`` and ``casa-dev`` images if the ``Dockefile`` was modified and will push all images in docker hub.

In our example, only the ``Dockerfile`` of ``casa-dev`` is different, so only ``casa-dev`` image will rebuilt.

The aim of a registry server for docker is to share private images of brainvisa for CATI members.

.. Create the registry on https://catidev.cea.fr is more complicated due to CEA retrictions, so we use https://sandbox.brainvisa.info.

The Registry is compatible with Docker engine version 1.6.0 or higher.

See also the BrainVisa developers site: https://brainvisa.github.io/

Both git and svn are used in Brainvisa projects sources. svn will probably be completely replaced with git.

git URLs use https by default. It's OK for anonymous download and update, but they require manual authentication for each push, thus it's painful. If you have a github account, you can use ssh with a ssh key instead. See https://brainvisa.github.io/contributing.html

git URLs use https by default. It’s OK for anonymous download and update, but they require manual authentication for each push, thus it’s painful. If you have a github account, you can use ssh with a ssh key instead. See 

Once done git will automatically use ssh. But then ssh needs to be working...

Once done git will automatically use ssh. But then ssh needs to be working…

git and ssh may be used either on the host side (since sources are actually stored on the host filesystem), or within the container. As users may have ssh keys and have already registered them in GitHub, they will want to reuse their host ssh keys.

Singularity 3 does not allow to mount the host ``.ssh`` directory into the already mounted container home directory. So there are 2 other options:

 directory into the already mounted container home directory. So there are 2 other options:

copy the host ``.ssh`` directory into the container home::

 cp -a "/host/$CASA_HOST_HOME/.ssh" ~/

But copying private ssh keys is not recommended for security reasons.

use a ssh agent:
 - install ``keychain``. On debian-based Linux distributions, this is::

     sudo apt-get install keychain

 - add in your host ``$HOME/.bash_profile`` file::

     eval $(keychain --eval --agents ssh id_rsa)

- install ``keychain``. On debian-based Linux distributions, this is::

    sudo apt-get install keychain

- add in your host ``$HOME/.bash_profile`` file::

    eval $(keychain --eval --agents ssh id_rsa)

install ``keychain``. On debian-based Linux distributions, this is::

  sudo apt-get install keychain

add in your host ``$HOME/.bash_profile`` file::

  eval $(keychain --eval --agents ssh id_rsa)

* :ref:`Change the filesystem / disk for docker images <change_docker_base_dir>`

* :ref:`cleanup leftover docker images or containers <cleaning_up_docker>`

With Docker versions older than 1.13, the ``docker build`` command did not have a host networking option. On some systems (Ubuntu 14 for instance) the contents of ``/etc/resolv.conf`` point to a local proxy DNS server (at least that's what I understand), and docker could not use it during image building.

Either upgrade to a newer Docker, or change the :ref:`DNS setup <dns_setup>` for Docker.

When docker starts, even when running as a specific user, it starts up as root. The mount options specified on docker commandline are setup as root. If the user home directory is on a network filesystem (NFS...), the local root user cannot override the filesystem access rights. Thus the directory tree must be traversable to reach the mounted directory.

In other words, the ``+x`` flag has to be set for "other" users on the directory and its parents. Typically:

Several options are needed to enable display and OpenGL. Normally casa_distro tries to set them up and should do the best it can.

On machines with nvidia graphics cards and nvidia proprietary drivers, casa_distro will add options to mount the host system drivers and OpenGL libraries into the container in order to have hardware 3D rendering.

Options are setup in the ``casa_distro.json`` file so you can check and edit them. Therefore, the detection of nvidia drivers is done on the host machine at the time of build workflow creation: if the build workflow is shared across several machines on a network, this config may not suit all machines running the container.

 file so you can check and edit them. Therefore, the detection of nvidia drivers is done on the host machine at the time of build workflow creation: if the build workflow is shared across several machines on a network, this config may not suit all machines running the container.

However it does not seem to work when ssh connections and remote display are involved.

There are several ways to use OpenGL in singularity, depending on the host system, the 3D hardware, the X server, the type of user/ssh connection.

Our container images include  a software-only Mesa implementation of OpenGL, which can be used if other solutions fail.

Casa-distro tries to use "reasonable" settings but cannot always detect the best option. Thus the user can control the behavior using the ``opengl`` option in ``casa_distro run``, ``casa_distro shell``, ``casa_distro mrun`` and ``casa_distro bv_maker`` subcommands. This option can take several values: ``auto``, ``container``, ``nv``, or ``software``. The default is, of course, ``auto``.

Casa-distro tries to use “reasonable” settings but cannot always detect the best option. Thus the user can control the behavior using the 

``auto``: performs auto-detection: same as ``nv`` if an NVidia device is detected on a host linux system, otherwise same as ``container``, unless we detect a case where that is known to fail (in which case we would use ``software``).

 if an NVidia device is detected on a host linux system, otherwise same as 

, unless we detect a case where that is known to fail (in which case we would use 

``container``: passes no special options to Singularity: the mesa installed in the container is used

: passes no special options to Singularity: the mesa installed in the container is used

``nv`` tries to mount the proprietary NVidia driver of the host (linux) system in the container

 tries to mount the proprietary NVidia driver of the host (linux) system in the container

``software`` sets ``LD_LIBRARY_PATH`` to use a software-only OpenGL rendering. This solution is the slowest but is a fallback when no other solution works.

 to use a software-only OpenGL rendering. This solution is the slowest but is a fallback when no other solution works.

There are cases where the nvidia option makes things worse (see ssh connections below). If you ever need to disable the nvidia option, you can add an option ``opengl=software`` or ``opengl=container`` to ``run``, ``shell`` and other subcommands:

There are cases where the nvidia option makes things worse (see ssh connections below). If you ever need to disable the nvidia option, you can add an option 

If it is OK, you can set this option in the build workflow ``casa_distro.json`` config, under the ``"container_gui_env"`` key::

{
    "casa_distro_compatibility": "3",
    "name": "brainvida-5.0",
    "image": "/home/bilbo/casa_distro/brainvisa-5.0.sif",
    "type": "user",
    "system": "ubuntu-18.04",
    "container_type": "singularity",
    "distro": "brainvisa",
    "container_options": [
        "--softgl",
    ],
    # ...
}

Via a ssh connection:
same host, different user:
    ``xhost +`` must have been used on the host system. Works (as long as
    the ``XAUTHORITY`` env variable points to the ``.Xauthority`` file from
    the host user home directory).
different host:
    I personally could not make it work using the ``nv`` option. But
    actually outside of casa-distro or any container, it doesn't work
    either. Remote GLX rendering has always been a very delicate thing...

    It works for me using the software Mesa rendering (slow). So at this point, using casa_distro actually makes it possible to render OpenGL when the host system cannot (or not directly)...

``xhost +`` must have been used on the host system. Works (as long as
the ``XAUTHORITY`` env variable points to the ``.Xauthority`` file from
the host user home directory).

I personally could not make it work using the ``nv`` option. But
actually outside of casa-distro or any container, it doesn't work
either. Remote GLX rendering has always been a very delicate thing...

It works for me using the software Mesa rendering (slow). So at this point, using casa_distro actually makes it possible to render OpenGL when the host system cannot (or not directly)...

 option. But
actually outside of casa-distro or any container, it doesn’t work
either. Remote GLX rendering has always been a very delicate thing…

It works for me using the software Mesa rendering (slow). So at this point, using casa_distro actually makes it possible to render OpenGL when the host system cannot (or not directly)…

Singularity for Mac is available as a beta at the time this document is written (but with no updates nor news in more than a year). It somewhat works but we sometimes ended up with a "silent" virtual machine which seems to do just nothing. But it should work in principle, and sometimes does ;)

Singularity for Mac is available as a beta at the time this document is written (but with no updates nor news in more than a year). It somewhat works but we sometimes ended up with a “silent” virtual machine which seems to do just nothing. But it should work in principle, and sometimes does ;)

We experienced this behaviour on MacOS 10.11 using Singularity Desktop 3.3-beta for Mac. We had to upgrade the system (to 10.15) and then it worked. But then after a few days became silent again, for certain users, using certain images... but it still worked for our BrainVisa images...

We experienced this behaviour on MacOS 10.11 using Singularity Desktop 3.3-beta for Mac. We had to upgrade the system (to 10.15) and then it worked. But then after a few days became silent again, for certain users, using certain images… but it still worked for our BrainVisa images…

Graphical commands (brainvisa, anatomist, others...) should run through a X11 server. Xquartz is installed in MacOS systems, but need to be started, and a bit configured.

Graphical commands (brainvisa, anatomist, others…) should run through a X11 server. Xquartz is installed in MacOS systems, but need to be started, and a bit configured.

open Xquartz, either using the desktop / finder icon, or by running a X command such as::

  xhost +

open Xquartz, either using the desktop / finder icon, or by running a X command such as:

in the Xquartz preferences menu, go to "security" and check the option to enable network connections (tcp) to the X server

in the Xquartz preferences menu, go to “security” and check the option to enable network connections (tcp) to the X server

run
  ::

      xhost +

  to enable other users / apps to use the graphical server (this will start Xquartz, if not already running). Note that this command needs to be run again each time the Xquartz server is stopped / restarted.

run
::

    xhost +

to enable other users / apps to use the graphical server (this will start Xquartz, if not already running). Note that this command needs to be run again each time the Xquartz server is stopped / restarted.

You should use the ``opengl=software`` option in ``casa_distro`` otherwise 3D will likely crash the programs.

now graphical applications should run inside singularity containers. 3D hardware is not used however, rendering is using a software rendering, so it is not fast.

I personally had trouble getting the VirtualBox image to actually run on MacOS 10.15. The virtual machine consistently crashed at boot time. After inspecting the logs I found out that the sound card support might be the cause, and I had to use a "fake sound device" in the virtualbox image settings. Then it appeared that all graphics display was notably slow (either 2D and 3D), whatever video / accelerated 3D support options. And icons and fonts in the virtual machine were microscopic, almost impossible to read, and difficult if even possible to configure in the linux desktop. The "zoom factor x2" option in virtualbox was very handy for that, but reduced the actual resolution by a factor of 2 if I understand. Apart from these limitations, the software was running.

I personally had trouble getting the VirtualBox image to actually run on MacOS 10.15. The virtual machine consistently crashed at boot time. After inspecting the logs I found out that the sound card support might be the cause, and I had to use a “fake sound device” in the virtualbox image settings. Then it appeared that all graphics display was notably slow (either 2D and 3D), whatever video / accelerated 3D support options. And icons and fonts in the virtual machine were microscopic, almost impossible to read, and difficult if even possible to configure in the linux desktop. The “zoom factor x2” option in virtualbox was very handy for that, but reduced the actual resolution by a factor of 2 if I understand. Apart from these limitations, the software was running.

We have a working install procedure from one of our friends using a Mac here:

Guests additions: run the Linux additions after mounting the CD and opening its contents.

Shutdown the virtual machine, go to its configuration, and in the 'Display' section, chose 'Graphics Controller: VMSVGA', tick 'Activate 3D acceleration' and increase the 'Video memory' to 128Mb.

Shutdown the virtual machine, go to its configuration, and in the ‘Display’ section, chose ‘Graphics Controller: VMSVGA’, tick ‘Activate 3D acceleration’ and increase the ‘Video memory’ to 128Mb.

setup shared directory to mount the computer filesystem (my user directory). For this I went into the 'shared directory' section of the VM configuration, and asked to have ``/media/olivier`` to point on my home directory (on my Mac: ``/Users/olivier``) .

setup shared directory to mount the computer filesystem (my user directory). For this I went into the ‘shared directory’ section of the VM configuration, and asked to have 

There is an issue to fix before accessing ``/media/olivier``, because of a permission issue. It is fixed by typing the following into the terminal::

  sudo usermod -aG vboxsf $(whoami)

, because of a permission issue. It is fixed by typing the following into the terminal:

there is still a keyboard mapping issue, it can probably be fixed in the linux desktop config somewhere.

Singularity may be a bit touchy to install on Windows, it needs Windows 10 with linux subsystem (WSL2) plus other internal options (hyper-V something). It's possible, not easy.

Singularity may be a bit touchy to install on Windows, it needs Windows 10 with linux subsystem (WSL2) plus other internal options (hyper-V something). It’s possible, not easy.

Once singularity is working, to be able to run graphical programs, a X server must be installed. Several ones exist for Windows, several are free, but most of them do not support hardware-accelerated 3D. `Xming <https://sourceforge.net/projects/xming/>`_ supports hardware acceleration, but has gone commercial. The latest free implementation was released in 2016, and seems to work. Microsoft is possibly working on another implementation.

Once singularity is working, to be able to run graphical programs, a X server must be installed. Several ones exist for Windows, several are free, but most of them do not support hardware-accelerated 3D. 

 supports hardware acceleration, but has gone commercial. The latest free implementation was released in 2016, and seems to work. Microsoft is possibly working on another implementation.

technical:home directory and configuration files in casa-distro containers

casa_distro_admin_command:creating a modified brainvisa distribution