BlueBuild

BlueBuild's command line program that builds Containerfiles and custom images based on your recipe.yml.

Installation

Distrobox

We package a fedora-toolbox and alpine image with all the tools needed to run bluebuild. You can use distrobox to run the application without needing to install it on your machine.

distrobox create blue-build --image ghcr.io/blue-build/cli
distrobox enter blue-build

Cargo

This is the best way to install as it gives you the opportunity to bulid for your specific environment.

cargo install --locked blue-build

Podman/Docker

This will install the binary on your system in /usr/local/bin. This is only a linux-gnu version.

podman run --rm ghcr.io/blue-build/cli:latest-installer | bash

Nix Flake

You can install this CLI through the Nix flake on Flakehub

Non-nixos

You can install BlueBuild to your global package environment on non-nixos systems by running

# you can replace "*" with a specific tag
nix profile install https://flakehub.com/f/bluebuild/cli/*.tar.gz#bluebuild

NixOS

If you are using a dedicated flake to manage your dependencies, you can add BlueBuild as a flake input throught the fh cli (that can be installed through nixpkgs) and add bluebuild to it.

{pkgs,inputs,...}: {
    ...
    environment.SystemPackages = [
        inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name 
    ];
    ...
}

If you are not using a dedicated nix flake, you can add the BlueBuild flake as a variable inside your /etc/nixos/*.nix configuration, though this requires you to run nixos-rebuild with the --impure variable, it is not advisable to do so.

{pkgs,...}:
let
    bluebuild = builtins.fetchTarball "https://flakehub.com/f/bluebuild/cli/*.tar.gz";
in {
    ...
    environment.SystemPackages = [
        bluebuild.packages.${pkgs.system}.bluebuild
    ];
    ...
}

You can also use nix develop .# in this repos directory to run a nix shell with development dependencies and some helful utilities for building BlueBuild!

Github Install Script

bash <(curl -s https://raw.githubusercontent.com/blue-build/cli/main/install.sh)

How to use

Templating

Once you have the CLI tool installed, you can run the following to pull in your recipe file to generate a Containerfile.

bluebuild template -o <CONTAINERFILE> <RECIPE_FILE>

You can then use this with podman or buildah to build and publish your image. Further options can be viewed by running bluebuild template --help

Building

If you don't care about the details of the template, you can run the build command.

bluebuild build ./config/recipe.yaml

This will template out the file and build with buildah or podman.

Local Builds

Rebase

If you want to test your changes, you can do so by using the rebase command. This will create an image as a .tar.gz file, store it in /etc/bluebuild, an run rpm-ostree rebase on that newly built file.

sudo bluebuild rebase config/recipe.yml

You can initiate an immediate restart by adding the --reboot/-r option.

Upgrade

When you've rebased onto a local image archive, you can update your image for your recipe by running:

sudo bluebuild upgrade config/recipe.yml

The --reboot argument can be used with this command as well.

CI Builds

GitHub

You can use our GitHub Action by using the following .github/workflows/build.yaml:

name: bluebuild
on:
  schedule:
    - cron: "00 17 * * *" # build at 17:00 UTC every day 
                          # (20 minutes after last ublue images start building)
  push:
    paths-ignore: # don't rebuild if only documentation has changed
      - "**.md"
  pull_request:
  workflow_dispatch: # allow manually triggering builds
jobs:
  bluebuild:
    name: Build Custom Image
    runs-on: ubuntu-22.04
    permissions:
      contents: read
      packages: write
      id-token: write
    strategy:
      fail-fast: false # stop GH from cancelling all matrix builds if one fails
      matrix:
        recipe:
          # !! Add your recipes here 
          - recipe.yml
    steps:
       # the build is fully handled by the reusable github action
      - name: Build Custom Image
        uses: blue-build/github-action@v1.0.0
        with:
          recipe: ${{ matrix.recipe }}
          cosign_private_key: ${{ secrets.SIGNING_SECRET }}
          registry_token: ${{ github.token }}
          pr_event_number: ${{ github.event.number }}

Gitlab

If you're running in Gitlab CI, it will automatically sign your image using Gitlab's own OIDC service. Here's an example of a .gitlab-ci.yaml:

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"
      when: never
    - if: "$CI_COMMIT_TAG"
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: "$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS"
      when: never
    - if: "$CI_COMMIT_BRANCH"
stages:
  - build
variables:
  ACTION:
    description: "Action to perform for the pipeline."
    value: "build-image"
    options:
      - "build-image"
build-image:
  stage: build
  image: ghcr.io/blue-build/cli:latest-alpine
  retry: 2
  rules:
    - if: $ACTION == "build-image"
  parallel:
    matrix:
      - RECIPE:
          - recipe.yml
  id_tokens:
    SIGSTORE_ID_TOKEN:
      aud: sigstore
  script:
    - bluebuild build --push ./config/$RECIPE

Future Features

• Update to the most recent stable style of the starting point template
• Setup pipeline automation for publishing
• Create an init command to create a repo for you to start out
• Setup the project to allow installing with binstall
• Create an install script for easy install for users without cargo