Mastodon Skip to content


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.


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/

source: (optional)

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 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 would be turned into the RUN-statement below:

type: rpm-ostree
- micro
- firefox
- firefox-langpacks
# the contents of this statement have been simplified slightly to better illustrate the topic on hand
RUN /tmp/modules/rpm-ostree/ '{"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.


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


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


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


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


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


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

get_yaml_array OUTPUT_VAR_NAME '[]' "$1"


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.


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


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.


The URL to the raw contents of the module’s in plain text, not HTML. The README may include a top-level heading for readability, but it will be stripped out in favor of name: when the README is ingested for the website.


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