A container for deploying bootable container images.

Have podman installed on your system. Either through your systems package manager if you're on Linux or through Podman Desktop if you are on macOS or Windows. If you want to run the resulting virtual machine(s) or installer media you can use qemu.

On macOS, the podman machine must be running in rootful mode:

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

The following example builds a Fedora ELN bootable container into a QCOW2 image for the architecture you're running the command on.

mkdir -p output
sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v $(pwd)/output:/output \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    quay.io/centos-bootc/fedora-bootc:eln

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

This assumes qemu was installed through homebrew.

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

Usage:
  sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v $(pwd)/output:/output \
    quay.io/centos-bootc/bootc-image-builder:latest \
    <imgref>

Flags:
      --config string   build config file
      --tls-verify      require HTTPS and verify certificates when contacting registries (default true)
      --type string     image type to build [qcow2, ami] (default "qcow2")

💡 Tip: Flags in bold are the most important ones.

The following image types are currently available via the --type argument:

AMIs can be automatically uploaded to AWS by specifying the following flags:

Notes:

• These flags must all be specified together. If none are specified, the AMI is exported to the output directory.
• The bucket must already exist in the selected region, bootc-image-builder will not create it if it is missing.
• The output volume is not needed in this case. The image is uploaded to AWS and not exported.

If you already have a credentials file (usually in $HOME/.aws/credentials) you need to forward the directory to the container

For example:

$ sudo podman run \
 --rm \
 -it \
 --privileged \
 --pull=newer \
 --security-opt label=type:unconfined_t \
 -v $HOME/.aws:/root/.aws:ro \
 quay.io/centos-bootc/bootc-image-builder:latest \
 --type ami \
 --aws-profile default \
 --aws-ami-name fedora-bootc-ami \
 --aws-bucket fedora-bootc-bucket \
 --aws-region us-east-1 \
 quay.io/centos-bootc/fedora-bootc:eln

Notes:

• the argument --aws-profile is optional and is "default" if not specified
• instead of the --aws-profile you can also set the environment variable AWS_PROFILE like described below.

AWS credentials can be specified through two environment variables:

You can set these variables while running the container by saving them to a file and passing them using the --env-file flag for podman run. For example:

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

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

The following volumes can be mounted inside the container:

A build config is a JSON file with customizations for the resulting image. A path to the file is passed via the --config argument. The customizations are specified under a blueprint.customizations object.

As an example, let's show how you can add a user to the image:

Firstly create a file output/config.json and put the following content into it:

{
  "blueprint": {
    "customizations": {
      "user": [
        {
          "name": "foo",
          "password": "bar",
          "groups": [
            "wheel"
          ]
        }
      ]
    }
  }
}

Then, run bootc-image-builder with the following arguments:

sudo podman run \
    --rm \
    -it \
    --privileged \
    --pull=newer \
    --security-opt label=type:unconfined_t \
    -v $(pwd)/output:/output \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    --config /output/config.json \
    quay.io/centos-bootc/fedora-bootc:eln

Possible fields:

Example:

{
  "user": [
    {
      "name": "alice",
      "password": "bob",
      "groups": [
        "wheel",
        "admins"
      ]
    }
  ]
}

To build the container locally you can run

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

NOTE: running already the podman build as root avoids problems later as we need to run the building of the image as root anyway

• Website: https://www.osbuild.org
• Bug Tracker: https://github.com/osbuild/bootc-image-builder/issues
• Matrix: #image-builder on fedoraproject.org
• Mailing List: [email protected]
• Changelog: https://github.com/osbuild/bootc-image-builder/releases

Please refer to the developer guide to learn about our workflow, code style and more.

• web: https://github.com/osbuild/bootc-image-builder
• https: https://github.com/osbuild/bootc-image-builder.git
• ssh: [email protected]:osbuild/bootc-image-builder.git

• Apache-2.0
• See LICENSE file for details.