The casa_distro_admin command

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

HELP, format: rst 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

Version : 3.0.2

usage:

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.

Common parameters:

Most commands accept more or less the same parameters.

Many subcommands need environment selection specifications: see the documentation on how to specify an environment.

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.

Commands:

help

Print global help or help about a command.

Parameters

format
format help text in a given text format. Valid values are “text” (default) for raw text, or rst (RST/sphinx format).
full
if true or yes or 1, display each subcommand parameters documentation in the general help.

singularity_deb

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.

Parameters

system
Name of the system for the output file. If dockerhub is not given, a value is built based on this parameter
output
default=singularity-container-{version}-{system}.deb Location of the resulting Debian package file.
dockerhub
default=name of the system replacing “-” by “:” Name of the base image system to pull from DockerHub.
version
default=3.7.0 Version of Singularity to use. This must be a valid release version.
go_version
default=1.15.6 Version of Go language to install during Singularity building process. Go language is not included in the final package.

singularity_debs

Create all required Singularity debian packages in a directory. Packages that must be build have a corresponding singularity-container-*.deb.json file with the following structure:

{

“singularity_version”: “3.7.0”, required Singularity version “go_version”: “1.15.6”, Go version to use to build Singularity “system”: {

“name”: “ubuntu”, Name of the target system “version”: “20.04”, Version of the targer system “dockerhub”: “ubuntu:20.04” System image to pull on DockerHub

}

}

The command makes sure that all .deb files corresponding to a *.deb.json file exists. If not, they are created with singularity_deb command.

Parameters

directory
Name of directory containing JSON files and where deb files might be created

create_base_image

Create a new virtual image

Creating the casa-system image:

  • 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 casa_distro_admin create_base_image type=system base=ubuntu-18.04.sif

  • For VirtualBox: TODO

Parameters

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.
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 use to buld 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”.

image_version

default=1.0

Version (or branch) of the image

verbose

default=True

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

cleanup (allowed 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
force (allowed only if container_type=singularity)

default=no

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

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)

default=no

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

publish_base_image

Upload an image to BrainVISA web site. Upload is done with rsync in the following remote directory:

brainvisa@brainvisa.info:/var/www/html/brainvisa.info_download/

This directory location can be customized with 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)

Parameters

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
Force usage of a specific virtual image instead of the one defined in the environment configuration.
container_type
default=singularity 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.

create_user_image

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 developement 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” :

  • 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 developement environment. The ne image is based on base_image and the installation directory of the development environment is copied into the image in /casa/install.
  • upload: upload the user image on BrainVISA web site.

Parameters

version [REQUIRED]
Version of the release to create.
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
distro

default=None

If given, select environment having the given distro name.

branch

default=None

If given, select environment having the given branch.

system

default=None

If given, select environments having the given system name.

image_version

default=None

If given, select environments having the given image version.

environment_name
If given, select dev environment by its name.
container_type
default=None Type of virtual appliance to use. Either “singularity”, “vbox” or “docker”.
output
default={base_directory}/{name}{extension} Path of the output image.
force
default=no If “yes”, “true” or 1, erase existing image without asking any question.
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.

install
default=yes 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
install_doc
default=yes 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
default=yes If “true”, “yes” or “1”, run ‘make install-test’ as part of the install step. If “false”, “no” or “0”, skip this step
generate
default=yes If “true”, “yes” or “1”, perform the image creation step. If “false”, “no” or “0”, skip this step
zip
default=no If “true”, “yes” or “1”, zip the installed files for an “online” installation.
upload

default=no If “true”, “yes” or “1”, upload the image on BrainVISA web site. If “false”, “no” or “0”, skip this step Upload is done with rsync in the following remote directory:

brainvisa@brainvisa.info:/var/www/html/brainvisa.info_download/

This directory location can be customized with 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)
verbose

default=True

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

bbi_daily

BrainVISA Build infrastructure: daily/nightly automated tests

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 Automated tests with bbi_daily for a complete introduction to automated tests.

  1. Self-update casa_distro using ‘git pull’ and restart itself for the next steps
  2. Select dev environments based on the provided filters (distro, branch, system, image_version, name)
  3. Update casa-dev and casa-run images used by the selected environments to the latest version available from the BrainVISA website
  4. 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

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"]).
  • 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 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…).

Parameters

distro

default=None

If given, select environment having the given distro name.

branch

default=None

If given, select environment having the given branch.

system

default=None

If given, select environments having the given system name.

image_version

default=None

If given, select environments having the given image version.

name

default=None

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

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
default = yes 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
default = yes Boolean indicating if the tests must be performed on dev environments
update_user_images
default = yes Boolean indicating if images of user environment must be recreated
install_doc
default = yes Boolean indicating if the documentation must be installed in user images
recreate_user_envs
default = yes Boolean indicating if user environments must be wiped and recreated using singularity –bind <dir>:/casa/setup …
user_tests
default = yes Boolean indicating if the tests must be performed on user environments
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.

verbose

default=None

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

local_install

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.

Parameters

type
Type of image to install. Either “run” or “dev”.
steps

default=None

Installation steps to perform. If not given, the steps not yet done are displayed. Can be a comma separated list of step names or “all” to perform all steps not already done or “next” to perform only the next undone step.

system

default=*

System to used when searching for an image builder file. This is used as a shell pattern, the default value match any system.

log_file

default=/etc/casa_local_install.log

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

action

default=None

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
user

default=brainvisa

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

Images and releases creation

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.

Creation a base VirtualBox image

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.

  1. Install VirtualBox version 6 or greater
  2. Download an Ubuntu iso file from internet (any Debain based distro may work but only recent Ubuntu LTS are tested).
  3. Run casa_distro_admin create_system to create an empty VirtualBox image with appropriate base settings (e.g. enough maximum disk size)
  4. Perform Ubuntu minimal installation with an autologin account named “brainvisa” and with password “brainvisa”
  5. Perform system updates and install kernel module creation packages :
sudo apt update
sudo apt upgrade
sudo apt install gcc make perl
  1. Set root password to “brainvisa” (this is necessary to automatically connect to the VM to perform post-install)
  2. Reboot the VM
  3. Download and install VirtualBox guest additions
  4. Shut down the VM
  5. Configure the VM in VirualBox (especially 3D acceleration, processors and memory)

Managing container images

Singularity and Docker

In a general way, we designed casa-distro first using Docker, and then extended it to Singularity. 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.

Sharing images

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

By default publish_docker will use Docker Hub, 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, which also requires to have access to the website account to push. We could use Singularity Hub in the future.

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

Designing new images

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.

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.

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

  • <workflow_repository>/share/docker/<image_name>/<system>
  • $HOME/.config/casa-distro/docker/<image_name>/<system>
  • $HOME/.casa-distro/docker/<image_name>/<system>
  • <casa_builtin>/docker/<image_name>/<system>

where:

  • <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.

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:
dependencies:
    - ../../casa-dev
image_sources:
  - name: pytorch
    tags:
      - ubuntu-16.04
    visibility: public
  • a Dockerfile 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.