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

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

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

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:

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:

bluebuild generate -d ./recipes/recipe.yml

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:

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.

Rebase/Upgrade

Caution

These commands will be replaced by switch in v0.9.0. It will be aliased with rebase and upgrade so as to not break existing scripts. Right now, upgrade must be called when building the same image you called rebase on earlier. The switch command removes this ambiguity.

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

bluebuild rebase ./recipes/recipe.yml

After you’ve rebased, you can use the upgrade command to do the same thing except call rpm-ostree upgrade. To trigger an immediate reboot for either command, you can pass in the --reboot/-r argument.