diff --git a/README.md b/README.md index 93c34df..6b8b37e 100644 --- a/README.md +++ b/README.md @@ -21,51 +21,69 @@ preferably as root. The script ***must*** be passed the version number of [the release to install](https://github.com/containers/automation/releases). Alternatively it may be passed `latest` to install the HEAD of the main branch. -For example, to install the `v1.0.0` release, run: -```sh -# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' -# curl -sL "$url" | bash -s 1.1.3 +For example, to install the `v1.1.3` release, run: +```bash +~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' +~# curl -sL "$url" | bash -s 1.1.3 ``` To install `latest`, run: -```sh -# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' -# curl -sL "$url" | bash -s latest +```bash +~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' +~# curl -sL "$url" | bash -s latest ``` -Optionally, the installer may also be passed the names of one or more components to -install system-wide. For example: - -To install the latest `build-push`, run: -```sh -# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' -# curl -sL "$url" | bash -s latest build-push -``` - -## Alt. Installation +### Alt. Installation If you're leery of piping to bash and/or a local clone of the repository is already available locally, the installer can be invoked with the *magic version* '0.0.0'. -Note that this will limit the install to the local clone (as-is), the installer script +Note this will limit the install to the local clone (as-is). The installer script will still reach out to github.com to retrieve version information. For example: -```sh -# cd /path/to/clone -# ./bin/install_automation.sh 0.0.0 +```bash +~# cd /path/to/clone +/path/to/clone# ./bin/install_automation.sh 0.0.0 +``` + +### Component installation + +The installer may also be passed the names of one or more components to +install system-wide. Available components are simply any subdirectory in the repo +which contain a `.install.sh` file. For example, to install the latest `build-push` system-wide run: + +```bash +~# url='https://github.com/containers/automation/releases/latest/download/install_automation.sh' +~# curl -sL "$url" | bash -s latest build-push ``` ## Usage The basic install consists of copying the contents of the `common` (subdirectory) and the installer script into a central location on the system. Because this location -can vary, a global shell variable `$AUTOMATION_LIB_PATH` is widely used. Therefore, -it is highly recommended that all users and calling scripts explicitly load and export -env. var. definitions set in the file `/etc/automation_environment`. For example: - -```sh -# set -a -# source /etc/automation_environment -# set +a +can vary by platform, a global shell variable `$AUTOMATION_LIB_PATH` is established +by a central configuration at install-time. It is highly recommended that all +callers explicitly load and export the contents of the file +`/etc/automation_environment` before making use of the common library or any +components. For example: + +```bash +#!/bin/bash + +set -a +if [[ -r "/etc/automation_environment" ]]; then + source /etc/automation_environment +fi +set +a + +if [[ -n "$AUTOMATION_LIB_PATH" ]]; then + source $AUTOMATION_LIB_PATH/common_lib.sh +else + ( + echo "WARNING: It doesn't appear containers/automation common was installed." + ) > /dev/stderr +fi + +...do stuff... ``` @@ -81,18 +99,41 @@ This directory contains scripts intended for execution under multiple environmen pertaining to operations on this whole repository. For example, executing all unit tests, installing components, etc. +### `build-push` + +Handy automation too to help with parallel building and pushing container images, +including support for multi-arch (via QEMU emulation). See the +[README.md file in the subdirectory](build-push/README.md) for more information. + +### `cirrus-ci_artifacts` + +Handy python script that may be used to download artifacts from any build, +based on knowing its ID. Downloads will be stored properly nested, by task +name and artifact so there are no name clashes. + +### `cirrus-ci_env` + +Python script used to minimally parse `.cirrus.yml` tasks as written/formatted +in other containers projects. This is not intended to be used directly, but +called by other scripts to help extract env. var. values from matrix tasks. + +### `cirrus-ci_retrospective` + +See the [README.md file in the subdirectory](cirrus-ci_retrospective/README.md) for more information. + +### `cirrus-task-map` + +Handy script that parses a `.cirrus.yml` and outputs an flow-diagram to illustrate +task dependencies. Useful for visualizing complex configurations, like that of +`containers/podman`. + ### `common` This directory contains general-purpose scripts, libraries, and their unit-tests. They're intended to be used individually or as a whole from within automation of other repositories. -### `cirrus-ci_retrospective` - -See the [README.md file in the subdirectory](cirrus-ci_retrospective/README.md) for more information - -### `build-push` +### `github` -Handy automation too to help with parallel building and pushing container images, -including support for multi-arch (via QEMU emulation). See the -[README.md file in the subdirectory](build-push/README.md) for more information. +Contains some helper scripts/libraries for using `cirrus-ci_retrospective` from +within github-actions workflow. Not intended to be used otherwise. diff --git a/build-push/README.md b/build-push/README.md index c468c1b..9e3747e 100644 --- a/build-push/README.md +++ b/build-push/README.md @@ -23,25 +23,26 @@ it may be useful on its own, this is not its primary purpose. ## QEMU-user-static Emulation -On platforms/distro's that support it, this is a handy way to enable -non-native binary execution. This can therefore be used to support -building container images for other architectures. Though other -techniques may be possible, there are [handy/dandy scripts and -container images available to help configure -this.](https://github.com/multiarch/qemu-user-static#multiarchqemu-user-static-images) - -Using this in a reliable way under automation suggests pointing it -at the host's qemu-user-staic binaries instead of those bundled in -the container image (which may not even match the host platform). -Fortunately passing those in via volume-mount is pretty trivial. -Something like this (as **root** in Fedora): +On platforms/distro's that support it (Like F34+) this is a handy +way to enable non-native binary execution. It can therefore be +used to build container images for other non-native architectures. +Though setup may vary by distro/version, in F34 all that's needed +is to install the `qemu-user-static` package. It will take care +of automatically registering the emulation executables with the +kernel. + +Otherwise, you may find these [handy/dandy scripts and +container images useful](https://github.com/multiarch/qemu-user-static#multiarchqemu-user-static-images) for environments without native support (like +CentOS and RHEL). However, be aware I cannot atest to the safety +or quality of those binaries/images, so use them at your own risk. +Something like this (as **root**): ```bash -$ sudo dnf install -y qemu-user-static -$ qemu_setup_fqin="docker.io/multiarch/qemu-user-static:latest" -$ vol_awk='{print "-v "$1":"$1""}' -$ bin_vols=$(find /usr/bin -name 'qemu-*-static' | awk -e "$vol_awk" | tr '\n' ' ') -$ sudo podman run --rm --privileged $bin_vols $qemu_setup_fqin --reset -p yes +~# install qemu user static binaries somehow +~# qemu_setup_fqin="docker.io/multiarch/qemu-user-static:latest" +~# vol_awk='{print "-v "$1":"$1""}' +~# bin_vols=$(find /usr/bin -name 'qemu-*-static' | awk -e "$vol_awk" | tr '\n' ' ') +~# podman run --rm --privileged $bin_vols $qemu_setup_fqin --reset -p yes ``` Note: You may need to alter `$vol_awk` or the `podman` command line