Skip to content

Commit

Permalink
docs: add distrobox installation tips (#146)
Browse files Browse the repository at this point in the history
I had initially added distrobox installation instructions to the website
(see [here](blue-build/website#45), but it has
been suggested that the CLI readme is a more natural place for them.

I have tested the distrobox installation method and procedures on my
home machine and aside from an odd bug (see
#145) everything is working.
  • Loading branch information
michaelhaaf authored Mar 29, 2024
1 parent fcc012b commit 47abb2b
Showing 1 changed file with 35 additions and 8 deletions.
43 changes: 35 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,16 +20,43 @@ The `bluebuild` tool takes advantage of newer build features. Specifically bind,

### 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
distrobox create blue-build --image ghcr.io/blue-build/cli
distrobox enter blue-build
```

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

### Cargo

This is the best way to install as it gives you the opportunity to bulid for your specific environment.
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
Expand Down Expand Up @@ -63,7 +90,7 @@ If you are using a dedicated flake to manage your dependencies, you can add Blue
{pkgs,inputs,...}: {
...
environment.SystemPackages = [
inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name
inputs.bluebuild.packages.${pkgs.system}.bluebuild # change bluebuild with the fh added input name
];
...
}
Expand All @@ -84,7 +111,7 @@ in {
}
```

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

Expand Down Expand Up @@ -112,7 +139,7 @@ If you don't care about the details of the template, you can run the `build` com
bluebuild build ./config/recipe.yaml
```

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

#### Local Builds

Expand Down Expand Up @@ -146,7 +173,7 @@ You can use our [GitHub Action](https://github.com/blue-build/github-action) by
name: bluebuild
on:
schedule:
- cron: "00 17 * * *" # build at 17:00 UTC every day
- 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
Expand All @@ -165,7 +192,7 @@ jobs:
fail-fast: false # stop GH from cancelling all matrix builds if one fails
matrix:
recipe:
# !! Add your recipes here
# !! Add your recipes here
- recipe.yml
steps:
# the build is fully handled by the reusable github action
Expand Down Expand Up @@ -198,7 +225,7 @@ stages:
build-image:
stage: build
image:
image:
name: ghcr.io/blue-build/cli:main
entrypoint: [""]
services:
Expand Down Expand Up @@ -227,7 +254,7 @@ build-image:
## Future Features

- Stages for parallel building (useful for compiling programs for your image)
- Automatic download and management of image keys for seemless signed image rebasing
- 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`

0 comments on commit 47abb2b

Please sign in to comment.