robojerk
a207949d9f
- Add technical report on Debian atomic image creation - Add Fedora tools bootable instructions and implementation report - Add apt-tool blocking implementation documentation - Add environment configuration example - Update .gitignore with better artifact blocking - Update justfile and Containerfile configurations - Improve variants configuration for debian-bootc-base
297 lines
9.7 KiB
Markdown
297 lines
9.7 KiB
Markdown
# 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.
|