bluebuild

bluebuild [command] [options] [recipe]

BlueBuild is a tool for creating custom immutable Linux images based on Universal Blue and Fedora Atomic. It uses YAML recipe files to declaratively define image customizations including packages, scripts, and system configurations.The tool simplifies the process of building custom rpm-ostree images that can be deployed on Fedora Silverblue, Kinoite, or other atomic Fedora variants. Recipes can specify base images, add/remove packages, include custom scripts, and configure system settings.BlueBuild integrates with GitHub Actions for automated CI/CD builds via a reusable GitHub Action; the generate command produces the Containerfile that the build uses. Images are typically hosted on GitHub Container Registry (ghcr.io).Users can switch their existing Fedora Atomic system onto a locally built image with bluebuild switch, or onto a published image with rebase and upgrade. The project provides a library of reusable modules for common customizations like adding Flatpak repositories, configuring fonts, or setting up development tools.

build recipe

Template out the files and build the image with Docker, Podman, or Buildah.

Generate the Containerfile used to build the recipe and print or write it out.

Create a new BlueBuild project in a new directory, based on the official template.

Set up a new BlueBuild project in the current empty directory.

Check a recipe and its modules for errors before building.

Build the image locally, export it as an oci-archive tarball, and rebase or upgrade the running system onto it. Runs as a normal user, asking for sudo only when needed.

Build locally and rebase the current rpm-ostree system onto the resulting image.

Build locally and upgrade the current rpm-ostree system to the resulting image.

Generate an offline ISO installation image from the recipe.

Print shell completions for bash, zsh, fish, and others to stdout.

Upgrade the bluebuild CLI itself to the latest version.

Push the built image to the configured container registry (build command).

Override the container registry to push to (build command).

Rechunk the image layers for more efficient updates (build command).

Enable verbose output.

Display help information.

Requires Podman or Docker for local builds. GitHub Actions integration requires repository write access and container registry credentials. Recipe changes may require complete image rebuilds. Images built locally may differ from CI-built images due to architecture or environment differences.

BlueBuild emerged from the Universal Blue community in 2023 as a way to simplify custom image creation for Fedora Atomic desktops. It was inspired by the growing interest in immutable Linux distributions and the need for user-friendly customization tools. The project provides a higher-level abstraction over raw Containerfile/Dockerfile builds.

podman(1), rpm-ostree(1), docker(1), buildah(1)

Source code · Homepage · Documentation