Image Builder

https://osbuild.org/docs/
Admin
Image Builder is a tool for building operating system artifacts, offering hosted, local package, and...
Tokens:1,003,062
Snippets:3,031
Trust Score:8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Custom installer kickstart - on premises example (TOML)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Provides a custom kickstart via `customizations.installer.kickstart.contents`. This cannot be combined with other installer customizations.

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

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

### iso.yaml example

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/advanced/bootc/sources-of-configuration

Example iso.yaml configuration for the `bootc-generic-iso` image type, setting the installer label and grub2 boot entry for Fedora installation.

```yaml
label: "Fedora-bootc-Installer"  
grub2:  
  entries:  
    - name: "Install Fedora (bootc)"  
      linux: "/images/pxeboot/vmlinuz inst.stage2=hd:LABEL=Fedora-bootc-Installer console=tty0 inst.text selinux=0"  
      initrd: "/images/pxeboot/initrd.img"  
```

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

### Installer customization - hosted example (JSON)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Hosted equivalent for installer customizations. Uses JSON format instead of TOML.

```json
{ "customizations": { "installer": { "unattended": true, "sudo-nopasswd": ["user", "%wheel"] } } }
```

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

### Compile, install, and run osbuild-composer

Source: https://osbuild.org/docs/developer-guide/projects/osbuild-composer/CONTRIBUTING

Compile the project from the working directory, install it, and start the service.

```bash
$ rm -rf rpmbuild/  
$ make rpm  
$ sudo dnf -y install rpmbuild/RPMS/x86_64/*  
$ sudo systemctl start osbuild-composer.socket  

```

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

### Hosted groups example (JSON)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Hosted API example for installing a package group using the @ prefix in the packages list.

```json
{  
  "customizations": {  
    "packages": ["@anaconda-tools"],  
  }  
}  

```

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

### Blueprint with distro and packages (hosted)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Two hosted service examples that select a distribution via the distribution field and install packages via customizations.packages. The first uses fedora-44, the second uses rhel-10.2. These correspond to the on-premises blueprint examples.

```json
{  
  "image_name": "tmux",  
  "image_description": "tmux image with openssh",  
  "distribution": "fedora-44",  
  "customizations": {  
    "packages": ["tmux", "openssh-server"]  
  }  
}  

```

```json
{  
  "image_name": "tmux",  
  "image_description": "tmux image with openssh",  
  "distribution": "rhel-10.2",  
  "customizations": {  
    "packages": ["tmux", "openssh-server"]  
  }  
}  

```

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

### Start Docker containers

Source: https://osbuild.org/docs/developer-guide/projects/osbuild-composer/HACKING

Start the containers with docker-compose up.

```bash
docker-compose up  
```

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

### Install scap-security-guide and inspect profiles

Source: https://osbuild.org/docs/user-guide/oscap-remediation

Commands to install the scap-security-guide package and list available profiles using oscap info. Run on the build host or a system with scap-security-guide installed.

```bash
dnf install scap-security-guide  
oscap info /usr/share/xml/scap/ssg/content/<security_profile>.xml  

```

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

### Start the service

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-crc/HACKING

Run this command to start the image-builder service. The API will be available at http://localhost:8086/api/image-builder/v1/.

```bash
./image-builder

```

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

### Hosted enabled_modules example (JSON)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Hosted API example for enabling a modularity stream and listing a package from it.

```json
{  
  "customizations": {  
    "enabled_modules": [  
      { "name": "nodejs", "stream": "18" }  
    ],  
    "packages": ["nodejs"]  
  }  
}  

```

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

### Start compose with composer-cli

Source: https://osbuild.org/docs/on-premises/commandline

Starts a compose for the base-image-with-tmux blueprint with qcow2 image type, returning a UUID.

```bash
$ composer-cli compose start base-image-with-tmux qcow2  
Compose ab71b61a-b3c4-434f-b214-1e16527766ff added to the queue  

```

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

### Install dependencies for building binaries

Source: https://osbuild.org/docs/developer-guide/projects/images/docs/developer

Install the `krb5-devel` package required to build most binaries defined in `cmd` and run tests.

```bash
dnf -y install krb5-devel
```

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

### Start PostgreSQL container

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-crc/HACKING

Run this command to start a PostgreSQL container with the specified configuration. Wait a few seconds for it to become healthy.

```bash
podman run --replace --name image-builder-db \
  -p 5434:5432 \
  -e POSTGRES_USER=user \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=imagebuilder \
  --health-cmd "pg_isready -U user -d imagebuilder" \
  --health-interval 10s --health-timeout 5s --health-retries 5 \
  -d postgres

```

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

### Start ephemeral VM with deploy-qemu

Source: https://osbuild.org/docs/developer-guide/projects/osbuild-composer/HACKING

Start a VM using the built RPMs. IMAGE must be a cloud-init-enabled image matching the host OS. The second argument is a directory for cloud-init user-data.

```bash
tools/deploy-qemu IMAGE tools/deploy/test  
```

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

### Run QEMU VM with Fedora netinstall ISO

Source: https://osbuild.org/docs/on-premises/commandline/building-ostree-images

Boots a VM with KVM acceleration, 3000MB RAM, snapshot mode, host CPU, virtio networking with port forwarding from host 2223 to guest SSH, and mounts the Fedora netinstall ISO.

```bash
$ qemu-system-x86_64 \  
          -enable-kvm \  
          -m 3000 \  
          -snapshot \  
          -cpu host \  
          -net nic,model=virtio \  
          -net user,hostfwd=tcp::2223-:22 \  
          -cdrom $HOME/Downloads/Fedora-Server-netinst-x86_64-33-1.2.iso \  
          disk-image.img  

```

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

### Manifest with devices and mounts (example-5.json) and build command

Source: https://osbuild.org/docs/developer-guide/projects/osbuild/manifest

Full manifest example that creates a files pipeline with mkdir and copy stages, then a disk pipeline that truncates a 1G raw image, formats it as ext4, and copies the files tree into a mounted filesystem. Save as example-5.json and build with the provided osbuild command, exporting the disk pipeline.

```json
{
  "version": "2",
  "pipelines": [
    {
      "name": "files",
      "stages": [
        {
          "type": "org.osbuild.mkdir",
          "options": {
            "paths": [
              {
                "path": "/resources"
              }
            ]
          }
        },
        {
          "type": "org.osbuild.copy",
          "options": {
            "paths": [
              {
                "from": "input://inlinefile/sha256:659c11543b435c1503e4636cd9ad810f5cb99a3cafaf7be12a34e2d026ec33b7",
                "to": "tree:///resources/inline-file"
              },
              {
                "from": "input://curlfile/sha256:29ddbe330656a28c0cd1f77332464b74146b32765bc9194112fdc0ffdade8727",
                "to": "tree:///resources/curl-file"
              }
            ]
          },
          "inputs": {
            "inlinefile": {
              "type": "org.osbuild.files",
              "origin": "org.osbuild.source",
              "references": [
                "sha256:659c11543b435c1503e4636cd9ad810f5cb99a3cafaf7be12a34e2d026ec33b7"
              ]
            },
            "curlfile": {
              "type": "org.osbuild.files",
              "origin": "org.osbuild.source",
              "references": [
                "sha256:29ddbe330656a28c0cd1f77332464b74146b32765bc9194112fdc0ffdade8727"
              ]
            }
          }
        }
      ]
    },
    {
      "name": "disk",
      "stages": [
        {
          "type": "org.osbuild.truncate",
          "options": {
            "filename": "/disk.raw",
            "size": "1G"
          }
        },
        {
          "type": "org.osbuild.mkfs.ext4",
          "options": {
            "uuid": "90f06397-4919-4dc0-aab3-f42d01d2de4f"
          },
          "devices": {
            "device": {
              "type": "org.osbuild.loopback",
              "options": {
                "filename": "/disk.raw"
              }
            }
          }
        },
        {
          "type": "org.osbuild.copy",
          "inputs": {
            "files-tree": {
              "type": "org.osbuild.tree",
              "origin": "org.osbuild.pipeline",
              "references": [
                "name:files"
              ]
            }
          },
          "options": {
            "paths": [
              {
                "from": "input://files-tree/",
                "to": "mount://mnt/"
              }
            ]
          },
          "devices": {
            "image": {
              "type": "org.osbuild.loopback",
              "options": {
                "filename": "disk.raw"
              }
            }
          },
          "mounts": [
            {
              "name": "mnt",
              "type": "org.osbuild.ext4",
              "source": "image",
              "target": "/"
            }
          ]
        }
      ]
    }
  ],
  "sources": {
    "org.osbuild.inline": {
      "items": {
        "sha256:659c11543b435c1503e4636cd9ad810f5cb99a3cafaf7be12a34e2d026ec33b7": {
          "encoding": "base64",
          "data": "SSBhbSBhbiBpbmxpbmUgZmlsZQo="
        }
      }
    },
    "org.osbuild.curl": {
      "items": {
        "sha256:29ddbe330656a28c0cd1f77332464b74146b32765bc9194112fdc0ffdade8727": {
          "url": "http://localhost:8080/curl-source-file.txt"
        }
      }
    }
  }
}
```

```bash
$ sudo osbuild --export disk --output-directory output/5 example-5.json
```

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

### Chain depsolve request JSON

Source: https://osbuild.org/docs/user-guide/depsolving

Example of a chain depsolve request with two transactions. The first installs @core and selinux-policy-targeted, excluding firewalld; the second installs osbuild with weak dependencies disabled. The depsolver resolves each transaction sequentially, marking the first result as installed before resolving the second.

```json
{
  "command": "depsolve",
  "api_version": 2,
  "arch": "x86_64",
  "module_platform_id": "platform:f43",
  "releasever": "43",
  "cachedir": "rpmmd",
  "arguments": {
    "repos": [
      {
        "id": "fedora",
        "metalink": "https://mirrors.fedoraproject.org/metalink?repo=fedora-43&arch=x86_64"
      },
      {
        "id": "updates",
        "metalink": "https://mirrors.fedoraproject.org/metalink?repo=updates-released-f43&arch=x86_64"
      }
    ],
    "transactions": [
      {
        "package-specs": [
          "@core",
          "selinux-policy-targeted"
        ],
        "exclude-specs": [
          "firewalld"
        ]
      },
      {
        "package-specs": [
          "osbuild"
        ],
        "install_weak_deps": false
      }
    ]
  }
}
```

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

### Enable COPR repository and install image-builder

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/installation

Enable the COPR repository to get a more recent version of image-builder from the main branch, then install and build. The build command produces a Fedora 43 Minimal Raw disk image.

```bash
$ sudo dnf copr enable @osbuild/image-builder  
# ...  
$ sudo dnf install image-builder  
# ...  
$ sudo image-builder build --distro fedora-43 minimal-raw-xz  
# ...  

```

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

### Run osbuild to build example-2.json and export the res pipeline

Source: https://osbuild.org/docs/developer-guide/projects/osbuild/manifest

Builds the second example manifest and exports the res pipeline to output/2 using the --export and --output-directory options. The command requires sudo and assumes example-2.json is in the working directory.

```bash
$ sudo osbuild --export res --output-directory output/2 example-2.json  

```

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

### Example blueprint in TOML format

Source: https://osbuild.org/docs/on-premises/overview/basic-concepts

Defines a blueprint in TOML format that specifies the image name, description, version, and a package to install. The example includes the tmux package with version wildcard. Use this as a template for creating custom blueprints.

```toml
name = "base-image-with-tmux"  
description = "A base system with tmux"  
version = "0.0.1"  
  
[[packages]]  
name = "tmux"  
version = "*"  

```

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

### Compose response JSON

Source: https://osbuild.org/docs/developer-guide/projects/osbuild-composer/localcloud

Example JSON response from the compose endpoint after starting a build. Contains the compose ID and href.

```json
{"href":"/api/image-builder-composer/v2/compose","kind":"ComposeId","id":"f3ac9290-23c0-47b4-bb9e-cadee85d1340"}  

```

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

### Build ISO with podman and image-builder

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/advanced/bootc/isos

Builds the Containerfile into an ISO using podman and then invokes image-builder to create a bootc-generic-iso with the specified bootc reference and default filesystem ext4. Requires the Containerfile from the previous example.

```bash
sudo podman build -t localhost/iso -f Containerfile  
sudo image-builder build --bootc-ref localhost/iso --bootc-default-fs ext4 bootc-generic-iso  

```

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

### boot-aws setup, teardown, and run commands

Source: https://osbuild.org/docs/developer-guide/projects/images/docs/developer/cmds

Commands for booting an AWS image using the boot-aws utility. The setup subcommand uploads the image to S3, registers it as an AMI, creates a security group allowing SSH, launches an instance, waits until ready, prints its public IP, and configures cloud-init with the provided SSH key and username. The teardown subcommand removes all resources created by setup using the resource file. The run subcommand performs setup, uploads and runs the script specified by PATH_TO_SCRIPT, then performs teardown.

```shell
go run ./cmd/boot-aws setup \
     --access-key-id "${AWS_ACCESS_KEY_ID}" \
     --secret-access-key "${AWS_SECRET_ACCESS_KEY}" \
     --region "${AWS_REGION}" \
     --bucket "${AWS_BUCKET}" \
     --ami-name "${IMAGE_NAME}" \
     --s3-key "${IMAGE_KEY}" \
     --username "${USERNAME}" \
     --arch "${IMAGE_ARCHITECTURE}" \
     --ssh-pubkey "${PATH_TO_SSH_PUBLIC_KEY}" \
     --ssh-privkey "${PATH_TO_SSH_PRIVATE_KEY}" \
     --resourcefile ./aws-test-resources.json \
     ${PATH_TO_IMAGE_FILE}
```

```shell
go run ./cmd/boot-aws teardown \
     --access-key-id "${AWS_ACCESS_KEY_ID}" \
     --secret-access-key "${AWS_SECRET_ACCESS_KEY}" \
     --region "${AWS_REGION}" \
     --bucket "${AWS_BUCKET}" \
     --name "${IMAGE_NAME}" \
     --key "${IMAGE_KEY}" \
     --username "${USERNAME}" \
     --arch "${IMAGE_ARCHITECTURE}" \
     --ssh-pubkey "${PATH_TO_SSH_PUBLIC_KEY}" \
     --ssh-privkey "${PATH_TO_SSH_PRIVATE_KEY}" \
     --resourcefile ./aws-test-resources.json
```

```shell
go run ./cmd/boot-aws run \
     --access-key-id "${AWS_ACCESS_KEY_ID}" \
     --secret-access-key "${AWS_SECRET_ACCESS_KEY}" \
     --region "${AWS_REGION}" \
     --bucket "${AWS_BUCKET}" \
     --ami-name "${IMAGE_NAME}" \
     --s3-key "${IMAGE_KEY}" \
     --username "${USERNAME}" \
     --arch "${IMAGE_ARCHITECTURE}" \
     --ssh-pubkey "${PATH_TO_SSH_PUBLIC_KEY}" \
     --ssh-privkey "${PATH_TO_SSH_PRIVATE_KEY}" \
     ${PATH_TO_IMAGE_FILE} ${PATH_TO_SCRIPT}
```

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

### org.osbuild.systemd.unit.create stage configuration

Source: https://osbuild.org/docs/developer-guide/projects/osbuild/modules/stages/org.osbuild.systemd.unit.create

Example configuration for the org.osbuild.systemd.unit.create stage, showing a swap.service unit with Unit, Swap, and Install sections. The Swap section includes What, Priority, Options, and TimeoutSec properties. The Install section defines WantedBy and RequiredBy arrays.

```json
{
  "name": "org.osbuild.systemd.unit.create",
  "options": {
    "filename": "swap.service",
    "config": {
      "Unit": {
        "Description": "Swap unit"
      },
      "Swap": {
        "What": "/dev/sda2",
        "Priority": 10,
        "Options": {
          "descriptions": "May contain an option string for the swap device",
          "type": "string"
        },
        "TimeoutSec": {
          "descriptions": "Configures the time to wait for the swapon command to finish",
          "type": "string"
        }
      },
      "Install": {
        "additionalProperties": false,
        "type": "object",
        "description": "'Install' configuration section of a unit file.",
        "properties": {
          "WantedBy": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "RequiredBy": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}
```

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

### Configure Kickstart Contents in TOML

Source: https://osbuild.org/docs/bootc

Use the [customizations.installer.kickstart] block to provide kickstart commands. Note that bootc-image-builder automatically handles the container image installation.

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

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

### Disk Partition Configuration Examples

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/advanced/bootc/sources-of-configuration

Two YAML examples for configuring disk partitions in image-builder for bootc images. The first shows a default GPT layout with BIOS boot, ESP, and root partitions. The second demonstrates using the grow_root_to_fill_disk policy to leave unallocated space.

```yaml
mount_configuration: "units"  
partition_table:  
  type: "gpt"  
  partitions:  
    - size: "1 MiB"  
      type: "21686148-6449-6e6F-744e-656564454649"  
      bootable: true  
    - size: "200 MiB"  
      type: "filesystem"  
      payload:  
        type: "vfat"  
        mountpoint: "/boot/efi"  
        label: "ESP"  
        fstab_options: "defaults,uid=0,gid=0,umask=077,shortname=winnt"  
        fstab_freq: 0  
        fstab_passno: 2  
    - size: "2 GiB"  
      type: "filesystem"  
      payload:  
        type: "ext4"  
        label: "root"  
        mountpoint: "/"  
        fstab_options: "defaults"  
        fstab_freq: 0  
        fstab_passno: 0  

```

```yaml
mount_configuration: "units"  
partition_table:  
  type: "gpt"  
  size: "10 GiB"  
  policy:  
    grow_root_to_fill_disk: false  
  partitions:  
    - size: "1 MiB"  
      type: "21686148-6449-6e6F-744e-656564454649"  
      bootable: true  
    - size: "200 MiB"  
      type: "filesystem"  
      payload:  
        type: "vfat"  
        label: "ESP"  
        mountpoint: "/boot/efi"  
        fstab_options: "defaults,uid=0,gid=0,umask=077,shortname=winnt"  
        fstab_freq: 0  
        fstab_passno: 2  
    - size: "4 GiB"  
      type: "filesystem"  
      payload:  
        type: "ext4"  
        label: "root"  
        mountpoint: "/"  
        fstab_options: "defaults"  
        fstab_freq: 0  
        fstab_passno: 0  

```

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

### Build Fedora bootc installer Containerfile

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/advanced/bootc/isos

Builds a Fedora bootc payload installer (boot.iso) by installing Anaconda and required packages, configuring the ISO label and GRUB entries, setting Anaconda's interactive defaults, and applying minimal systemd and user configuration. Includes the necessary build tools and the bare-minimum steps normally performed by lorax. A bootc system installed through Anaconda will fail to start systemd-remount-fs.service.

```dockerfile
FROM quay.io/fedora/fedora-bootc:rawhide  
  
RUN dnf install -qy \  
    anaconda \  
    anaconda-install-img-deps \  
    anaconda-dracut \  
    dracut-config-generic \  
    dracut-network \  
    net-tools \  
    grub2-efi-x64-cdboot \  
    plymouth \  
    default-fonts-core-sans \  
    default-fonts-other-sans \  
    google-noto-sans-cjk-fonts  
  
# these are necessary build tools. if you use a separate build container then  
# these tools should be installed there  
RUN dnf install -qy \  
    xorrisofs \  
    squashfs-tools  
  
RUN dnf clean all  
  
RUN mkdir -p /boot/efi && cp -ra /usr/lib/efi/*/*/EFI /boot/efi  
  
# ---  
  
# some configuration for our ISO  
  
RUN mkdir -p /usr/lib/image-builder/bootc  
  
COPY <<EOT /usr/lib/image-builder/bootc/iso.yaml  
label: "Fedora-bootc-Installer"  
grub2:  
  entries:  
    - name: "Install Fedora (bootc)"  
      linux: "/images/pxeboot/vmlinuz inst.stage2=hd:LABEL=Fedora-bootc-Installer console=tty0 inst.graphical selinux=0 rhgb quiet"  
      initrd: "/images/pxeboot/initrd.img"  
EOT  
  
# some configuration for anaconda  
  
COPY <<EOT /usr/share/anaconda/interactive-defaults.ks  
bootc --source-imgref registry:quay.io/fedora/fedora-bootc:rawhide --target-imgref quay.io/fedora/fedora-bootc:rawhide  
EOT  
  
# ---  
  
# these things are normally performed by `lorax` to make `anaconda` work; this is the  
# bare minimum to get things to work  
  
RUN echo "install:x:0:0:root:/root:/usr/libexec/anaconda/run-anaconda" >> /etc/passwd && \  
    echo "install::14438:0:99999:7:::" >> /etc/shadow && \  
    passwd -d root  
  
RUN mv /usr/share/anaconda/list-harddrives-stub /usr/bin/list-harddrives && \  
    mv /etc/yum.repos.d /etc/anaconda.repos.d && \  
    ln -s /lib/systemd/system/anaconda.target /etc/systemd/system/default.target && \  
    rm -v /usr/lib/systemd/system-generators/systemd-gpt-auto-generator  
  
RUN ln -s /usr/lib/systemd/system/anaconda-shell@.service /usr/lib/systemd/system/autovt@.service  
  
RUN mkdir /usr/lib/systemd/logind.conf.d  
COPY <<EOT /usr/lib/systemd/logind.conf.d/anaconda-shell.conf  
[Login]  
ReserveVT=2  
EOT  
  
RUN mkdir "$(realpath /root)" && \  
    kernel=$(kernel-install list --json pretty | jq -r '.[] | select(.has_kernel == true) | .version') && \  
    DRACUT_NO_XATTR=1 dracut --force -v --zstd --reproducible --no-hostonly \  
        --add "anaconda" \  
        "/usr/lib/modules/${kernel}/initramfs.img" "${kernel}"  
  
RUN mkdir /etc/systemd/user/pipewire.service.d/  
COPY <<EOT /etc/systemd/user/pipewire.service.d/allowroot.conf  
[Unit]  
ConditionUser=  
EOT  
  
RUN mkdir /etc/systemd/user/pipewire.socket.d/  
COPY <<EOT /etc/systemd/user/pipewire.socket.d/allowroot.conf  
[Unit]  
ConditionUser=  
EOT  

```

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

### Example build cache info.json

Source: https://osbuild.org/docs/developer-guide/projects/images/test

Example cache file for a fedora-40 x86_64 qcow2 image with all-customizations config. Shows a manifest-checksum, osbuild-version, commit, boot-success true, PR 42, runner-distro fedora-40, and embedded kickstart path.

```json
{  
  "distro": "fedora-40",  
  "arch": "x86_64",  
  "image-type": "qcow2",  
  "config": "all-customizations",  
  "manifest-checksum": "8c0ce3987d78fe6f3307494cd57ceed861de61c3b04786d6a7f570faacbdb5df",  
  "osbuild-version": "osbuild 89",  
  "osbuild-commit": "74392a0238dec6bfa3f030e46c840148df2814e0",  
  "commit": "52ecfdf1eb345e09c6a6edf4a8d3dd5c8079c51c",  
  "boot-success": true,  
  "pr": 42,  
  "runner-distro": "fedora-40",  
  "iso-embedded-ks": "embedded.ks"  
}  


```

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

### On-premises groups example (TOML)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Defines a package group to install using the [[groups]] table with a name attribute matching the group ID.

```toml
[[groups]]  
name = "anaconda-tools"  

```

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

### Boot image with qemu

Source: https://osbuild.org/docs/on-premises/commandline

Boots the resulting qcow2 image with qemu, enabling KVM, setting memory, snapshot mode, CPU host, and port forwarding.

```bash
$ qemu-system-x86_64 \
                -enable-kvm \
                -m 3000 \
                -snapshot \
                -cpu host \
                -net nic,model=virtio \
                -net user,hostfwd=tcp::2223-:22 \
                ab71b61a-b3c4-434f-b214-1e16527766ff-disk.qcow2   

```

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

### Configure Anaconda installer modules (on premises)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Configure Anaconda installer modules for on-premises builds. The values are not validated; any name listed under enable is added to the Anaconda configuration, so mistyped values may cause Anaconda to fail to start. The disable list is processed after enable and takes priority.

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

```

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

### Sample browser-diagnostics.log lines

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-frontend

Example lines from the browser diagnostics log, where each line shows the elapsed time since the test started, the level, and message. Uncaught exceptions, console errors/warnings, failed requests, and 400+ responses are captured. Warnings have a smaller budget than errors.

```text
+  1429ms  HTTP 404    GET .../apps/chrome/operator-generated/fed-modules.json  
+  2759ms  CONSOLE WARNING Unsatisfied version * from undefined of shared
                          singleton module react-router-dom (required =6.30.4)
+  3210ms  HTTP 400    GET .../api/rbac/v1/access/?application=inventory  

```

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

### Build the project

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-crc/HACKING

Run this command to build the project.

```bash
make build

```

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

### Embed PGP public key in gpgkeys entry

Source: https://osbuild.org/docs/on-premises/installation/managing-repositories

If the gpgkeys entry starts with -----BEGIN PGP PUBLIC KEY BLOCK-----, osbuild-composer imports it directly instead of fetching from a URL. The example shows a multi-line key embedded in the source configuration.

```toml
check_gpg = true  
check_ssl = true  
check_repogpg  
id = "custom-local"  
name = "signed local packages"  
type = "yum-baseurl"  
url = "https://local/repos/projectrepo/"  
gpgkeys=["https://remote/keys/other-repokey.pub",  
'''-----BEGIN PGP PUBLIC KEY BLOCK-----  
Version: GnuPG v1.4.10 (GNU/Linux)  
  
mQENBEt+xXMBCACkA1ZtcO4H7ZUG/0aL4RlZIozsorXzFrrTAsJEHvdy+rHCH3xR  
cFz6IMbfCOdV+oKxlDP7PS0vWKfqxwkenOUut5o9b32uDdFMW4IbFXEQ94AuSQpS  
jo8PlVMm/51pmmRxdJzyPnr0YD38mVK6qUEYLI/4zXSgFk493GT8Y4m3N18O/+ye  
PnOOItj7qbrCMASoBx1TG8Zdg8ufehMnfb85x4xxAebXkqJQpEVTjt4lj4p6BhrW  
R+pIW/nBUrz3OsV7WwPKjSLjJtTJFxYX+RFSCqOdfusuysoOxpIHOx1WxjGUOB5j  
fnhmq41nWXf8ozb58zSpjDrJ7jGQ9pdUpAtRABEBAAG0HkJyaWFuIEMuIExhbmUg  
PGJjbEByZWRoYXQuY29tPokBOAQTAQIAIgUCS37FcwIbAwYLCQgHAwIGFQgCCQoL  
BBYCAwECHgECF4AACgkQEX6MFo7+On9dgAf9Hi2K1MKcmLkDeSUIXkXIAw0nAzl2  
UDGLWEdDqAgFxP6UaCVtOIRCr7z4EDOQoxD7mkdekbH2W5GcTO4h8MQBHYD9EkY7  
H/lTKchlFfsmafOoA3Y/tDLPKu+OIfH9Mqn2Mf7wMYGrnWSRNKYgvC5zkMgkhoPU  
mSPPHyBabsdS/Kg5ZAf43ac/MXY9V8Mk6zqbBlj6QYqjJ0nBD6vwozrDQ5gJtDUL  
mQho13zPn4lBJl9YJVjcgRB2WbzgSZOln0DfV22Seai66vnr5NyaOIw5B9QLSNhN  
EaPFswEDLKCsns9dkDuGFX52/Mt/i7JySvwhMBqHElPzWmwCHeY45M8gBYhGBBAR  
AgAGBQJLfsbpAAoJECH7Y/6XEsLNuasAn0Q0jB4Ea/95EREUkCFTm9L6nOpAAJ9t  
QzwGXhrLFZzOdRWYiWcCQbX5/7kBDQRLfsVzAQgAvN5jr95pJthv2w9co9/7omhM  
5rAnr9WJfbMLLiUfPPUvpL24RGO6SKy03aiVTUjlaHc+cGqOciwnNKMCSt+noyG2  
kNnAESTDtCivpsjonaFP8jA3TqL0QK+yzBRKJnMnLEY1nWE1FtkMRccXvzi0Z/XQ  
VhiWQyTvDFoKtepBFrH9UqWbNHyki22aighumUsW01pcPH2ogSj+HR01r7SfI/y2  
EkE6loHQfCDycHmlqYV+X6GZEvf1qu2+EHEQChsHIAxWyshsxM/ZPmx/8e5S3Xmj  
l7h/6E9wcsIpvnf504sLX5j4Km9I5HgJSRxHxgRPpqJ2/XiClAJanO5gCw0RdQAR  
AQABiQEfBBgBAgAJBQJLfsVzAhsMAAoJEBF+jBaO/jp/SqEH/iArzrfVOhZQGuy1  
KmG0+/FdJGqAEHP5HWpsaeYJok1VmhTPZd4IVFBz/bGJYyvsrPU0pJ6QLkdGxNnb  
KulJocgkW5MKEL/CRc54ESKwYngigmbY4qLwhS+gB3BJg1TvoHD810MSj4wdxNNo  
6JQmFmuoDsLRwaRYbKQDz95XXoGQtmV1o57T05WkLuC5OmHqnWv3rggVC8madpUJ  
moUUvUWgU1qyXe3PrgMGFOibWIl7lPZ08nzKXBRvSK/xoTGxl+570AevfVHMu5Uk  
Yu2U6D6/DYohtTYp0s1ekS5KQkCJM7lfqecDsQhfVfOfR0w4aF8k8u3HmWdOfUz+  
9+2ZsBo=  
=myjM  
-----END PGP PUBLIC KEY BLOCK-----''']  

```

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

### Perform a rootless build with bootc-image-builder

Source: https://osbuild.org/docs/bootc

Example of running the builder in rootless mode using the --in-vm flag and mounting local container storage.

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

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

### Install test dependencies for osbuild

Source: https://osbuild.org/docs/developer-guide/projects/osbuild

Install required test dependencies using dnf. Some tests are skipped if these prerequisites are not installed.

```bash
sudo dnf install -y systemd-boot-unsigned erofs-utils pykickstart podman xfsprogs
```

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

### osbuild example-3.json output

Source: https://osbuild.org/docs/developer-guide/projects/osbuild/manifest

Example output from running osbuild with example-3.json, showing pipeline sources, durations, and success message.

```text
starting example-3.json  
Pipeline source org.osbuild.inline: 02340d3e  
Build  
  root: <host>  
  
⏱  Duration: 1756035220s  
Pipeline source org.osbuild.curl: c33c828e  
  
⏱  Duration: 0s  
org.osbuild.copy: 7a83e94e  
  
⏱  Duration: 0s  
Pipeline archive: c33c828e  
  
⏱  Duration: 1s  
manifest example-3.json finished successfully  
files:          7a83e94e
```

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

### Push example.toml blueprint

Source: https://osbuild.org/docs/on-premises/commandline/edge-container%2Binstaller

Pushes the example.toml blueprint to osbuild-composer.

```bash
$ composer-cli blueprints push example.toml  

```

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

### Install npm dependencies

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-frontend

Runs a clean installation of npm dependencies to ensure Playwright and other required packages are installed as per the project's dev dependencies.

```bash
npm clean-install  

```

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

### Blueprint with distro and packages (on premises)

Source: https://osbuild.org/docs/user-guide/blueprint-reference

Two on-premises blueprint examples that select a distribution via the distro field. The first uses fedora-44, the second uses rhel-10.2. Both install tmux and openssh-server packages. Note that osbuild-composer prior to version 100 used a different distro naming scheme without a dot; new versions accept both, but future versions will require the dotted format (e.g., rhel-10.2).

```toml
name = "tmux"  
description = "tmux image with openssh"  
version = "1.2.16"  
distro = "fedora-44"  
  
[[packages]]  
name = "tmux"  
version = "*"  
  
[[packages]]  
name = "openssh-server"  
version = "*"  

```

```toml
name = "tmux"  
description = "tmux image with openssh"  
version = "1.2.16"  
distro = "rhel-10.2"  
  
[[packages]]  
name = "tmux"  
version = "*"  
  
[[packages]]  
name = "openssh-server"  
version = "*"  

```

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

### Create example.toml blueprint

Source: https://osbuild.org/docs/on-premises/commandline/edge-container%2Binstaller

Blueprint for the edge-container commit. Must be saved as example.toml. Includes packages and a user with a password hash.

```toml
name = "example"  
description = "RHEL for Edge Installer example"  
version = "0.0.3"  
  
[[packages]]  
name = "vim-enhanced"  
version = "*"  
  
[[packages]]  
name = "tmux"  
version = "*"  
  
[customizations]  
  
[[customizations.user]]  
name = "user"  
description = "Example User"  
password = "$6$uvdfeuHQYM6kUaea$fvvzyu.Z.u89TVCB2tq8UEc52XDFGnAqCo75BX3zu8OzIbS.EKMo/Saammb151sLrdzmlESnpNEPrJ7h5b0c6/"  
groups = ["wheel"]  

```

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

### Build a qcow2 image from a bootable container with --bootc-ref

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/usage

Pulls a bootable container and builds a qcow2 image from it using the --bootc-ref argument. The container must already be in the local container storage before running image-builder.

```bash
$ sudo podman pull quay.io/centos-bootc/centos:stream10  
$ sudo image-builder build --bootc-ref quay.io/centos-bootc/centos:stream10 qcow2  
# ...  

```

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

### Install dev dependencies

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-crc/HACKING

Run this command to install the development dependencies required for the project.

```bash
make dev-prerequisites

```

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

### Install dependencies for generating manifests

Source: https://osbuild.org/docs/developer-guide/projects/images/docs/developer

Install the osbuild packages required to generate manifests.

```bash
dnf -y install osbuild osbuild-depsolve-dnf osbuild-luks2 osbuild-lvm2 osbuild-ostree osbuild-selinux
```

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

### Start compose with composer-cli

Source: https://osbuild.org/docs/on-premises/commandline/building-ostree-images

Starts a compose for the OSTree commit, outputting a compose ID.

```bash
$ sudo composer-cli compose start fishy-commit fedora-iot-commit  
Compose 8e8014f8-4d15-441a-a26d-9ed7fc89e23a added to the queue  

```

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

### Install frontend locally for Cockpit development

Source: https://osbuild.org/docs/developer-guide/projects/image-builder-frontend

Creates a symbolic link in ~/.local/share/cockpit/ pointing to the built frontend assets.

```make
make cockpit/devel-install  
```

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

### Build with --force-repo

Source: https://osbuild.org/docs/developer-guide/projects/image-builder/advanced/repositories

Builds a minimal-raw-xz image for Fedora 43 using only the repository given by --force-repo. The repository must contain all necessary packages.

```bash
$ sudo image-builder build --distro fedora-43 --force-repo https://some/base/url minimal-raw-xz  

```

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

### Install image-builder CLI packages

Source: https://osbuild.org/docs/on-premises/installation

Installs the image-builder CLI and its required packages on a local machine.

```bash
$ sudo dnf install image-builder osbuild osbuild-depsolve-dnf  

```
Tokens:
Raw