bootc-image-builder

A tool to convert bootc container images to bootable disk images. This tool creates bootable VM images from bootc-compatible container images, handling the complete bootc workflow including OSTree integration, composefs setup, initramfs creation, and bootloader installation.

Features

• ✅ Multi-format Support: QCOW2, Raw, VMDK, ISO, AMI
• ✅ Bootc Integration: Full bootc container image support
• ✅ OSTree Repository: Creates and manages OSTree repositories
• ✅ Composefs Support: Efficient container filesystem mounting
• ✅ Initramfs Creation: Uses dracut to create bootc-aware initramfs
• ✅ Bootloader Support: GRUB and systemd-boot installation
• ✅ UEFI/BIOS Support: Both UEFI and BIOS boot modes
• ✅ Secure Boot: Optional secure boot configuration
• ✅ Cloud Integration: AWS, Azure, GCP optimizations

Installation

Prerequisites

You need the following tools installed on your system:

# Container runtime
sudo apt install podman

# Disk image tools
sudo apt install qemu-utils parted

# OSTree and composefs
sudo apt install ostree libostree-dev

# Bootloader tools
sudo apt install grub-efi-amd64 systemd-boot

# Initramfs tools
sudo apt install dracut

# Build tools
sudo apt install build-essential

Build from Source

git clone https://github.com/apt-ostree/bootc-image-builder
cd bootc-image-builder
cargo build --release
sudo cp target/release/bootc-image-builder /usr/local/bin/

Usage

Basic Usage

# Convert a bootc container image to QCOW2
bootc-image-builder build localhost/my-debian-server:latest --format qcow2

# Convert to raw disk image
bootc-image-builder build localhost/my-debian-server:latest --format raw --output my-server.img

# Convert to VMDK for VMware
bootc-image-builder build localhost/my-debian-server:latest --format vmdk --output my-server.vmdk

Advanced Usage

# Build with custom settings
bootc-image-builder build localhost/my-debian-server:latest \
  --format qcow2 \
  --size 20 \
  --arch x86_64 \
  --bootloader grub \
  --secure-boot \
  --kernel-args "console=ttyS0,115200n8 quiet" \
  --output my-server.qcow2

# Build for cloud deployment
bootc-image-builder build localhost/my-debian-server:latest \
  --format ami \
  --cloud-provider aws \
  --output my-server-ami

Command Line Options

bootc-image-builder build [OPTIONS] <IMAGE>

Arguments:
  <IMAGE>  The name of the bootc container image to build from

Options:
  -f, --format <FORMAT>        The format of the output disk image [default: qcow2] [possible values: qcow2, raw, vmdk, iso, ami]
  -o, --output <OUTPUT>        The path to save the generated disk image file [default: bootc-image]
  -s, --size <SIZE>            The size of the disk image in GB [default: 10]
      --arch <ARCH>            The architecture to build for [default: x86_64] [possible values: x86_64, aarch64, ppc64le]
      --bootloader <BOOTLOADER> The bootloader to use [default: grub] [possible values: grub, systemd-boot]
      --secure-boot            Enable secure boot support
      --uefi                   Enable UEFI boot (default: auto-detect)
      --bios                   Enable BIOS boot (default: auto-detect)
      --kernel-args <KERNEL_ARGS> Custom kernel command line arguments [default: "console=ttyS0,115200n8 quiet"]
      --cloud-provider <CLOUD_PROVIDER> Cloud provider for cloud-specific optimizations [possible values: aws, azure, gcp]
  -h, --help                   Print help
  -V, --version                Print version

How It Works

The bootc-image-builder follows this workflow:

1. Pull and Extract: Downloads and extracts the bootc container image
2. Setup Bootc Support: Installs bootc binary and configuration
3. Create OSTree Repository: Sets up OSTree repository structure
4. Configure Composefs: Enables composefs for efficient container mounting
5. Create Initramfs: Uses dracut to create bootc-aware initramfs
6. Install Bootloader: Installs GRUB or systemd-boot
7. Create Disk Image: Partitions, formats, and copies files to disk image

Examples

Building a Debian Server Image

# 1. Create a bootc container image with apt-ostree
apt-ostree compose tree debian-server.yaml --container

# 2. Convert to bootable disk image
bootc-image-builder build localhost/debian-server:latest \
  --format qcow2 \
  --size 10G \
  --bootloader grub

# 3. Boot in QEMU
qemu-system-x86_64 -drive file=debian-server.qcow2,format=qcow2

Building a Cloud Image

# 1. Create cloud-optimized bootc image
apt-ostree compose tree cloud-server.yaml --container

# 2. Convert to AMI format
bootc-image-builder build localhost/cloud-server:latest \
  --format ami \
  --cloud-provider aws \
  --size 8G

# 3. Deploy to AWS
aws ec2 run-instances --image-id ami-12345678 --instance-type t3.micro

Architecture Support

• x86_64: Intel/AMD 64-bit (default)
• aarch64: ARM 64-bit
• ppc64le: PowerPC 64-bit

Format Support

• QCOW2: QEMU, KVM, OpenStack (default)
• Raw: Direct disk images
• VMDK: VMware compatibility
• ISO: Bootable CDs/DVDs
• AMI: Amazon Web Services

Bootloader Support

• GRUB: Traditional bootloader with BLS support
• systemd-boot: Modern UEFI bootloader

Security Features

• Secure Boot: UEFI secure boot support
• Immutable: Read-only filesystem by default
• Atomic Updates: OSTree-based atomic updates
• Container Isolation: Container-based system management

Troubleshooting

Common Issues

1. Permission Denied: The tool requires root/sudo privileges for disk operations
2. Missing Dependencies: Ensure all required tools are installed
3. Dracut Failures: Falls back to minimal initramfs if dracut fails
4. Loop Device Issues: May need to unmount existing loop devices

Debug Mode

# Enable debug logging
RUST_LOG=debug bootc-image-builder build localhost/my-image:latest

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• apt-ostree - Debian/Ubuntu equivalent of rpm-ostree
• bootc - Container images that can boot directly
• ostree - Operating system and container image management
• composefs - Efficient read-only filesystem for containers