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

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...