debian-atomic/docs/fedora-tools-bootable-instructions.md

Making Debian Atomic Bootable Using Fedora Tools

Note: This approach introduces Fedora dependencies but provides immediate bootability while waiting for Debian-native tools.

🎯 Overview

This guide shows how to make Debian Atomic bootable using Fedora's mature atomic tools. This is a temporary solution until Debian-native tools are ready.

📋 Prerequisites

Fedora-Specific Tools Required

Tool	Source	Purpose	Alternative
bootc-image-builder	Container tool (quay.io/centos-bootc/bootc-image-builder)	Convert OCI containers to bootable images	None (Fedora-specific)
rpm-ostree	Fedora repositories	OSTree package management	apt-ostree (in development)
bootupd	Fedora repositories	Bootloader management	deb-bootupd (in development)
bootc	Fedora repositories	Container deployment	deb-bootc (in development)
ostree	Fedora repositories	OSTree core tools	Available on Debian
systemd	Fedora repositories	System initialization	Available on Debian

Installation on Fedora Host

# Install required Fedora packages
sudo dnf install -y \
    rpm-ostree \
    bootupd \
    bootc \
    ostree \
    systemd

# Pull bootc-image-builder container (it's a tool, not a package)
sudo podman pull quay.io/centos-bootc/bootc-image-builder:latest

# Verify installations
rpm-ostree --version
bootupd --version
bootc --version
podman images | grep bootc-image-builder

🚀 Step-by-Step Instructions

Step 1: Build Debian Atomic Container Image

# Clone Debian Atomic repository
git clone https://git.raines.xyz/particle-os/debian-atomic.git
cd debian-atomic

# Build the OSTree-enabled base variant
just compose-debian-bootc-base

# Push to registry (replace with your registry)
just build-deploy debian-bootc-base

Step 2: Convert to Bootable Image Using bootc-image-builder Container

# Use bootc-image-builder container to convert OCI container to bootable image
sudo podman run --rm -it --privileged \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    --output . \
    oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest

# Alternative: Generate ISO
sudo podman run --rm -it --privileged \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type iso \
    --output . \
    oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest

Step 3: Test Bootable Image

# Test QCOW2 image in QEMU
qemu-system-x86_64 \
    -hda *.qcow2 \
    -m 4G \
    -smp 2 \
    -enable-kvm \
    -bios /usr/share/edk2/ovmf/OVMF_CODE.fd

# Test ISO image in QEMU
qemu-system-x86_64 \
    -cdrom *.iso \
    -m 4G \
    -smp 2 \
    -enable-kvm \
    -bios /usr/share/edk2/ovmf/OVMF_CODE.fd

Step 4: Deploy to Real Hardware

# Install to existing system using bootc
sudo bootc install to-existing-root \
    --source-imgref oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest

# Or install to new disk
sudo bootc install \
    --source-imgref oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest \
    --target /dev/sdX

🔧 Fedora Tools Deep Dive

1. bootc-image-builder (Container Tool)

What it is: A container tool that converts OCI containers to bootable disk images Why Fedora-specific: Built for Fedora's container workflow, distributed as a container How to use: Run as a privileged container with volume mounts Alternatives: None currently available for Debian

# Key features
podman run --rm quay.io/centos-bootc/bootc-image-builder:latest --help

# Supported image types
--type qcow2        # QEMU virtual machine
--type iso          # Bootable ISO
--type raw          # Raw disk image
--type ami          # AWS AMI
--type gce          # Google Cloud image
--type vmdk         # VMware virtual machine

2. rpm-ostree

What it does: Manages OSTree deployments with RPM packages Why Fedora-specific: Designed for RPM package ecosystem Alternatives: apt-ostree (in development)

# Key commands
rpm-ostree status          # Show deployment status
rpm-ostree upgrade         # Upgrade to new deployment
rpm-ostree rollback        # Rollback to previous deployment
rpm-ostree install pkg     # Install additional packages

3. bootupd

What it does: Manages UEFI boot entries and bootloader updates Why Fedora-specific: Fedora's bootloader management solution Alternatives: deb-bootupd (in development)

# Key commands
bootupd status             # Show bootloader status
bootupd update             # Update bootloader
bootupd install            # Install bootloader

4. bootc

What it does: Deploys and manages bootable containers Why Fedora-specific: Fedora's container deployment tool Alternatives: deb-bootc (in development)

# Key commands
bootc status               # Show deployment status
bootc upgrade              # Upgrade to new image
bootc install              # Install new deployment

⚠️ Limitations and Considerations

Fedora Dependencies

• Package Management: Uses RPM instead of APT
• Security Model: SELinux instead of AppArmor
• System Tools: Fedora-specific systemd configurations
• Update Workflow: Fedora release cycle instead of Debian
• Container Tools: bootc-image-builder is Fedora-specific container

Compatibility Issues

• Package Conflicts: RPM vs DEB package formats
• Library Differences: Fedora vs Debian library versions
• Configuration Files: Different default configurations
• Service Management: Different systemd service defaults

Workarounds

# Use Debian packages when possible
# Avoid Fedora-specific configurations
# Test thoroughly before production use
# Plan migration to Debian-native tools

🔄 Migration Path to Debian-Native Tools

Phase 1: Fedora Tools (Current)

• Use bootc-image-builder container for image creation
• Use rpm-ostree for package management
• Use bootupd for bootloader management
• Use bootc for deployment

Phase 2: Hybrid Approach (Planned)

• Use Debian-native tools where available
• Fall back to Fedora tools for missing functionality
• Gradually replace Fedora dependencies

Phase 3: Debian-Native (Future)

• apt-ostree for package management
• deb-bootc-image-builder for image creation
• deb-bootupd for bootloader management
• deb-bootc for deployment

📊 Comparison: Fedora vs Debian Tools

Functionality	Fedora Tool	Debian Tool	Status
Image Building	bootc-image-builder (container)	deb-bootc-image-builder	🔄 In Development
Package Management	rpm-ostree	apt-ostree	🔄 In Development
Bootloader Management	bootupd	deb-bootupd	🔄 In Development
Container Deployment	bootc	deb-bootc	🔄 In Development
OSTree Core	ostree	ostree	✅ Available

🎯 Quick Start Commands

# 1. Install Fedora packages
sudo dnf install -y rpm-ostree bootupd bootc

# 2. Pull bootc-image-builder container
sudo podman pull quay.io/centos-bootc/bootc-image-builder:latest

# 3. Build Debian Atomic image
cd debian-atomic
just compose-debian-bootc-base
just build-deploy debian-bootc-base

# 4. Convert to bootable image using container tool
sudo podman run --rm -it --privileged \
    --security-opt label=type:unconfined_t \
    -v /var/lib/containers/storage:/var/lib/containers/storage \
    quay.io/centos-bootc/bootc-image-builder:latest \
    --type qcow2 \
    --output . \
    oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest

# 5. Test in QEMU
qemu-system-x86_64 -hda *.qcow2 -m 4G -smp 2 -enable-kvm

🔍 Troubleshooting

Common Issues

1. bootc-image-builder Container Not Found: Ensure you've pulled the container image
2. Container Build Fails: Check that Debian Atomic builds successfully first
3. Image Conversion Fails: Verify container image has proper OSTree structure
4. Boot Fails: Check UEFI settings and bootloader configuration
5. Permission Denied: Ensure you're running with sudo and proper security opts

Debug Commands

# Check container image
podman inspect oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest

# Check OSTree repository
podman run --rm oci:git.raines.xyz/robojerk/debian-atomic-debian-bootc-base:latest ostree --repo=/ostree/repo refs

# Check bootc-image-builder container
podman run --rm quay.io/centos-bootc/bootc-image-builder:latest --version

# Check available image types
podman run --rm quay.io/centos-bootc/bootc-image-builder:latest build --help

📚 Additional Resources

• Fedora Atomic Documentation
• bootc Documentation
• OSTree Documentation
• Debian Atomic Development

🎯 Bottom Line

Using Fedora tools gives you immediate bootability for Debian Atomic, but introduces Fedora dependencies. This is a practical solution while waiting for Debian-native tools to be ready.

The trade-off is clear: immediate functionality vs. pure Debian ecosystem. Choose based on your current needs and long-term goals.

Key Insight: bootc-image-builder is not a package but a container tool that runs as a privileged container. This is why it's Fedora-specific and can't be easily ported to Debian.