particle-os/debian-atomic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add comprehensive documentation and improve container configuration

Browse source 
- 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
This commit is contained in:
robojerk 2025-08-19 20:51:01 -07:00
parent af2678743e
commit a207949d9f
8 changed files with 1377 additions and 42 deletions
Download patch file Download diff file Expand all files Collapse all files

297
docs/fedora-tools-bootable-instructions.md Normal file
View file

@ -0,0 +1,297 @@
# 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.