### Basic Module Script Setup

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/making-modules.mdx

This is the minimal setup for a new module script. It ensures the correct shell is used and that any errors in the module will cause the build to fail.

```bash
#!/usr/bin/env bash
set -euo pipefail
```

--------------------------------

### Start Development Server

Source: https://github.com/blue-build/website/blob/main/README.md

Start the development server to preview changes locally. The `GH_TOKEN` environment variable can be used to bypass GitHub rate limits.

```sh
pnpm dev
```

```sh
npm run dev
```

--------------------------------

### Install Flatpaks from Flathub (User Scope)

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/default-flatpaks-v2.mdx

This configuration installs specified Flatpaks from the Flathub repository for the current user. Users will be notified on each boot about the Flatpak setup.

```yaml
type: default-flatpaks
configurations:
  - install:
      - org.mozilla.firefox
      - com.github.tchx84.Flatseal
      - io.github.flattool.Warehouse
      - io.missioncenter.MissionCenter
      - com.github.rafostar.Clapper
      - org.gnome.Loupe
```

--------------------------------

### Example Recipe File Structure

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

Illustrates the recommended directory structure for recipe files after migration, moving from a './config/recipes/' structure to a top-level './recipes/' directory.

```yaml
config
└─recipes
  ├── image_configs
  │   ├── common.yml
  │   ├── gnome.yml
  │   └── kde.yml
  ├── recipe-gnome-nvidia.yml
  ├── recipe-gnome.yml
  ├── recipe-kde-nvidia.yml
  └── recipe-kde.yml
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/blue-build/website/blob/main/README.md

Install project dependencies using pnpm. This is the recommended package manager for faster speeds.

```sh
pnpm install
```

--------------------------------

### Original Blue Build Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

This is the initial configuration of the Blue Build recipe before any changes are made. It includes several modules and package installations.

```yaml
name: jp-laptop
description: The image of Wunker OS for JP's Laptop.
base_image: ghcr.io/ublue-os/bazzite
image_version: "39"
modules:
    # ...
    - type: script
      scripts:
          - setup-selinux-dockersock.sh
    - type: script
      scripts:
          - setup-kubectl.sh
    - type: rpm-ostree
      repos:
          - https://pkg.earthly.dev/earthly.repo
          - https://cli.github.com/packages/rpm/gh-cli.repo
      install:
          - earthly
          - neovim
          - helix
          - alacritty
          - gh
    - type: script
      scripts:
          - install-mkcert.sh
          - install-codelldb.sh
```

--------------------------------

### Start SSH Agent and Add Key

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Provides bash commands to start the ssh-agent and add an SSH key to it, necessary for using SSH secrets in builds.

```bash
# Start the ssh-agent and load env variables
eval "$(ssh-agent)"

# Add your ssh key to the current agent
ssh-add
```

--------------------------------

### Quickstart New BlueBuild Project

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/v090-features-changes.mdx

Use the `bluebuild new` command to create a new BlueBuild project. This command prompts for image name, registry, organization, description, and build platform, then sets up a new git repository with initial files.

```bash
❯ bluebuild new ./weird-os
✔ What would you like to name your image? · weird-os
✔ What is the registry for the image? (e.g. ghcr.io or registry.gitlab.com) · ghcr.io
✔ What is the name of your org/username? · octocat
✔ Write a short description of your image: · this is my weird custom OS :3
✔ Are you building on Github or Gitlab? · Github
Private key written to cosign.key
Public key written to cosign.pub
[main (root-commit) 994d18c] chore: Initial Commit
 11 files changed, 355 insertions(+)
 create mode 100644 .github/dependabot.yml
 create mode 100644 .github/workflows/build.yml
 create mode 100644 .gitignore
 create mode 100644 LICENSE
 create mode 100644 README.md
 create mode 100644 cosign.pub
 create mode 100644 files/scripts/example.sh
 create mode 100644 files/system/etc/.gitkeep
 create mode 100644 files/system/usr/.gitkeep
 create mode 100644 modules/.gitkeep
 create mode 100644 recipes/recipe.yml
INFO  => Created new BlueBuild project in ./weird-os
```

--------------------------------

### Example Recipe File Structure (Moved)

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

Shows the updated directory structure where the 'recipes' directory is moved to the root of the repository, simplifying path references.

```yaml
config
recipes
├── image_configs
│   ├── common.yml
│   ├── gnome.yml
│   └── kde.yml
├── recipe-gnome-nvidia.yml
├── recipe-gnome.yml
├── recipe-kde-nvidia.yml
└── recipe-kde.yml
```

--------------------------------

### Install Flatpaks with Custom Repository Details

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/default-flatpaks-v2.mdx

This configuration installs Flatpaks from a custom repository, specifying its URL, name, and title. Notifications are disabled, and the scope is set to system.

```yaml
type: default-flatpaks
configurations:
  - notify: false
    scope: system
    repo:
      url: https://flathub.org/beta-repo/flathub-beta.flatpakrepo
      name: flathub-beta
      title: Flathub Beta
    install:
      - org.mozilla.firefox
      - com.github.tchx84.Flatseal
      - io.github.flattool.Warehouse
      - io.missioncenter.MissionCenter
      - com.github.rafostar.Clapper
      - org.gnome.Loupe
```

--------------------------------

### Updated Blue Build Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

This is the modified Blue Build recipe after removing the 'neovim' package. Observe the 'install' list for the 'rpm-ostree' module.

```yaml
name: jp-laptop
description: The image of Wunker OS for JP's Laptop.
base_image: ghcr.io/ublue-os/bazzite
image_version: "39"
modules:
    # ...
    - type: script
      scripts:
          - setup-selinux-dockersock.sh
    - type: script
      scripts:
          - setup-kubectl.sh
    - type: rpm-ostree
      repos:
          - https://pkg.earthly.dev/earthly.repo
          - https://cli.github.com/packages/rpm/gh-cli.repo
      install:
          - earthly
          - helix
          - alacritty
          - gh
    - type: script
      scripts:
          - install-mkcert.sh
          - install-codelldb.sh
```

--------------------------------

### Example of Blue Build Layer Caching

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

This output shows a Blue Build process where most layers are cached, and only the final two layers are rebuilt. This highlights the efficiency of caching in reducing build times.

```bash
=> [stage-4 16/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind,from=s  0.7s
```

--------------------------------

### DNF Module Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/dnf-module.mdx

This configuration uses the 'dnf' module to install packages and repositories. It specifies a custom repository file for Steam and installs Steam along with kernel modules, disabling weak dependency installation.

```yaml
type: dnf
repos:
  files:
    - https://negativo17.org/repos/fedora-steam.repo
install:
  packages:
    - install-weak-deps: false
      packages:
        - steam
        - kernel-modules-extra
```

--------------------------------

### Install Flatpaks from Flathub (System Scope) with Notifications Disabled

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/default-flatpaks-v2.mdx

This configuration installs specified Flatpaks system-wide and disables boot-time notifications for the Flatpak setup. This is useful for pre-installing applications for all users.

```yaml
type: default-flatpaks
configurations:
  - notify: false
    scope: system
    install:
      - org.mozilla.firefox
      - com.github.tchx84.Flatseal
      - io.github.flattool.Warehouse
      - io.missioncenter.MissionCenter
      - com.github.rafostar.Clapper
      - org.gnome.Loupe
```

--------------------------------

### Configure Multiple Modules in a Separate File

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-files.mdx

Define configurations for multiple modules within a single YAML file by listing them under the `modules` key. This example also shows how to include another configuration file.

```yaml
---
# yaml-language-server: $schema=https://schema.blue-build.org/module-list-v1.json

# recipes/common-modules.yml
modules:
    - type: signing
    - type: files
      files:
          - usr: /usr
    - type: fonts
      fonts:
          nerd-fonts:
              - Hack
    - from-file: common-packages.yml

```

--------------------------------

### Use Custom Modules in recipes.yml

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/module-repository.mdx

Specify the source of custom modules in your recipe.yml file. This example shows how to reference modules from a custom OCI repository.

```yaml
# recipe.yml
modules:
    - type: <name-of-your-module>
      # supports using tags like `:latest` too
      source: ghcr.io/octocat/bluebuild-modules
      list:
          - gec
          - gec
          - gec
```

--------------------------------

### Define and Use Stages in Blue Build

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/stages.mdx

This example shows how to define a stage named 'helix' to build the Helix editor from source using Rust, and then copy the compiled binaries and runtime files into the main image. It utilizes `script` modules for compilation and `copy` modules to transfer artifacts between stages.

```yaml
name: custom-image
base-image: ghcr.io/ublue-os/silverblue-main
image-version: 40
description: Stages example
stages:
  - name: helix
    from: docker.io/library/rust
    modules:
      - type: script
        snippets:
          - apt-get update && apt-get install -y git # Install git
          - git clone https://github.com/helix-editor/helix.git # Clone the helix repo
          - cd helix && RUSTFLAGS="-C target-feature=-crt-static" cargo install --path helix-term # Use cargo to install
          - mkdir -p /out/ && mv $CARGO_HOME/bin/hx /out/hx && mv runtime /out/ # Move bin and runtime
modules:
  # Copy the bin and runtime from the `helix` stage
  - type: copy
    from: helix
    src: /out/hx
    dest: /usr/bin/
  - type: copy
    from: helix
    src: /out/runtime
    dest: /usr/lib64/helix/
```

--------------------------------

### Rebase to Signed Universal Blue Image

Source: https://github.com/blue-build/website/blob/main/src/content/docs/learn/universal-blue.mdx

After rebasing to an unsigned image, use this command to rebase to a signed Universal Blue image to complete the installation. A reboot is necessary to apply the changes.

```bash
# example image details:
IMAGE_PATH=ghcr.io/octocat/weird-os
IMAGE_TAG=latest
# rebase command:
rpm-ostree rebase ostree-image-signed:docker://$IMAGE_PATH:$IMAGE_TAG
# reboot to complete the rebase:
systemctl reboot
```

--------------------------------

### Rebase to Unsigned Universal Blue Image

Source: https://github.com/blue-build/website/blob/main/src/content/docs/learn/universal-blue.mdx

Use this command to rebase to an unsigned Universal Blue image, which helps in installing proper signing keys and policies. A reboot is required to finalize the rebase.

```bash
# example image details:
IMAGE_PATH=ghcr.io/octocat/weird-os
IMAGE_TAG=latest
# rebase command:
rpm-ostree rebase ostree-unverified-registry:$IMAGE_PATH:$IMAGE_TAG
# reboot to complete the rebase:
systemctl reboot
```

--------------------------------

### Blue Build Cache Hit Example

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

This output shows that most build stages were cached, indicated by 'CACHED'. This occurs when the inputs to a build stage have not changed since the last build.

```bash
=> CACHED [stage-config 1/1] COPY ./config /config                                                                                                       0.0s
=> CACHED [stage-modules 1/2] COPY --from=ghcr.io/blue-build/modules:latest /modules /modules                                                            0.0s
=> CACHED [stage-modules 2/2] COPY ./modules /modules                                                                                                    0.0s
=> CACHED [stage-keys 1/1] COPY cosign.pub /keys/jp-desktop-gaming.pub                                                                                   0.0s
=> CACHED [stage-4  2/16] RUN --mount=type=bind,from=stage-keys,src=/keys,dst=/tmp/keys   mkdir -p /usr/etc/pki/containers/   && cp /tmp/keys/* /usr/et  0.0s
=> CACHED [stage-bins 1/3] COPY --from=ghcr.io/sigstore/cosign/cosign /ko-app/cosign /bins/cosign                                                         0.0s
=> CACHED [stage-bins 3/3] COPY --from=ghcr.io/blue-build/cli:main-installer /out/bluebuild /bins/bluebuild                                              0.0s
=> CACHED [stage-4  3/16] RUN --mount=type=bind,from=stage-bins,src=/bins,dst=/tmp/bins   mkdir -p /usr/bin/   && cp /tmp/bins/* /usr/bin/   && ostree   0.0s
=> CACHED [stage-4  4/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4  5/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4  6/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4  7/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4  8/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4  9/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4 10/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4 11/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4 12/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4 13/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> CACHED [stage-4 14/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind  0.0s
=> [stage-4 15/16] RUN   --mount=type=tmpfs,target=/var   --mount=type=bind,from=stage-config,src=/config,dst=/tmp/config,rw   --mount=type=bind,from=  33.4s
```

--------------------------------

### Mount SSH Socket Secret

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Shows how to mount the SSH socket into the build environment for accessing private repositories or servers. Requires starting ssh-agent and adding keys.

```yaml
modules:
  - type: script
    secrets:
      - type: ssh
    snippets:
      - git clone git@github.com:some/repo.git
```

--------------------------------

### Extract JSON Array using get_json_array

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Demonstrates the usage of the `get_json_array` bash function to extract array values from a module's configuration. The first example uses a direct path, while the second shows a safer, more explicit path.

```bash
get_json_array OUTPUT_VAR_NAME 'try .key.to.array[]' "${1}"
```

```bash
get_json_array OUTPUT_VAR_NAME 'try .["key"].["to"].["array"][]' "${1}"
```

--------------------------------

### Display Full Recipe with Snippets Included

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/local.mdx

When using `from-file:` syntax in your recipe, use the `--display-full-recipe` or `-d` flag to generate and display the complete `recipe.yml` with all snippets expanded.

```bash
bluebuild generate -d ./recipes/recipe.yml
```

--------------------------------

### Basic Custom Just Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/learn/universal-blue.mdx

Create a simple custom `just` recipe by defining a recipe name followed by the commands to execute. Each line is run separately by default.

```justfile
# 60-custom.just
recipename:
    echo "This is my recipe"
    echo "I can run commands here"
```

--------------------------------

### Switch System to Locally Built Image

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/local.mdx

The `switch` command builds your image, exports it as a `.tar.gz` file, and uses `rpm-ostree` to rebase or upgrade your current operating system with the locally built image.

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

--------------------------------

### Generate ISO from Local Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/generate-iso.mdx

Use this command to build a local image and generate an ISO from a specified recipe file. Provide the desired ISO name and the path to your recipe.

```bash
sudo bluebuild generate-iso --iso-name weird-os.iso recipe recipes/recipe.yml
```

--------------------------------

### Build Image Locally from Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/local.mdx

The `build` command tests your `recipe.yml` locally. This is the same command used by the BlueBuild GitHub Action, which can also use `--push` and `--registry` options.

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

--------------------------------

### Custom Just Recipe as a Bash Script

Source: https://github.com/blue-build/website/blob/main/src/content/docs/learn/universal-blue.mdx

To run a multi-line recipe as a script, include a shebang (e.g., `#!/usr/bin/env bash`) at the beginning of the recipe. This ensures the commands are executed by the specified interpreter.

```justfile
# 60-custom.just
scriptrecipe:
    #!/usr/bin/env bash
    set -euxo pipefail
    VAR="Hello, world!"
    echo $VAR # Hello, world!
```

--------------------------------

### Generate Containerfile from Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/local.mdx

Use the `generate` command to create a `Containerfile` from your `recipe.yml`. Output is printed to stdout by default, or can be redirected to a file using the `-o` flag.

```bash
bluebuild generate ./recipes/recipe.yml -o Containerfile
```

--------------------------------

### RPM-OSTree Upgrade with Caching

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

This command demonstrates an `rpm-ostree upgrade` process. It shows that existing layers are already present, and only a small amount of new data needs to be downloaded, indicating effective layer caching.

```bash
$> rpm-ostree upgrade
Pulling manifest: ostree-image-signed:docker://registry.gitlab.com/wunker-bunker/wunker-os/jp-laptop
Importing: ostree-image-signed:docker://registry.gitlab.com/wunker-bunker/wunker-os/jp-laptop (digest: sha256:01073d98adf4041f3b91840af1135b15aee97db90de6bc3a3846d67c07345e6a)
ostree chunk layers already present: 65
custom layers already present: 16
custom layers needed: 2 (255.0	MB)
```

--------------------------------

### Format Files

Source: https://github.com/blue-build/website/blob/main/README.md

Format all project files using Prettier. This command can also be run automatically in VSCode with recommended plugins.

```sh
pnpm run fmt
```

--------------------------------

### Generate ISO from Remote Image

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/generate-iso.mdx

Use this command to generate an ISO from a pre-built and published remote image. Specify the desired ISO name and the image's registry path.

```bash
sudo bluebuild generate-iso --iso-name weird-os.iso image ghcr.io/octocat/weird-os
```

--------------------------------

### Run BlueBuild Module with JSON Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/minimal-setup.mdx

Execute a BlueBuild module using the `run_module.sh` script with its configuration provided as a JSON string. This snippet demonstrates mounting necessary module and script sources and then invoking the module.

```dockerfile
# Run BlueBuild's gnome-extensions module
RUN \
  # add in the module source code
  --mount=type=bind,from=ghcr.io/blue-build/modules:latest,src=/modules,dst=/tmp/modules,rw \
  # add in the script that sets up the module run environment
  --mount=type=bind,from=ghcr.io/blue-build/cli/build-scripts:latest,src=/scripts/,dst=/tmp/scripts/ \
  # run the module
  /tmp/scripts/run_module.sh 'gnome-extensions' \
    '{"type":"gnome-extensions","install":["Vitals","GSConnect","Burn My Windows","PaperWM","Gnome 4x UI Improvements"]}'

```

--------------------------------

### Enable Image Rechunking Locally

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/v090-features-changes.mdx

To enable image rechunking for more efficient diffs and updates when building locally, use the `--rechunk` flag with the `bluebuild build` command.

```bash
bluebuild build --rechunk
```

--------------------------------

### Accessing Module Configuration with jq

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/making-modules.mdx

This script demonstrates how to read configuration variables and arrays passed as a JSON string to the module. It uses `jq` for safe parsing of JSON data.

```bash
#!/usr/bin/env bash
set -euo pipefail

# read a single variable from the configuration
# `try` makes the command output 'null' if the key is not found, otherwise it will error out and the build will fail
# the `.["var"]` syntax is optional and could be replaced with the less safe and more error-prone `.var` syntax
VAR=$(echo "$1" | jq -r 'try .["var"]')
echo "$VAR"

# read an array from the configuration
get_json_array ARRAY 'try .["array"][]' "$1"
# loop over the array
for THING in "${ARRAY[@]}"; do
    echo "$THING"
done
```

--------------------------------

### Import Module Configurations into Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-files.mdx

Reference external module configuration files within your main recipe file using the `from-file` directive. This allows for modular and organized recipe definitions.

```yaml
# recipe.yml
# ...rest of the recipe
modules:
    - from-file: common-modules.yml
    - from-file: common-flatpaks.yml

```

--------------------------------

### Run BlueBuild Module with YAML Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/minimal-setup.mdx

Use `yq` to process a YAML configuration string and pass it to the `run_module.sh` script for executing a BlueBuild module. This method is an alternative to using JSON configuration.

```dockerfile
# run the module
config=$'\
type: gnome-extensions \ninstall: \n    - Vitals # https://extensions.gnome.org/extension/1460/vitals/ \n    - GSConnect # https://extensions.gnome.org/extension/1319/gsconnect/ \n    - Burn My Windows # https://extensions.gnome.org/extension/4679/burn-my-windows/ \n    - PaperWM # https://extensions.gnome.org/extension/6099/paperwm/ \n    - Gnome 4x UI Improvements # https://extensions.gnome.org/extension/4158/gnome-40-ui-improvements/ \n' && \
/tmp/scripts/run_module.sh "$(echo "$config" | yq eval '.type')" "$(echo "$config" | yq eval -o=j -I=0)"

```

--------------------------------

### GNOME Image Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-images.mdx

Define a specific recipe for a GNOME-based image, including its name and base image.

```yaml
# recipe-gnome.yml
name: weird-gnome
description: This is the GNOME version of my personal OS image.
base-image: ghcr.io/ublue-os/silverblue-main
# ...

```

--------------------------------

### Configure Files Module to Copy System Files

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/config-files.mdx

Use this configuration when migrating 1-to-1 filetree mappings. It specifies the 'system' directory as the source and the root ('/') as the destination for files to be copied into the image.

```yaml
type: files
files:
    - source: system
      destination: /

```

--------------------------------

### KDE Image Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-images.mdx

Define a specific recipe for a KDE Plasma-based image, including its name and base image.

```yaml
# recipe-kde.yml
name: weird-kde
description: This is the LDE Plasma version of my personal OS image.
base-image: ghcr.io/ublue-os/kinoite-main
# ...

```

--------------------------------

### Build Workflow Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-images.mdx

Configure the build workflow to include multiple recipe files for building different image versions. Recipes can be located in subdirectories.

```yaml
# build.yml
# ...
jobs:
    bluebuild:
        strategy:
            matrix:
                recipe:
                    - recipe-gnome.yml
                    - recipe-kde.yml
                    # or like this if you want to have the recipes in their own directory:
                    # - common/gnome.yml
                    # - common/kde.yml
# ...

```

--------------------------------

### Trigger Immediate Reboot with Switch Command

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/local.mdx

To force an immediate system reboot after using the `switch` command, include the `--reboot` or `-r` argument.

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

--------------------------------

### Set Environment Variable in Module

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Demonstrates how to set an environment variable 'TEST' for a script module. The variable is then checked for existence.

```yaml
type: script
env:
  TEST: 'test'
snippets:
  - '[ -n "$TEST" ]'
```

--------------------------------

### Updating from-file Path

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/caching-update.mdx

Demonstrates how to update the `from-file:` directive in a recipe to reflect the new relative path after moving the 'recipes' directory to the root.

```yaml
from-file: image_configs/common.yml
```

--------------------------------

### Generate Skopeo Key Pair

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/cosign.mdx

This command generates a Sigstore key pair using skopeo, which can be used with cosign. Similar to cosign, ensure the private key is not password protected.

```bash
skopeo generate-sigstore-key --output-prefix cosign
```

--------------------------------

### Copy yq for YAML Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/minimal-setup.mdx

Copy the `yq` binary into your Containerfile to enable parsing YAML configuration for BlueBuild modules. This is an optional step if you prefer YAML over JSON for module configuration.

```dockerfile
# `yq` be used to pass BlueBuild modules configuration written in yaml
COPY --from=docker.io/mikefarah/yq /usr/bin/yq /usr/bin/yq

```

--------------------------------

### Containerfile Generation from Module Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Illustrates how a YAML module configuration is translated into a RUN statement in a Containerfile. The module's configuration is passed as a JSON string to a script.

```yaml
# recipes/module.yml
type: rpm-ostree
install:
    - micro
uninstall:
    - firefox
    - firefox-langpacks
```

```dockerfile
# the contents of this statement have been simplified slightly to better illustrate the topic on hand
RUN /tmp/modules/rpm-ostree/rpm-ostree.sh '{"type":"rpm-ostree","from-file":"module.yml","repos":null,"install":["micro"],"remove":["firefox","firefox-langpacks"]}'
```

--------------------------------

### Refactor yq to jq for Reading Configuration

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/v090-features-changes.mdx

Update module code to use `jq` and `get_json_array` instead of `yq` and `get_yaml_array` for reading configuration. This change is necessary due to the removal of `yq` from default BlueBuild images.

```diff
# read a single variable from the configuration
- VAR=$(echo "$1" | yq -I=0 '.var')
+ VAR=$(echo "$1" | jq -r 'try .["var"]')
echo "$VAR"

# read an array from the configuration
- get_yaml_array ARRAY '.array[]' "$1"
+ get_json_array ARRAY 'try .["array"][]' "$1"
```

--------------------------------

### Configure a Single Module in a Separate File

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/multiple-files.mdx

Use this format to define configuration for a single module in its own YAML file. Ensure the `type` matches the module you are configuring.

```yaml
---
# yaml-language-server: $schema=https://schema.blue-build.org/module-v1.json

# recipes/common-flatpaks.yml
type: default-flatpaks
system:
    install:
        - org.blender.Blender

```

--------------------------------

### Using a Custom Module in a Recipe

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/making-modules.mdx

This YAML snippet shows how to include a custom module in your Blue Build image configuration. The custom module is referenced by its type name.

```yaml
# recipe.yml
modules:
    - type: <name-of-your-module>
      option: true
```

--------------------------------

### Add Template Repository as a Git Remote

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/sync.mdx

Add the blue-build/template repository as a remote named 'template' to your local repository. This allows you to fetch and merge changes from the template.

```bash
git remote add template https://github.com/blue-build/template.git
```

--------------------------------

### Generate Cosign Key Pair

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/cosign.mdx

Use this command to generate a new public and private key pair for cosign signing. Ensure no password is set for the private key when prompted, as it will be used in automated workflows.

```bash
cosign generate-key-pair
```

--------------------------------

### Fetch All Git Commits

Source: https://github.com/blue-build/website/blob/main/src/content/docs/how-to/sync.mdx

Fetch the latest commits from all configured remote repositories, including your local repository and the newly added template remote. This prepares your local repository for merging.

```bash
git fetch --all
```

--------------------------------

### Mount Secret as File

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Mounts a secret as a file named /tmp/secret_file within the build. This method is suitable for secrets that need to be read from a file.

```yaml
modules:
  - type: script
    secrets:
      - type: env
        name: SECRET_ENV
        mount:
          type: file
          destination: /tmp/secret_file
    snippets:
      - cat /tmp/secret_file | login-script.sh
```

--------------------------------

### Specify Local Modules with `source: local`

Source: https://github.com/blue-build/website/blob/main/src/content/docs/blog/v090-features-changes.mdx

When using local modules located in the `./modules/` folder of your custom image repository, set the `source` property to `local`. This change ensures proper recipe validation and prevents errors with custom modules.

```yaml
modules:
    # use the module "./modules/custom-module/"
    - type: custom-module
      source: local
      input:
          - value 1
          - value 2
```

--------------------------------

### Mount Command Secret

Source: https://github.com/blue-build/website/blob/main/src/content/docs/reference/module.mdx

Demonstrates using the output of a host command as a secret within a script module. The command's stdout is mounted as an environment variable named 'SECRET_ENV'.

```yaml
modules:
  - type: script
    secrets:
      - type: exec
        command: secret-manager-command
        args:
          - '-q'
          - some/arg/for/secret-command
        mount:
          type: env
          name: SECRET_ENV
    snippets:
      - echo $SECRET_ENV | login-script.sh
```