Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/blue-build/cli

BlueBuild's command line program that builds Containerfiles and custom images based on your recipe.yml.
https://github.com/blue-build/cli

cli cli-tool fedora fedora-silverblue ublue ublue-os

Last synced: about 2 months ago
JSON representation

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

Host: GitHub
URL: https://github.com/blue-build/cli
Owner: blue-build
License: apache-2.0
Created: 2024-01-21T16:32:34.000Z (8 months ago)
Default Branch: main
Last Pushed: 2024-05-29T03:01:18.000Z (4 months ago)
Last Synced: 2024-05-29T14:29:51.388Z (4 months ago)
Topics: cli, cli-tool, fedora, fedora-silverblue, ublue, ublue-os
Language: Rust
Homepage: https://blue-build.org/
Size: 1000 KB
Stars: 40
Watchers: 5
Forks: 6
Open Issues: 19
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

# BlueBuild

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

## Requirements

The `bluebuild` tool takes advantage of newer build features. Specifically bind, cache, and tmpfs mounts on the `RUN` instructions. We support using the following tools and their versions:

- Docker - v23 and above
- Podman - v4 and above
- Buildah - v1.24 and above

## Installation

### Cargo

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

```bash
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.

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

```bash
docker run --pull always --rm ghcr.io/blue-build/cli:latest-installer | bash
```

### Github Install Script

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

### Distrobox

[distrobox-export-documentation]: https://distrobox.it/usage/distrobox-export/

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.

```bash
# fedora-toolbox
distrobox create blue-build --image ghcr.io/blue-build/cli
# alpine
distrobox create blue-build --image ghcr.io/blue-build/cli:latest-alpine
```

By default, the bluebuild commands will not be visible outside of the distrobox itself. You will need to **enter** the distrobox, and either run the commands from inside the distrobox, or **export** the distrobox commands for use outside the distrobox.

Refer to the [distrobox documentation][distrobox-export-documentation] for more information.

#### Running commands from within distrobox

```bash
[user@host]$ bluebuild help
ERROR
[user@host]$ distrobox enter blue-build
[user@blue-build]$ bluebuild help
A CLI tool built for creating Containerfile templates based on the Ublue Community Project
...
```

#### Exporting commands to run outside distrobox

```bash
[user@blue-build]$ distrobox-export --bin $(which bluebuild)
[user@blue-build]$ exit
[user@host]$ bluebuild help
A CLI tool built for creating Containerfile templates based on the Ublue Community Project
...
```

### Nix Flake

You can install this CLI through the Nix flake on [Flakehub](https://flakehub.com/)

#### Non-nixos

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

```shell
# 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](https://github.com/DeterminateSystems/fh) cli (that can be installed through nixpkgs) and add `bluebuild` to it.
```nix
{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.

```nix
{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!

## How to use

### Generating `Containerfile`

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

```bash
bluebuild generate -o
```

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.

```bash
bluebuild build ./recipes/recipe.yaml
```

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

### Completions

The `bluebuild completions` command generates shell completions, printed to stdout. These completions can be stored for integration in your shell environment. For example, on a system with [bash-completion](https://github.com/scop/bash-completion/) installed:

```bash
# user completions
$ bluebuild completions bash > ~/.local/share/bash-completion/completions/bluebuild
# system-wide completions
$ bluebuild completions bash | sudo tee /usr/share/bash-completion/completions/bluebuild
```

Subsequent invocations of `bluebuild` will respond to `` autocompletions:

```bash
$ bluebuild # press
-v -V --help template bug-report
-q --verbose --version upgrade completions
-h --quiet build rebase help
```

Currently, bluebuild completions are available for `bash`, `zsh`, `fish`, `powershell`, and `elvish` shell environments.

#### 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.

```bash
sudo bluebuild rebase recipes/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:

```bash
sudo bluebuild upgrade recipes/recipe.yml
```

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

##### Switch

> NOTE: This is an unstable feature and can only be used when installing from the `main` image or with the `switch` feature flag when compiling.

With the switch command, you can build and boot an image locally using an `oci-archive` tarball. The `switch` command can be run as a normal user and will only ask for `sudo` permissions when moving the archive into `/etc/bluebuild`.

```bash
bluebuild switch recipes/recipe.yml
```

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

#### CI Builds

##### GitHub

You can use our [GitHub Action](https://github.com/blue-build/github-action) by using the following `.github/workflows/build.yaml`:

```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-latest
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/[email protected]
with:
recipe: ${{ matrix.recipe }}
cosign_private_key: ${{ secrets.SIGNING_SECRET }}
registry_token: ${{ github.token }}
pr_event_number: ${{ github.event.number }}
```

##### Gitlab

We also support GitLab CI! Fun fact, this project started out as a way to build these images in GitLab. You will want to make use of GitLab's [Secure Files](https://docs.gitlab.com/ee/ci/secure_files/index.html) feature for using your cosign private key for signing. Here's an example of a `.gitlab-ci.yml`:

```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

build-image:
stage: build
image:
name: ghcr.io/blue-build/cli:main
entrypoint: [""]
services:
- docker:dind
parallel:
matrix:
- RECIPE:
# Add your recipe files here
- recipe.yml
variables:
# Setup a secure connection with docker-in-docker service
# https://docs.gitlab.com/ee/ci/docker/using_docker_build.html
DOCKER_HOST: tcp://docker:2376
DOCKER_TLS_CERTDIR: /certs
DOCKER_TLS_VERIFY: 1
DOCKER_CERT_PATH: $DOCKER_TLS_CERTDIR/client
before_script:
# Pulls secure files into the build
- curl --silent "https://gitlab.com/gitlab-org/incubation-engineering/mobile-devops/download-secure-files/-/raw/main/installer" | bash
- export COSIGN_PRIVATE_KEY=$(cat .secure_files/cosign.key)
script:
- sleep 5 # Wait a bit for the docker-in-docker service to start
- bluebuild build --push ./recipes/$RECIPE
```

## Future Features

- Stages for parallel building (useful for compiling programs for your image)
- Automatic download and management of image keys for seamless signed image rebasing
- Module command for easy 3rd party plugin management
- Create an init command to create a repo for you to start out
- Setup the project to allow installing with `cargo-binstall`