# 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**

```bash
# 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**

```bash
# 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**

```bash
# 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**

```bash
# 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**

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

```bash
# 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)

```bash
# 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)

```bash
# 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)

```bash
# 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**

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

```bash
# 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**

```bash
# 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](https://docs.fedoraproject.org/en-US/fedora-coreos/)**
- **[bootc Documentation](https://github.com/containers/bootc)**
- **[OSTree Documentation](https://ostreedev.github.io/ostree/)**
- **[Debian Atomic Development](https://git.raines.xyz/particle-os/debian-atomic)**

## 🎯 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.