### Anaconda ISO with Kickstart and User Configuration

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Create an Anaconda ISO with a kickstart file embedded for automated installation. This example also includes setting a root password.

```toml
[customizations.installer.kickstart]
contents = """
text
zerombr
clearpart --all
autopart
network --bootproto=dhcp --onboot=on
"""

[[customizations.user]]
name = "root"
password = "password"
```

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

### Initialize ManifestConfig

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/09-types.md

Example of how to initialize a ManifestConfig struct with various configuration options.

```go
manifestConfig := &ManifestConfig{
    Architecture:    cntArch,
    Config:          config,
    Imgref:          imgref,
    BuildImgref:     buildImgref,
    DistroDefPaths:  distroDefPaths,
    SourceInfo:      sourceinfo,
    BuildSourceInfo: buildSourceinfo,
    RootFSType:      rootfsType,
    UseLibrepo:      useLibrepo,
}
```

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

### TOML Configuration Schema Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

This TOML snippet illustrates the structure for customizing users, kernel, filesystems, and installer options within the bootc-image-builder configuration.

```toml
[customizations]
# Users
[[customizations.user]]
name = "alice"
password = "bob"
key = "ssh-rsa AAA... user@email.com"
groups = ["wheel"]

# Kernel
[customizations.kernel]
append = "mitigations=auto,nosmt"

# Filesystems
[[customizations.filesystem]]
mountpoint = "/"
minsize = "10 GiB"

[[customizations.filesystem]]
mountpoint = "/var/data"
minsize = "20 GiB"

# Installer (anaconda-iso only)
[customizations.installer.kickstart]
contents = "..."

[customizations.installer.modules]
enable = ["org.fedoraproject.Anaconda.Modules.Localization"]
disable = ["org.fedoraproject.Anaconda.Modules.Users"]

# ISO customizations
[customizations.iso]
volume_id = "TheISOLabel"
application_id = "MyApp"
publisher = "MyPublisher"

```

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

### Legacy (RPM/Anaconda) Build Path - DNF Solver Setup

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/12-architecture-guide.md

Sets up the DNF solver, including initialization for RHEL/plugins, creating a new container solver, and collecting repository configurations.

```Go
InitDNF() for RHEL/plugins
NewContainerSolver()
Collect repos config
```

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

### AWS AMI Upload Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/04-cloud-integration.md

Demonstrates how to create an AWS uploader and use the upload function to upload a disk image as an AMI. Ensure AWS credentials and necessary flags are configured.

```go
// Upload AMI to AWS
uploader, err := awscloud.NewUploader("us-east-1", "bucket", "image-name", opts)
if err != nil {
    return err
}

flags := cmd.Flags()
if err := upload(uploader, "/output/image/disk.raw", flags); err != nil {
    return fmt.Errorf("cannot upload AMI: %w", err)
}
```

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

### Distro Definition Version Resolution Examples

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/07-distro-definitions.md

Illustrates how distro definition files are matched against requests, including exact matches, fuzzy matches (downgrades), and scenarios with no matching file.

```text
Request:   fedora-40
Files:     fedora-40.yaml, fedora-39.yaml, fedora-38.yaml
Result:    fedora-40.yaml
```

```text
Request:   fedora-41
Files:     fedora-40.yaml, fedora-39.yaml, fedora-38.yaml
Result:    fedora-40.yaml (highest ≤ 41)
```

```text
Request:   fedora-99
Files:     fedora-40.yaml, fedora-39.yaml
Result:    Error: "could not find def file for distro fedora-99"
```

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

### ImageDef YAML Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/07-distro-definitions.md

Provides examples of how to define required packages for different image types within a distribution's definition file.

```yaml
anaconda-iso:
  packages:
    - anaconda
    - anaconda-install-env-deps
    - anaconda-dracut
    - dracut-config-generic
    - dracut-network
    - squashfs-tools
iso:
  packages:
    - anaconda
    - anaconda-install-env-deps
```

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

### Initialize and Use Progress Bar for Upload

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/04-cloud-integration.md

Illustrates the setup and usage of the cheggaaa/pb progress bar for tracking upload progress. It configures the bar to display bytes and wraps the file reader with a proxy.

```go
pbar := pb.New(0)
pbar.SetTotal(fileSize)
pbar.Set(pb.Bytes, true)      // Show bytes unit
pbar.SetWriter(osStdout)       // Write to stdout
reader := pbar.NewProxyReader(file)
pbar.Start()
defer pbar.Finish()
```

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

### Run Integration Tests (Concise)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/HACKING.md

Execute integration tests with concise output. Ensure test dependencies are installed prior to running.

```bash
pytest
```

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

### Legacy (RPM/Anaconda) Build Path - manifestForISO

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/12-architecture-guide.md

Generates the manifest for an ISO image, including loading distro definitions, creating an Anaconda container installer, applying blueprint customizations, and getting the distro and runner.

```Go
manifestForISO()
  distrodef.LoadImageDef() // Load distro-specific packages
  image.NewAnacondaContainerInstallerLegacy()
  Apply blueprint customizations
  getDistroAndRunner()
```

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

### Default Command Handling Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/01-main-cli.md

Demonstrates how the CLI automatically injects the 'build' subcommand when no other subcommand is explicitly provided. This simplifies common usage patterns.

```bash
bootc-image-builder quay.io/centos-bootc/centos-bootc:stream9
# becomes: bootc-image-builder build quay.io/centos-bootc/centos-bootc:stream9
```

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

### Get Bootc Image Builder Help

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/README.md

Use the --help flag to access command-line help for the bootc-image-builder and its subcommands. This is useful for understanding available options and usage.

```bash
bootc-image-builder --help
```

```bash
bootc-image-builder build --help
```

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

### Create Anaconda Container Installer Image Object

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/06-legacy-iso.md

Initializes a new Anaconda container installer image object. Sets container removal of signatures and rootfs compression to 'zstd'.

```go
img := image.NewAnacondaContainerInstallerLegacy(platform, filename, containerSource)
img.ContainerRemoveSignatures = true
img.RootfsCompression = "zstd"
```

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

### Add New Image Type Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/12-architecture-guide.md

Example of adding a new image type, 'qcow2-luks', to the supported image types map. This defines its export type and ISO/Legacy properties.

```go
"qcow2-luks": {Export: "qcow2", ISO: false, Legacy: false}
```

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

### ImageTypes Construction and Validation Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/09-types.md

Demonstrates the creation and validation of ImageTypes. Shows a valid disk type combination and an invalid mixed type combination that results in an error.

```go
types, err := imagetypes.New("qcow2", "ami")  // Valid: both disk
types.Exports()  // ["qcow2", "image"]

types, err := imagetypes.New("iso", "qcow2")  // Error: mixed types
```

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

### Install tmt Packages on Fedora

Source: https://github.com/osbuild/bootc-image-builder/blob/main/test/README.md

Installs the necessary packages for using tmt on Fedora.

```shell
sudo dnf install tmt tmt+provision-virtual
```

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

### Example Distro Definition YAML Structure

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/06-legacy-iso.md

Illustrates the typical structure of a distro-specific image definition YAML file, outlining package configurations for anaconda-iso, iso, and bootc-installer.

```yaml
anaconda-iso:
  packages:
    - anaconda
    - anaconda-install-env-deps
    - dracut-live
    # ... additional packages
iso:
  packages:
    # ... same as anaconda-iso for legacy images
bootc-installer:
  packages: []  # bootc-installer uses minimal config
```

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

### ImageDef YAML Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/09-types.md

Example YAML configuration for an ImageDef, specifying packages for an anaconda-iso image type.

```yaml
anaconda-iso:
  packages:
    - anaconda
    - anaconda-install-env-deps
    - dracut-live
```

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

### Access Virtual Machine via SSH

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Connect to a virtual machine launched with a virt-install example using SSH. Ensure you have the correct private SSH key and the IP address of the machine.

```shell
ssh -i /path/to/private/ssh-key alice@ip-address
```

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

### Get Bootc Image Builder Version

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Use the `--version` flag to display the version of the bootc-image-builder.

```bash
--version               version for bootc-image-builder
```

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

### Run Integration Tests (Verbose)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/HACKING.md

Execute integration tests with verbose output. This requires test dependencies to be installed and may take a significant amount of time.

```bash
pytest -s -vv
```

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

### Run QCOW2 Image on macOS (aarch64) using qemu

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Launches a virtual machine from a QCOW2 disk image on macOS aarch64 using qemu with HVF acceleration. Assumes qemu is installed via homebrew.

```bash
qemu-system-aarch64 \
    -M accel=hvf \
    -cpu host \
    -smp 2 \
    -m 4096 \
    -bios /opt/homebrew/Cellar/qemu/8.1.3_2/share/qemu/edk2-aarch64-code.fd \
    -serial stdio \
    -machine virt \
    -snapshot output/qcow2/disk.qcow2
```

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

### LoadImageDef Function Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/07-distro-definitions.md

Demonstrates how to load package definitions for a specific image type, distribution, and version using the LoadImageDef function. This is useful for dynamically including necessary packages in an image manifest.

```go
// Load anaconda-iso packages for Fedora 40
def, err := distrodef.LoadImageDef(
    []string{"/usr/share/bootc-image-builder/defs"},
    "fedora",
    "40",
    "anaconda-iso",
)
if err != nil {
    return nil, err
}

// Use packages
for _, pkg := range def.Packages {
    // Include in image manifest
}
```

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

### Start and Configure Podman Machine for Rootful Mode on macOS

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Ensures the Podman machine is running in rootful mode, which is required for bootc-image-builder on macOS.

```bash
$ podman machine stop   # if already running
Waiting for VM to exit...
Machine "podman-machine-default" stopped successfully
$ podman machine set --rootful
$ podman machine start
```

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

### Provide Kickstart Configuration

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Embed custom kickstart file contents for the Anaconda installer. Ensure essential partitioning and network commands are included, and avoid conflicts with bootc-image-builder's automatic additions.

```toml
[customizations.installer.kickstart]
contents = """
text --non-interactive
zerombr
clearpart --all --initlabel --disklabel=gpt
autopart --noswap --type=lvm
network --bootproto=dhcp --device=link --activate --onboot=on
"""
```

```json
{
  "customizations": {
    "installer": {
      "kickstart": {
        "contents": "text --non-interactive\nzerombr\nclearpart..."
      }
    }
  }
}
```

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

### AWS AMI Upload Example

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/08-upload-utility.md

Uploads a raw disk image to AWS and registers it as an AMI. Requires specifying the AWS region, an S3 bucket for intermediate storage, and a name for the AMI. Optionally, a target architecture can be specified.

```bash
# Upload raw image to AWS
upload aws /output/image/disk.raw \
  --region us-east-1 \
  --bucket my-images \
  --ami-name my-bootc-image
```

```bash
# Cross-architecture upload
upload aws /output/image/disk.raw \
  --region us-east-1 \
  --bucket my-images \
  --ami-name my-bootc-aarch64 \
  --target-arch aarch64
```

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

### Get Bootc Image Builder Version

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/README.md

Run the version command to display the current version of the bootc-image-builder. This is helpful for troubleshooting and ensuring you are using the expected version.

```bash
bootc-image-builder version
```

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

### Legacy (RPM/Anaconda) Build Path - NewContainer

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/12-architecture-guide.md

Initializes a new container for the legacy build path, involving pulling the image, starting a container, and mounting its filesystem.

```Go
podman_container.NewContainer()
```

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

### Specify Image Types for Bootc Image Builder

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Use the `--type` flag to specify which image formats to build. This flag can be passed multiple times to generate different image types. For example, to build both qcow2 and ami images, use `--type qcow2 --type ami`.

```bash
--type stringArray      image types to build [ami, anaconda-iso, bootc-installer, gce, iso, qcow2, raw, vhd, vmdk] (default [qcow2])
```

```bash
--type                  [Image type](#-image-types) to build (can be passed multiple times)                                       
```

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

### bootc-image-builder Build Command Help

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Display help information specific to the build command.

```bash
bootc-image-builder build --help
```

```bash
bootc-image-builder build -h
```

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

### bootc-image-builder Manifest Command Help

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Display help information specific to the manifest command.

```bash
bootc-image-builder manifest --help
```

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

### Configure Anaconda Installer Modules in TOML

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Customize Anaconda installer behavior by enabling or disabling specific dbus modules using this TOML configuration.

```toml
[customizations.installer.modules]
enable = [
  "org.fedoraproject.Anaconda.Modules.Localization"
]
disable = [
  "org.fedoraproject.Anaconda.Modules.Users"
]
```

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

### Manage Anaconda Installer Modules

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Enable or disable specific Anaconda installer modules. The disable list takes priority if a module is present in both lists.

```toml
[customizations.installer.modules]
enable = [
  "org.fedoraproject.Anaconda.Modules.Localization",
  "org.fedoraproject.Anaconda.Modules.Network"
]
disable = [
  "org.fedoraproject.Anaconda.Modules.Users"
]
```

```json
{
  "customizations": {
    "installer": {
      "modules": {
        "enable": ["org.fedoraproject.Anaconda.Modules.Localization"],
        "disable": ["org.fedoraproject.Anaconda.Modules.Users"]
      }
    }
  }
}
```

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

### Run QCOW2 Image on Linux using virt-install

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Launches a virtual machine from a QCOW2 disk image using virt-install, specifying CPU, memory, and disk details.

```bash
sudo virt-install \
    --name fedora-bootc \
    --cpu host \
    --vcpus 4 \
    --memory 4096 \
    --import --disk ./output/qcow2/disk.qcow2,format=qcow2 \
    --os-variant fedora-eln
```

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

### Configure Anaconda Installer Modules in JSON

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

The JSON representation for enabling and disabling Anaconda installer modules. Note that values are not validated, and 'disable' takes priority over 'enable'.

```json
{
  "customizations": {
    "installer": {
      "modules": {
        "enable": [
          "org.fedoraproject.Anaconda.Modules.Localization"
        ],
        "disable": [
          "org.fedoraproject.Anaconda.Modules.Users"
        ]
      }
    }
  }
}
```

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

### Build bootc-image-builder

Source: https://github.com/osbuild/bootc-image-builder/blob/main/HACKING.md

Build the bootc-image-builder binary. Ensure you are in the 'bib' directory before running.

```bash
cd bib
go build ./cmd/bootc-image-builder/
```

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

### Running bootc-image-builder with AWS Credentials File

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Demonstrates how to run bootc-image-builder using Podman, mounting the AWS credentials file into the container for AMI creation.

```bash
$ sudo podman run \
  --rm \
  -it \
  --privileged \
  --pull=newer \
  --security-opt label=type:unconfined_t \
  -v $HOME/.aws:/root/.aws:ro \
  -v /var/lib/containers/storage:/var/lib/containers/storage \
  --env AWS_PROFILE=default \
  quay.io/centos-bootc/bootc-image-builder:latest \
  --type ami \
  --aws-ami-name centos-bootc-ami \
  --aws-bucket fedora-bootc-bucket \
  --aws-region us-east-1 \
  quay.io/centos-bootc/centos-bootc:stream9
```

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

### Run QCOW2 Image on Linux using qemu-system-x86_64

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Launches a virtual machine from a QCOW2 disk image using qemu-system-x86_64 with KVM acceleration.

```bash
qemu-system-x86_64 \
    -M accel=kvm \
    -cpu host \
    -smp 2 \
    -m 4096 \
    -bios /usr/share/OVMF/OVMF_CODE.fd \
    -serial stdio \
    -snapshot output/qcow2/disk.qcow2
```

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

### Containerfile for Bootc Installer

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

This Containerfile is used to build a container image that includes Anaconda for the bootc-installer. Ensure all listed packages are installed and follow the specific instructions for EFI and symlink creation based on your Fedora version.

```Dockerfile
FROM your-favorite-bootc-container:latest
RUN dnf install -y \
     anaconda \
     anaconda-install-env-deps \
     anaconda-dracut \
     dracut-config-generic \
     dracut-network \
     net-tools \
     squashfs-tools \
     grub2-efi-x64-cdboot \
     python3-mako \
     lorax-templates-* \
     biosdevname \
     prefixdevname \
     && dnf clean all

# On Fedora 42 this is necessary to get files in the right places
# RUN dnf reinstall -y shim-x64

# On Fedora 43 and up this is necessary to get files in the right
# places
RUN mkdir -p /boot/efi && cp -ra /usr/lib/efi/*/*/EFI /boot/efi

# lorax wants to create a symlink in /mnt which points to /var/mnt
# on bootc but /var/mnt does not exist on some images.
#
# If https://gitlab.com/fedora/bootc/base-images/-/merge_requests/294
# gets merged this will be no longer needed
RUN mkdir /var/mnt

```

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

### General bootc-image-builder Help

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Display general help information for the bootc-image-builder command.

```bash
bootc-image-builder --help
```

```bash
bootc-image-builder -h
```

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

### Instantiate Manifest for ISO Image

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/06-legacy-iso.md

Instantiates the image into the manifest. This step requires a found runner and a random number generator.

```go
_, err = img.InstantiateManifest(&mf, nil, foundRunner, rng)
```

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

### Run Unit Tests

Source: https://github.com/osbuild/bootc-image-builder/blob/main/HACKING.md

Execute all unit tests for the bootc-image-builder project. Navigate to the 'bib' directory first.

```bash
cd bib
go test ./...
```

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

### Basic QCOW2 Image Build

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Builds a QCOW2 disk image from a specified container image. The output will be saved in a default directory structure.

```bash
bootc-image-builder quay.io/centos-bootc/centos-bootc:stream9
# Output: ./qcow2/disk.qcow2
```

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

### Running bootc-image-builder with AWS Credentials via Environment File

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Shows how to use Podman to run bootc-image-builder, providing AWS credentials securely via an environment file for AMI creation.

```bash
$ cat aws.secrets
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

$ sudo podman run \
  --rm \
  -it \
  --privileged \
  --pull=newer \
  --security-opt label=type:unconfined_t \
  -v /var/lib/containers/storage:/var/lib/containers/storage \
  --env-file=aws.secrets \
  quay.io/centos-bootc/bootc-image-builder:latest \
  --type ami \
  --aws-ami-name centos-bootc-ami \
  --aws-bucket centos-bootc-bucket \
  --aws-region us-east-1 \
  quay.io/centos-bootc/centos-bootc:stream9
```

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

### Build Fedora Bootable Container Image Rootless (QCOW2)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Performs an experimental rootless build using KVM. Mounts user's container storage and uses the --in-vm argument. Requires a config.toml file.

```bash
# Ensure the image is fetched
podman pull quay.io/fedora/fedora-bootc:latest
mkdir output
podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label:type:unconfined_t \
    -v ./config.toml:/config.toml:ro \
    -v ./output:/output \
    -v ~/.local/share/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --in-vm \
    --type qcow2 \
    --use-librepo=True \
    --rootfs ext4 \
    quay.io/fedora/fedora-bootc:latest
```

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

### Get Required osbuild Exports

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/02-image-types.md

Returns a deduplicated list of osbuild manifest exports needed for the specified image types. Assumes the ImageTypes object is valid.

```go
types, _ := imagetypes.New("qcow2", "raw", "ami")
exports := types.Exports()
// ["qcow2", "image"]
// because: qcow2→qcow2, raw→image, ami→image (deduplicated)
```

```go
types, _ := imagetypes.New("qcow2", "vmdk", "vhd")
exports := types.Exports()
// ["qcow2", "vmdk", "vpc"]
```

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

### Get Available Image Type Names

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/02-image-types.md

Retrieves a sorted, comma-separated list of all supported image type names. Useful for displaying options to users or for validation.

```go
names := imagetypes.Available()
// "ami, anaconda-iso, bootc-installer, gce, iso, ova, pxe-tar-xz, qcow2, raw, vhd, vmdk"
```

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

### Build CentOS Bootable Container Image (QCOW2)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Builds a CentOS bootable container into a QCOW2 image. Requires a config.toml file for user configuration and mounts local directories for configuration and output.

```bash
# Ensure the image is fetched
sudo podman pull quay.io/centos-bootc/centos-bootc:stream9
mkdir output
sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label:type:unconfined_t \
    -v ./config.toml:/config.toml:ro \
    -v ./output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    --use-librepo=True \
    quay.io/centos-bootc/centos-bootc:stream9
```

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

### Prepare and Pass mTLS Configuration in cmdBuild

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/05-mtls-configuration.md

Shows how mTLS configuration is prepared and passed as environment variables to the osbuild process. Includes deferred cleanup for resources.

```go
if mTLS != nil {
    envVars, cleanup, err := prepareOsbuildMTLSConfig(mTLS)
    if err != nil {
        return fmt.Errorf("failed to prepare osbuild TLS keys: %w", err)
    }
    defer cleanup()
    osbuildEnv = append(osbuildEnv, envVars...)
}

// Later, passed to osbuild
osbuildOpts := progress.OSBuildOptions{
    ExtraEnv: osbuildEnv,  // Includes mTLS env vars
}
```

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

### Live Debugging with osbuild

Source: https://github.com/osbuild/bootc-image-builder/blob/main/devel/Troubleshooting.md

Use `--entrypoint bash` with bootc-image-builder for persistent state during live debugging. This allows direct invocation of osbuild with specific options like `--break` to halt at particular stages.

```shell
osbuild --cache-max-size unlimited --export qcow2 --store /store --output-directory /output /tmp/manifest.json
```

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

### Load Distro Definition for Anaconda ISO

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/06-legacy-iso.md

Loads the distribution definition required for an Anaconda ISO installer. Ensure the correct paths and OS release information are provided.

```go
imageDef, err := distrodef.LoadImageDef(c.DistroDefPaths, 
      c.SourceInfo.OSRelease.ID, 
      c.SourceInfo.OSRelease.VersionID, 
      "anaconda-iso")
```

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

### Build qcow2 and raw images with custom configuration

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/01-main-cli.md

Use this command to build multiple image types (qcow2, raw) from a container image, specifying a custom configuration file and output directory. Ensure the container image reference is provided as the last argument.

```bash
bootc-image-builder build \
  --type qcow2 \
  --type raw \
  --config ./config.toml \
  --output ./output \
  quay.io/centos-bootc/centos-bootc:stream9
```

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

### Configure Filesystems

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Define custom filesystems with mount points and minimum sizes. Constraints apply, especially for btrfs, limiting configurable mount points.

```toml
[[customizations.filesystem]]
mountpoint = "/"
minsize = "10 GiB"

[[customizations.filesystem]]
mountpoint = "/boot"
minsize = "1 GiB"

[[customizations.filesystem]]
mountpoint = "/var/data"
minsize = "20 GiB"
```

```json
{
  "customizations": {
    "filesystem": [
      {"mountpoint": "/", "minsize": "10 GiB"},
      {"mountpoint": "/boot", "minsize": "1 GiB"},
      {"mountpoint": "/var/data", "minsize": "20 GiB"}
    ]
  }
}
```

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

### Selecting Build Path Based on Legacy ISO

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/02-image-types.md

Determines whether to use a legacy ISO build path or a standard disk build path based on the image type's legacy flag.

```go
if imageTypes.Legacy() {
    // Use manifestFromCobraForLegacyISO()
} else {
    // Use manifestFromCobraForDisk()
}
```

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

### Run Bootc Image Builder Container

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

This is the primary command to run the bootc-image-builder. Ensure you mount the output and container storage directories. The `<imgref>` placeholder should be replaced with the image reference you want to build.

```bash
sudo podman run \
  --rm \
  -it \
  --privileged \
  --pull=newer \
  --security-opt label=type:unconfined_t \
  -v ./output:/output \
  -v /var/lib/containers/storage:/var/lib/containers/storage \
  quay.io/centos-bootc/bootc-image-builder:latest \
  <imgref>
```

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

### Handle Errors When Loading Distro Definitions

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/07-distro-definitions.md

Load a distro definition and handle potential errors, such as missing definition files, permission issues, or invalid YAML format. The error handling block provides specific examples of possible error messages.

```go
def, err := distrodef.LoadImageDef(paths, "fedora", "40", "anaconda-iso")
if err != nil {
    // Possible errors:
    // - "could not find def file for distro fedora-40"
    // - "could not read def file..." (file permissions)
    // - "could not unmarshal def file..." (invalid YAML)
    // - "could not find def for distro fedora and image type anaconda-iso..."
    return nil, err
}
```

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

### Build Container Locally

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Use this command to build the bootc-image-builder container image on your local machine. It's recommended to run this as root to avoid later permission issues.

```shell
sudo podman build --tag bootc-image-builder .
```

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

### Run Bootc Image Builder with Configuration (Bash)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

This bash command runs the bootc-image-builder container, mounting a local TOML configuration file and output directory. It specifies the image type and the base OS image.

```bash
sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v ./config.toml:/config.toml:ro \
    -v ./output:/output \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    quay.io/centos-bootc/centos-bootc:stream9
```

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

### Build and Upload AMI to AWS

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Builds an AMI image and uploads it to AWS. Requires AWS region, bucket, and AMI name to be specified, along with AWS credentials configured in the environment.

```bash
bootc-image-builder \
  --type ami \
  --aws-region us-east-1 \
  --aws-bucket my-images \
  --aws-ami-name bootc-image \
  quay.io/centos-bootc/centos-bootc:stream9
```

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

### Build Multiple Image Types to Custom Output Directory

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Builds multiple image types (QCOW2 and AMI) and saves them to a specified output directory. This allows for flexible image generation for different platforms.

```bash
bootc-image-builder \
  --type qcow2 \
  --type ami \
  --output ./output \
  quay.io/centos-bootc/centos-bootc:stream9
# Output: ./output/qcow2/disk.qcow2 and ./output/image/disk.raw
```

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

### AMI Build with Custom TOML Configuration

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Build an AMI image using a custom TOML configuration file. Specify the configuration file using the --config option.

```bash
podman run \
  --type ami \
  --aws-region us-east-1 \
  --aws-bucket my-images \
  --aws-ami-name bootc-custom \
  --config config.toml \
  quay.io/centos-bootc/centos-bootc:stream9
```

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

### Configure Kickstart Contents in JSON

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

The JSON equivalent for embedding custom kickstart file content. Multi-line strings are represented with newline characters.

```json
{
  "customizations": {
    "installer": {
      "kickstart": {
        "contents": "text --non-interactive\nzerombr\nclearpart --all --initlabel --disklabel=gpt\nautopart --noswap --type=lvm\nnetwork --bootproto=dhcp --device=link --activate --onboot=on"
      }
    }
  }
}
```

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

### Parse CLI Args and Generate Manifest (Go)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/01-main-cli.md

Parses command-line arguments to generate an osbuild manifest. It handles different image types and includes validation for container storage and target architecture. Legacy flags are also supported.

```go
func manifestFromCobra(cmd *cobra.Command, args []string, pbar progress.ProgressBar) ([]byte, *mTLSConfig, error)
```

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

### Build Execution - Artifact Output Formats

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/12-architecture-guide.md

Describes the output directory structure for different image types after OSBuild execution.

```Go
For each image type:
  qcow2/ directory with qcow2 file
  image/ directory with raw file (ami, raw)
  vmdk/ directory with vmdk file
  vpc/ directory with vhd file
```

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

### Add User to Image Configuration (JSON)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

This JSON configuration demonstrates how to add a user with a name, password, SSH key, and group memberships. This format is used when passing configuration via stdin.

```json
{
  "customizations": {
    "user": [
      {
        "name": "alice",
        "password": "bob",
        "key": "ssh-rsa AAA ... user@email.com",
        "groups": [
          "wheel",
          "admins"
        ]
      }
    ]
  }
}
```

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

### Configure Kernel Arguments (JSON)

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Use this JSON configuration to specify kernel arguments to be appended during the build process. This is useful for passing specific boot parameters.

```json
{
  "customizations": {
    "kernel": {
      "append": "mitigations=auto,nosmt"
    }
  }
}
```

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

### Build bootc-image-builder Container

Source: https://github.com/osbuild/bootc-image-builder/blob/main/devel/README.md

Use this command to build the bootc-image-builder container with local development versions of its components. Ensure build contexts for 'osbuild' and 'images' point to your local source directories.

```bash
$ podman build --file=devel/Containerfile --build-context=osbuild=$HOME/src/osbuild --build-context=images=$HOME/src/images -t bootc-image-builder:devel .
```

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

### Integration with Main Build Process for AMI Upload

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/04-cloud-integration.md

Shows how the upload function is called within the main build process when an 'ami' image type is specified. It ensures the correct disk path is used and handles potential upload errors.

```go
// From main.go cmdBuild()
if uploader != nil {
    pbar.Stop()  // Stop main progress bar
    for idx, imgType := range imgTypes {
        switch imgType {
        case "ami":
            diskpath := filepath.Join(outputDir, exports[idx], "disk.raw")
            if err := upload(uploader, diskpath, cmd.Flags()); err != nil {
                return fmt.Errorf("cannot upload AMI: %w", err)
            }
        }
    }
}
```

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

### Build and upload an AMI to AWS

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/01-main-cli.md

This command builds an image of type 'ami' and uploads it to AWS. Specify the AWS region, S3 bucket name, and the desired AMI name. The container image reference is required.

```bash
bootc-image-builder build \
  --type ami \
  --aws-region us-east-1 \
  --aws-bucket mybucket \
  --aws-ami-name my-image \
  quay.io/fedora/fedora-bootc:latest
```

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

### Rootless Image Build within a VM

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Builds an image in rootless mode by running the builder inside a virtual machine using Podman. This requires mounting the container storage and using the `--in-vm` flag.

```bash
podman run \
  --privileged \
  -v ~/.local/share/containers/storage:/var/lib/containers/storage \
  quay.io/centos-bootc/bootc-image-builder:latest \
  --in-vm \
  --type qcow2 \
  quay.io/fedora/fedora-bootc:latest
```

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

### Use Librepo for RPM Downloads in Bootc Image Builder

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Set the `--use-librepo` flag to true to utilize librepo for downloading RPM packages, which can provide faster and more robust downloads.

```bash
--use-librepo     Download rpms using librepo (faster and more robust)                                                      
```

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

### prepareOsbuildMTLSConfig Function

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/05-mtls-configuration.md

Prepares mTLS certificates for osbuild by writing them to temporary files and returning environment variables that point to these files. It also provides a cleanup function to remove the temporary files.

```APIDOC
## prepareOsbuildMTLSConfig

### Description
Writes mTLS certificates to temporary files and returns environment variables for osbuild to use them.

### Signature
func prepareOsbuildMTLSConfig(mTLS *mTLSConfig) (envVars []string, cleanup func(), err error)

### Parameters
#### Path Parameters
- mTLS (*mTLSConfig) - Required - Certificate bundle from extractTLSKeys

### Returns
- envVars ([]string) - List of environment variable assignments: `KEY=value`
- cleanup (func()) - Cleanup function that removes temporary directory
- err (error) - File operation error

### Process
1. Creates temporary directory via `os.MkdirTemp()`
2. Writes three certificate files with appropriate permissions:
   - `client.key` - 0600 (private, readable by process only)
   - `client.crt` - 0600 (private, readable by process only)
   - `ca.crt` - 0644 (public, readable by all)
3. Returns environment variables pointing to these files
4. Returns cleanup function that recursively removes temp directory

### Environment Variables Returned
```
OSBUILD_SOURCES_CURL_SSL_CLIENT_KEY=/tmp/osbuild-mtls-XXXXX/client.key
OSBUILD_SOURCES_CURL_SSL_CLIENT_CERT=/tmp/osbuild-mtls-XXXXX/client.crt
OSBUILD_SOURCES_CURL_SSL_CA_CERT=/tmp/osbuild-mtls-XXXXX/ca.crt
```

### Error Handling
- MkdirTemp errors propagated
- WriteFile errors propagated
- Cleanup function removes temp dir on cleanup or error

### Defer Pattern
```go
// From main.go cmdBuild()
if mTLS != nil {
    envVars, cleanup, err := prepareOsbuildMTLSConfig(mTLS)
    if err != nil {
        return fmt.Errorf("failed to prepare osbuild TLS keys: %w", err)
    }
    defer cleanup()  // Removes temp directory when done
    osbuildEnv = append(osbuildEnv, envVars...)
}
```

### File Permissions
- `client.key` and `client.crt`: 0600 (rw-------)
  - Only owner can read/write
  - Prevents leaking private key via world-readable files
- `ca.crt`: 0644 (rw-r--r--)
  - World-readable since it's public certificate chain
```

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

### Upload Image to AWS

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/11-command-reference.md

Upload a pre-built disk image to AWS S3 and create an AMI. Ensure AWS credentials and bucket exist, and the target architecture is specified if needed.

```bash
upload aws /output/image/disk.raw \
  --region us-east-1 \
  --bucket my-images \
  --ami-name my-bootc-image
```

```bash
upload aws /output/image/disk.raw \
  --region us-east-1 \
  --bucket my-images \
  --ami-name my-bootc-aarch64 \
  --target-arch aarch64
```

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

### Configure Filesystem Partitions with TOML

Source: https://github.com/osbuild/bootc-image-builder/blob/main/README.md

Use this TOML structure to define custom filesystem partitions, specifying mountpoints and minimum sizes for the root and additional partitions.

```toml
[[customizations.filesystem]]
mountpoint = "/"
minsize = "10 GiB"

[[customizations.filesystem]]
mountpoint = "/var/data"
minsize = "20 GiB"
```

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

### Load Distro Definition and Access Packages

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/07-distro-definitions.md

Load a distro definition for a specific distribution, version, and image type. Access the package list from the loaded definition for further processing, such as dependency resolution.

```go
// 1. Load definition for target distro/version/type
def, err := distrodef.LoadImageDef(paths, "centos", "9", "anaconda-iso")
if err != nil {
    return err
}

// 2. Use packages in manifest
for _, pkg := range def.Packages {
    // Add to package set for depsolve
}
```

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

### Custom Filesystem Partitioning

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/10-configuration.md

Define custom filesystem partitions by specifying the mountpoint and minimum size for each. This allows for precise control over disk layout.

```toml
[[customizations.filesystem]]
mountpoint = "/"
minsize = "20 GiB"

[[customizations.filesystem]]
mountpoint = "/var/data"
minsize = "50 GiB"
```

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

### Define Distro Definition Paths

Source: https://github.com/osbuild/bootc-image-builder/blob/main/_autodocs/06-legacy-iso.md

Specifies the ordered list of directories where distro-specific image definition YAML files are searched for. Includes paths for development and production environments.

```go
var distroDefPaths = []string{
    "./data/defs",                          // Development
    "./bib/data/defs",                      // Development (alternative)
    "/usr/share/bootc-image-builder/defs",  // Production container
}
```