How to make a custom module

If you want to extend your image with custom functionality that requires configuration, you should create a module.

Creating a new module

1. Open your repository and create a new directory inside the modules/ directory. The name of this directory should be the name of your module.
   • This name will be used as the type: when launching your module.
   • If this name has multiple parts, they should be separated with a dash -.
   • As a guideline for (to be) official modules, the name should be a short and sweet noun or modifier-noun combination, without a -installer or -setup suffix being recommended.
2. Inside your newly created directory, create a file called <name-of-your-module>.sh and paste the following code into it:

   modules/<name-of-your-module>/<name-of-your-module>.sh

   #!/usr/bin/env bash
   set -euo pipefail

   • This makes sure the correct shell is used and errors in your module cause the build to fail.
3. You have now created an empty module and can proceed to coding it.

Coding your module

This guide only includes the bare minimum information to get you started on your coding adventure. Check out the module reference for more technical information about modules.

When being launched, your module receives its configuration as a JSON string as the first argument. It can be read from in bash using jq like this:

modules/<name-of-your-module>/<name-of-your-module>.sh

#!/usr/bin/env bash
set -euo pipefail

# read a single variable from the configuration
# `try` makes the command output 'null' if the key is not found, otherwise it will error out and the build will fail
# the `.["var"]` syntax is optional and could be replaced with the less safe and more error-prone `.var` syntax
VAR=$(echo "$1" | jq -r 'try .["var"]')
echo "$VAR"

# read an array from the configuration
get_json_array ARRAY 'try .["array"][]' "$1"
# loop over the array
for THING in "${ARRAY[@]}"; do
    echo "$THING"
done

In addition to the module’s own configuration, each module has access to a set of environment variables. Check out the module reference’s run environment section for a list.

Though bash is the recommended language to write modules, they can technically be written in any language as long as the .sh is used to launch them while passing the configuration.

Using your module

Your custom modules are available by default in custom images built in the same repository. There is no need to specify the source, you can just use them the same way you can use default modules. If the name of your custom module is the same as a default module’s name, the custom module will always be used instead.

recipe.yml

modules:
    - type: <name-of-your-module>
      option: true