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.5
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_distroDirectory where images and environments are stored. This parameter can be passed on the commandline, or set via the
CASA_BASE_DIRECTORYenvironment 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
trueoryesor1, 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,trueor1.- 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,trueor 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,trueor1.
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.
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_distroDirectory where images and environments are stored. This parameter can be passed on the commandline, or set via the
CASA_BASE_DIRECTORYenvironment 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.
- verbose
default=True
Print more detailed information if value is
yes,trueor1.
publish_user_image¶
Upload a “user” image to the 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)
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.
- 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)
- 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:
bv_maker sourcesbv_maker configurebv_maker buildbv_maker doc- 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 thecasa-runimage, 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)
- 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 tocteston the command-line.ctestis 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} + nameimage: the full path where the user image will be created. Default:{base_directory} + name + extensionversion: the version string that will be set in the user image, e.g. available as theCASA_VERSIONenvironment variable and as theversionmetadata key. This valueversionis passed totime.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
- 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_distroDirectory where images and environments are stored. This parameter can be passed on the commandline, or set via the
CASA_BASE_DIRECTORYenvironment variable.- verbose
default=None
Print more detailed information if value is
yes,trueor1.
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”.
- 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- 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.
- user
default=brainvisa
Name of the user account to use for non root commands.