Module

A module is a self-contained part of the build executed during the build process of an image. Most modules are bash scripts (blue-build/modules), but some default modules are implemented with Containerfile templating directly in blue-build/cli. Modules are configured in the recipe or an external configuration file.

Default configuration options

Modules themselves differ on what configuration options they use and require, and that information is available on module-specific reference pages. These options are always available.

type:

The name of the module to run. This corresponds to the name of the directory as well as the script’s name in the module’s directory. For example, using test would call the script in $MODULE_DIRECTORY/test/test.sh.

source: (optional)

Caution

A module can execute arbitrary code both in the image build and consequently on your booted system, so make sure you trust the source you specify.

The URL of the module repository (an OCI image) to pull the module from. If left unspecified, the source use is a hybrid the default module repository at ghcr.io/blue-build/modules and the custom modules in the local modules/ directory, where custom modules overwrite the default modules.

no-cache: (optional)

When set to true, the module is run regardless if previous layers in the build have been cached. This is useful in stages where the goal is to build the latest version of a program from a git repository. Otherwise, the module wouldn’t run again unless previous layers were also re-ran.

How modules are launched

A module added into an image’s configuration is turned into a RUN-statement that launches the module with a JSON version of its configuration in the generated Containerfile (or an equivalent dynamic bash command if using the legacy template).

For example, the following module configuration would be turned into the RUN-statement below:

recipes/module.yml

type: rpm-ostree
install:
    - micro
uninstall:
    - firefox
    - firefox-langpacks

Containerfile

# the contents of this statement have been simplified slightly to better illustrate the topic on hand
RUN /tmp/modules/rpm-ostree/rpm-ostree.sh '{"type":"rpm-ostree,"from-file":"module.yml","repos":null,"install":["micro"],"remove":["firefox","firefox-langpacks"]}'

Module run environment

Every module is ran in an environment containing the following environment variables and functions.

CONFIG_DIRECTORY

Environment variable containing the path to the files for the build (/tmp/files or /tmp/config).

MODULE_DIRECTORY

Environment variable containing the path to the directory containing all the modules of the module repository the current module is from (/tmp/modules).

IMAGE_NAME

Environment variable containing the name of the image declared in recipe.yml.

IMAGE_REGISTRY

Environment variable containing the registry URL and namespace (usually ghcr.io/<username>). Can be used with IMAGE_NAME to get the full image URL.

BASE_IMAGE

Environment variable containing the URL of the OCI image used as the base.

OS_VERSION

Environment variable containing the major version of running operating system. The value is gathered from the VERSION_ID in /etc/os-release.

get_json_array

Bash function that helps with reading arrays from the module’s configuration.

get_json_array OUTPUT_VAR_NAME 'try .key.to.array[]' "${1}"

or less readable, but safer command for extracting array values:

get_json_array OUTPUT_VAR_NAME 'try .["key"].["to"].["array"][]' "${1}"

module.yml

A module.yml is the metadata file for a public module, used on the website to generate module reference pages. May be used in future projects to showcase modules and supply some defaults for them.

name:

The name of the module, same as the name of the directory and script.

shortdesc:

A short description of the module, ideally not more than one sentence long. This is used in website metadata or anywhere a shorter module description is needed.

example:

A YAML string of example configuration showcasing the configuration options available with inline documentation to describe them.