Overview

What is Velocity

Velocity is a tool to help with the maintenance of container build scripts on multiple systems, backends (e.g podman or apptainer) and distros.

Important

While Velocity provides a compatibility layer for Apptainer and Podman, it is still important to have a basic knowledge of how they work and the container building process in general.

How it Works

Velocity works by building a set of containers in a chain so that the final container has all of the needed components.

Important

Velocity maintains a very hands off approach. It is only as good as the templates/configuration that you write. In general it will assume that a particular build will work (on a system, distro etc.) unless you tell it otherwise.

Note

While Velocity has many features that are similar to those provided by a package manager, it is NOT a package manager. Rather it should be viewed as a templating and build orchestration tool.

Installation

The easiest way to install velocity is to install prebuilt python packages using pip.

# note: you will need python 3.10 or greater
pip install olcf-velocity

Alternatively, you can clone the velocity repository and build/install velocity from source.

git clone https://github.com/olcf/velocity.git
cd velocity
pip install build
python3 -m build
# install the built python wheel package the version will depend on what version of velocity you have checked out
# check the dist directory for the exact version
pip install dist/olcf_velocity-<version>-py3-none-any.whl

Now you can use Velocity as a python module! We recommend setting a bash alias for convenience.

$ alias velocity="python3 -m velocity"
$ velocity
usage: velocity [-h] [-v] [-D {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}] [-b BACKEND] [-s SYSTEM] [-d DISTRO] {build,avail,spec} ...

build tool for OLCF containers

positional arguments:
  {build,avail,spec}
    build               build specified container image
    avail               lookup available images
    spec                lookup image dependencies

options:
  -h, --help            show this help message and exit
  -v, --version         program version
  -D {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}, --debug {TRACE,DEBUG,INFO,SUCCESS,WARNING,ERROR,CRITICAL}
                        set debug output level
  -b BACKEND, --backend BACKEND
  -s SYSTEM, --system SYSTEM
  -d DISTRO, --distro DISTRO

See https://github.com/olcf/velocity