bluebuild

Build a recipe

$ bluebuild build [path/to/recipe.yml]

$ bluebuild validate [path/to/recipe.yml]

$ bluebuild generate [[-o|--output]] [Containerfile] [path/to/recipe.yml]

$ bluebuild generate-iso --output-dir [path/to/output_directory] --iso-name [iso_name.iso] recipe [path/to/recipe.yml]

$ bluebuild [[-h|--help]]

bluebuild command [options]
bluebuild build [directory] [options]
bluebuild init [directory]
bluebuild validate [directory]

build
    Initiates the image building process based on the bluebuild.yaml file found in the specified or current directory.

init
    Initializes a new bluebuild project directory with a sample bluebuild.yaml configuration, providing a starting point for custom images.

validate
    Checks the syntax and validity of the bluebuild.yaml configuration file without performing a full image build.

--debug
    Enables verbose debug logging, providing more detailed output for troubleshooting during command execution.

--git-ref TEXT
    Specifies the OSTree reference (e.g., fedora/39/x86_64/kinoite) for the base image that bluebuild will use to layer on top of.

--tag TEXT
    Assigns a specific tag to the built container image (e.g., ublue-os/kinoite-main:latest) for easier identification and deployment.

--push
    Instructs bluebuild to push the successfully built container image to a configured container registry (e.g., Docker Hub, Quay.io).

--sign
    Digitally signs the built container image, providing integrity and authenticity verification.

--source-date YYYY-MM-DD
    Sets the source date for reproducible builds, aiming to ensure that the same inputs always produce identical image outputs.

--cache-dir DIRECTORY
    Specifies an alternative directory for caching build artifacts, which can significantly speed up subsequent builds by reusing previously downloaded components.

--temp-dir DIRECTORY
    Specifies an alternative directory for temporary files generated during the build process, useful for managing disk space.

bluebuild is a command-line tool designed to simplify the creation of custom Fedora rpm-ostree images, such as those used by Fedora Silverblue, Kinoite, and IoT. It allows users to declaratively define their desired image configuration—including layered packages, custom services, and filesystem modifications—within a bluebuild.yaml file.

By abstracting the complexities of rpm-ostree commands and container image building, bluebuild enables reproducible and maintainable custom operating system images. It is a core component of the Universal Blue (UBlue) project, aiming to make immutable desktop Linux more accessible and customizable. bluebuild leverages containerization (e.g., Podman) to build the image layers and applies them to an rpm-ostree base, resulting in a ready-to-deploy ostree commit.

bluebuild is a specialized tool primarily designed for building custom rpm-ostree images, such as those found in Fedora Silverblue, Kinoite, and IoT. It is not a general-purpose package manager or build system for traditional Linux distributions.

It requires a functional container runtime (like Podman or Docker) for its operations and depends heavily on the declarative configuration provided in the bluebuild.yaml file rather than extensive command-line options. Its primary audience is users and developers working within the immutable Linux ecosystem.

bluebuild heavily relies on a YAML configuration file (typically named bluebuild.yaml) located in the project directory. This file is the primary interface for customizing the image build, defining elements such as the base image, layered RPM packages, rpm-ostree services, systemd units, ujust commands, and other filesystem modifications. It enables reproducible and version-controlled image configurations, acting as the blueprint for your custom OS.

A key goal of bluebuild is to facilitate reproducible image builds. By leveraging features like --source-date and precise dependency management defined in the bluebuild.yaml, it aims to produce identical image outputs from the same inputs, contributing to more reliable and consistent image deployments across different environments. This ensures that a build created today will be the same as one created months later, given the same configuration.

bluebuild emerged from the Universal Blue (UBlue) project, an initiative focused on making rpm-ostree based immutable operating systems more accessible and customizable for end-users. It was created to provide a simpler, declarative interface for building custom images, automating the complex steps involving rpm-ostree commands and container image management. Its development reflects the growing interest in immutable Linux desktops and the need for user-friendly tools to manage and personalize them.

rpm-ostree(8), ostree(1), podman(1), docker(1), bootc(1)