Skip to content
BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak. BlueBuild

recipe.yml

A recipe.yml file describes the build process of a custom image. The top-level keys set the metadata and base for the image, and modules are build steps that add things on top of the base.

name:

Section titled “name:”

The image name. Used when publishing to GHCR as ghcr.io/<user>/<name>.

Example:

Section titled “Example:”
recipes/recipe.yml
name: weird-os

description:

Section titled “description:”

The image description. Published to GHCR in the image metadata.

Example:

Section titled “Example:”
recipes/recipe.yml
description: This is my personal OS image.

alt-tags: (optional)

Section titled “alt-tags: (optional)”

Allows setting custom tags on the recipe’s final image. Adding tags to this property will override the latest and timestamp tags.

Example:

Section titled “Example:”
alt-tags:
  - gts
  - stable

base-image:

Section titled “base-image:”

The OCI image to base your custom image on. Only atomic Fedora images and those based on them are officially supported. Universal Blue is recommended. A list of uBlue images can be found on the uBlue website. BlueBuild-built images can be used as well.

Example:

Section titled “Example:”
recipes/recipe.yml
base-image: ghcr.io/ublue-os/silverblue-main

image-version:

Section titled “image-version:”

The tag of the base image to build on. Used to select a version explicitly (40) or to always use the latest stable version (latest). A list of all available tags can be viewed by pasting your base-image url into your browser.

Example:

Section titled “Example:”
recipes/recipe.yml
image-version: 40

blue-build-tag: (optional)

Section titled “blue-build-tag: (optional)”

Version of the BlueBuild CLI to pull into your image. Supply the tag of the cli release container to pull, see the list of available tags for reference. Useful for testing out pre-release versions of BlueBuild CLI. Default: latest-installer. Set to to none to opt out of installing the CLI into your image.

nushell-version: (optional)

Section titled “nushell-version: (optional)”

Version of nushell to pull to /usr/libexec/bluebuild/nu/nu for use by modules. Change only if you need a specific version of Nushell, changing this might break some BlueBuild modules. Set to to none to opt out of installing Nushell into your image (this will break modules that depend on it).

stages: (optional)

Section titled “stages: (optional)”

A list of stages that are executed before the build of the final image. This is useful for compiling programs from source without polluting the final bootable image.

Example:

Section titled “Example:”
stages:
  - name: bluebuild
    from: docker.io/library/rust:1.77
    modules: # same as the top-level modules key, but executed in the custom stage
      - type: script
        no-cache: true
        snippets:
          - cargo install --locked --all-features blue-build

modules:

Section titled “modules:”

A list of modules that is executed in order. Multiple of the same module can be included.

Each item in this list should have at least a type: or be specified to be included from an external file in the recipes/ directory with from-file:.

Example:

Section titled “Example:”
recipes/recipe.yml
modules:
  - type: rpm-ostree
    # rest of the module config...
  - from-file: common-packages.yml

The included file can have one or multiple modules:

recipes/common-packages.yml
# one module
type: rpm-ostree
# rest of the module config...
recipes/common-packages.yml
# multiple modules
modules:
  - type: script
    # rest of the module config...
  - type: rpm-ostree
    # rest of the module config...