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:

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

Example:

recipes/recipe.yml

name: weird-os

description:

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

Example:

recipes/recipe.yml

description: This is my personal OS image.

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:

alt-tags:
  - gts
  - stable

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:

recipes/recipe.yml

base-image: ghcr.io/ublue-os/silverblue-main

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:

recipes/recipe.yml

image-version: 40

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:

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:

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:

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