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

How to build and test locally

This guide shows you how to use Bluebuild CLI to do the following things locally, without depending on the BlueBuild GitHub Action:

  • preview the Containerfile generated your recipe.yml locally;
  • test your recipe.yml build process locally before pushing to GitHub;
  • install a locally built image onto a virtual machine;
  • rebase your currently running operating system onto a locally built image;

Installing BlueBuild CLI

Section titled “Installing BlueBuild CLI”

The BlueBuild CLI tool is installed by default on images built using BlueBuild. There are also several methods available for installing the BlueBuild CLI tool, documented in the BlueBuild CLI README.

Using BlueBuild CLI

Section titled “Using BlueBuild CLI”

The repository README has general instructions for using the bluebuild CLI tool. Example use cases for some of the commands follow in the sections below. You can also view the help text for the commands using the --help argument on every subcommand.

Generate

Section titled “Generate”

The generate command allows you to create the Containerfile used to build your recipe. It will print to stdout unless you use the --output/-o <FILE_PATH> argument:

Terminal window
bluebuild generate ./recipes/recipe.yml -o Containerfile

If your recipe makes use of the from-file: syntax, it can sometimes get confusing to know the exact order of all the module calls in your recipe. You can make use of the --display-full-recipe/-d argument and it will generate your full recipe.yml file with all recipe snippets included:

Terminal window
bluebuild generate -d ./recipes/recipe.yml

Build

Section titled “Build”

The build command builds an image from a recipe; you can use this command to test your recipe locally before pushing the recipe to GitHub:

Terminal window
bluebuild build ./recipes/recipe.yml

You can see that the BlueBuild GitHub Action uses the same build command, with additional --push and --registry options for pushing successful build to ghcr.io or similar image repositories.

You can see the complete list of available options using bluebuild build --help.

Switch

Section titled “Switch”

The switch command is a workflow command. It will build your image, export it to a .tar.gz file, and call rpm-ostree rebase/rpm-ostree upgrade with the file as the target instead of a OCI image:

Terminal window
bluebuild switch ./recipes/recipe.yml

To trigger an immediate reboot for either command, you can pass in the --reboot/-r argument.