Restructure project layout for better CI/CD integration

- Flattened nested bootupd/bootupd/ structure to root level - Moved all core project files to root directory - Added proper Debian packaging structure (debian/ directory) - Created build scripts and CI configuration - Improved project organization for CI/CD tools - All Rust source, tests, and configuration now at root level - Added GitHub Actions workflow for automated testing - Maintained all original functionality while improving structure
2025-08-09 23:11:42 -07:00 · 2025-08-09 23:11:42 -07:00 · aaf662d5b1
commit aaf662d5b1
parent 5e8730df43
87 changed files with 1334 additions and 570 deletions
--- a/deb-bootupd.md
+++ b/deb-bootupd.md
@ -0,0 +1,382 @@
+# Debian Bootupd Fork Plan
+
+## Project Overview
+**Goal**: Create a Debian-compatible version of bootupd to make particle-os (Debian-based ublue-os) bootable.
+
+**Context**: 
+- **Proof-of-concept**: Test if we can create an immutable Debian using ublue-os tools
+- Original bootupd is Red Hat/Fedora-centric with RPM dependencies
+- Need to adapt for **Debian OSTree immutable systems** (not traditional Debian)
+- Target: Debian Trixie slim container image converted to bootc format
+- **Critical Insight**: This is a hybrid system - Debian packages within immutable OSTree structure
+- **Success metric**: Can we boot a Debian-based immutable system?
+
+## Key Understanding: OSTree vs Traditional Debian
+
+### **Traditional Debian (Mutable)**
+- Package-based updates via `apt`/`dpkg`
+- Mutable filesystem with writable `/usr`
+- Kernel in `/boot/vmlinuz-$kver`
+- GRUB configured via `grub-mkconfig`/`update-grub`
+
+### **Particle-OS (Immutable OSTree)**
+- Image-based atomic updates via bootc
+- Immutable `/usr` (read-only core OS)
+- Kernel embedded in `/usr/lib/modules/$kver/vmlinuz`
+- GRUB configured to point to OSTree deployment paths
+- Configuration in `/etc` (writable, three-way merge)
+- State in `/var` (shared across deployments)
+- OSTree object store in `/ostree`
+
+## Phase 1: Project Setup & Structure
+
+### 1.1 Create Debian Bootupd Directory Structure
+```
+deb-bootupd/
+├── src/                    # Source code (adapted from .Red_Hat_Version/bootupd/src/)
+├── systemd/               # Systemd service files
+├── tests/                 # Test suite
+├── Cargo.toml            # Dependencies adapted for Debian
+├── README.md             # Debian-specific documentation
+├── debian/               # Debian packaging files
+└── scripts/              # Build and deployment scripts
+```
+
+### 1.2 Initialize Git Repository
+- Fork from original bootupd repository
+- Create debian branch
+- Set up proper attribution and licensing
+
+### 1.3 Git Strategy: Hard Clean Fork
+**Approach**: Simple, direct fork for proof-of-concept
+
+**Benefits**:
+- **Clean start**: No complex git history or upstream sync complexity
+- **Focus on core**: Concentrate on making Debian immutable system bootable
+- **Proof-of-concept**: Perfect for testing the concept without maintenance overhead
+- **Simple workflow**: Just copy, adapt, and test
+
+**Implementation**:
+```bash
+# Simple copy approach
+cp -r .Red_Hat_Version/bootupd deb-bootupd/
+cd deb-bootupd
+chmod 755 deb-bootupd
+git init
+git add .
+git commit -m "Initial Debian fork of bootupd for immutable Debian proof-of-concept"
+```
+
+**Future considerations**: Can always add upstream sync later if the concept proves viable
+
+## Phase 2: Core Code Adaptation
+
+### 2.1 Package System Integration (`src/packagesystem.rs`)
+**Current Issue**: Hard dependency on RPM commands
+**Solution**: Rewrite for DPKG/APT
+
+**OSTree-Specific Considerations**:
+- **Not traditional package management**: Particle-OS uses image-based updates, not `apt`/`dpkg`
+- **Package queries**: Still need DPKG integration for querying existing package metadata
+- **Update mechanism**: Updates come from new bootc images, not package repositories
+- **Version tracking**: Need to track Debian package versions within the immutable OS tree
+
+**Kernel Detection Challenge**:
+- **File location**: `/usr/lib/modules/*/vmlinuz` (same as Red Hat)
+- **Filename parsing**: Must handle Debian kernel naming conventions
+- **Critical files**: `src/efi.rs` and `src/bios.rs` kernel detection logic
+- **Example difference**: `vmlinuz-6.1.0-13-amd64` vs `vmlinuz-6.1.0-1.fc38.x86_64`
+
+**Changes Required**:
+```rust
+// Replace RPM-specific code:
+// OLD: rpm -q --queryformat "%{nevra},%{buildtime}" -f <file>
+// NEW: dpkg -S <file> && dpkg -s <package> | grep "Installed-Time"
+
+// Replace RPM database paths:
+// OLD: usr/lib/sysimage/rpm, usr/share/rpm
+// NEW: var/lib/dpkg, usr/share/doc
+```
+
+**Implementation**:
+- Create `dpkg_parse_metadata()` function
+- Parse DPKG output format instead of RPM
+- Handle Debian package versioning conventions
+- Support both `dpkg -S` and `dpkg -s` queries
+
+### 2.2 OSTree Utilities (`src/ostreeutil.rs`)
+**Current Issue**: RPM command construction
+**Solution**: Adapt for Debian package database structure
+
+**Changes Required**:
+- Replace `rpm_cmd()` with `dpkg_cmd()`
+- Update database path detection logic
+- Maintain OSTree integration compatibility
+
+### 2.3 CoreOS Integration (`src/coreos.rs`)
+**Current Issue**: Fedora CoreOS-specific Aleph version parsing
+**Solution**: Adapt for Debian/particle-os versioning
+
+**Changes Required**:
+- Replace `.coreos-aleph-version.json` with Debian-specific version file
+- Update version parsing logic for Debian conventions
+- Remove Fedora-specific test data references
+
+### 2.4 Hardcoded Paths
+**Current Issues**:
+- `/usr/lib/bootupd/updates` (hardcoded in `model.rs`)
+- `/boot` state directory (hardcoded in `statefile.rs`)
+- `/run/bootupd-lock` lock file path
+
+**Solution**: Make paths configurable or follow Debian conventions
+- Consider using `/var/lib/bootupd/updates` (FHS compliant)
+- Keep `/boot` for state (standard across distributions)
+- Keep `/run` for locks (standard across distributions)
+
+### 2.5 OSTree-Specific Adaptations
+**Critical Changes for Debian OSTree**:
+
+**Kernel Path Adaptation**:
+```rust
+// Current (Red Hat): /usr/lib/modules/*/vmlinuz
+// Debian OSTree: /usr/lib/modules/*/vmlinuz (same path, different context)
+// Need to ensure this works with Debian kernel naming conventions
+```
+
+**Kernel Filename Parsing** (Key Challenge):
+- **Red Hat convention**: `vmlinuz-6.1.0-1.fc38.x86_64`
+- **Debian convention**: `vmlinuz-6.1.0-13-amd64`
+- **Critical**: Filename parsing logic must handle Debian version format
+- **Location**: This affects `src/efi.rs` and `src/bios.rs` kernel detection
+
+**Bootloader Configuration**:
+- **Current**: GRUB configs from coreos-assembler
+- **Debian OSTree**: GRUB configs pointing to OSTree deployment paths
+- **Path format**: `/ostree/deploy/debian/deploy/$checksum.0/vmlinuz`
+
+**State Management**:
+- **Current**: State in `/boot/bootupd-state.json`
+- **Debian OSTree**: State must persist across OSTree deployments
+- **Location**: Consider `/var/lib/bootupd/` for persistent state
+
+## Phase 3: System Integration
+
+### 3.1 System Commands
+**Current Dependencies**:
+- `efibootmgr` (EFI boot management)
+- `mount`/`umount` (filesystem operations)
+- `grub-install` (GRUB installation)
+
+**Debian Compatibility**:
+- ✅ `efibootmgr`: Available in Debian repositories
+- ✅ `mount`/`umount`: Standard Linux tools
+- ✅ `grub-install`: Available in Debian repositories
+
+**Action**: Ensure these packages are available in particle-os base image
+
+### 3.2 Systemd Integration
+**Current**: Hard dependency on `libsystemd`
+**Debian**: ✅ Fully supports systemd
+**Action**: No changes needed, maintain compatibility
+
+### 3.3 OS Detection
+**Current**: Red Hat-specific logic
+**Solution**: Enhance OS detection for Debian
+
+**Changes Required**:
+```rust
+// Current logic in efi.rs:
+// 1. Try /etc/system-release (Red Hat specific)
+// 2. Fall back to /etc/os-release
+
+// Enhanced logic:
+// 1. Try /etc/os-release first (standard)
+// 2. Parse for Debian family distributions
+// 3. Fall back to /etc/system-release for Red Hat
+// 4. Handle Debian-specific version formats
+```
+
+## Phase 4: Debian-Specific Features
+
+### 4.1 Package Manager Integration
+**New Features**:
+- APT package discovery integration
+- Debian package version comparison
+- Support for Debian backports and testing repositories
+
+**OSTree-Specific Features**:
+- **Image-based update detection**: Detect new bootc images vs package updates
+- **Deployment coordination**: Work with OSTree deployment system
+- **Rollback support**: Leverage OSTree's built-in rollback capabilities
+- **State persistence**: Ensure bootupd state survives across deployments
+
+### 4.2 Debian OSTree Integration
+**Unique Challenges**:
+- **Hybrid approach**: Debian packages within immutable OSTree system
+- **Update workflow**: New images contain updated Debian packages
+- **Version compatibility**: Ensure Debian package versions work with OSTree structure
+- **Bootloader updates**: Coordinate with OSTree deployment changes
+
+### 4.3 Distribution-Specific Bootloader Configs
+**Current**: Static GRUB configs from coreos-assembler
+**Solution**: Create Debian-specific GRUB configurations
+- Support for Debian kernel naming conventions
+- Debian-specific boot parameters
+- Integration with Debian initramfs tools
+- **OSTree path integration**: GRUB configs pointing to OSTree deployment paths
+
+### 4.4 Debian Package Dependencies
+**Update Cargo.toml**:
+- Keep core dependencies (anyhow, clap, serde, etc.)
+- Maintain systemd integration
+- Add Debian-specific optional features
+
+## Phase 5: Testing & Validation
+
+### 5.1 Test Suite Adaptation
+**Current**: Fedora/RPM-centric tests
+**Solution**: Create Debian-compatible test suite
+
+**Test Categories**:
+- Unit tests for DPKG parsing functions
+- Integration tests with Debian package databases
+- End-to-end tests in Debian container environments
+- Bootloader update simulation tests
+
+### 5.2 Particle-OS Integration Testing
+**Test Scenarios**:
+- Fresh particle-os installation
+- Bootloader adoption from existing Debian systems
+- Update process validation
+- Rollback functionality testing
+
+**OSTree-Specific Testing**:
+- **Deployment switching**: Test bootloader updates across OSTree deployments
+- **State persistence**: Verify bootupd state survives deployment switches
+- **Image updates**: Test with new bootc images containing updated Debian packages
+- **Rollback scenarios**: Test bootloader rollback with OSTree deployment rollback
+- **Hybrid updates**: Test scenarios where Debian packages and OSTree images are updated
+
+## Phase 6: Packaging & Deployment
+
+### 6.1 Debian Package Creation
+**Files Required**:
+- `debian/control` (package metadata)
+- `debian/rules` (build instructions)
+- `debian/changelog` (version history)
+- `debian/postinst` (post-installation scripts)
+
+**Build System Integration**:
+- **dh-cargo**: Use Debian's Rust packaging helper
+- **Benefits**: Automates cargo build, cargo install, and dependency handling
+- **debian/rules**: Simplified with dh-cargo integration
+- **Cargo.lock**: Include for reproducible builds
+- **Vendor directory**: Consider including for offline builds
+
+### 6.2 Container Integration
+**Integration Points**:
+- particle-os base image requirements
+- Bootc image builder integration
+- Container runtime compatibility
+
+### 6.3 Bootc Image Builder Integration
+**Critical Integration Points**:
+
+**Build Process Integration**:
+- **Include deb-bootupd**: Binary must be built and included in the bootc image
+- **Build timing**: deb-bootupd compiled during image build, not first boot
+- **Dependencies**: Ensure all required tools (`efibootmgr`, `grub-install`) are in base image
+
+**Image Builder Workflow**:
+1. **Build phase**: Compile deb-bootupd using debian-bootc-image-builder
+2. **Installation**: Install deb-bootupd binary and systemd service
+3. **Configuration**: Set up initial bootloader configuration
+4. **First boot**: deb-bootupd runs to adopt existing bootloader or install new one
+
+**debian/control Integration**:
+- **Build dependencies**: Use `dh-cargo` for Rust build system integration
+- **Runtime dependencies**: Ensure `efibootmgr`, `grub-common` are available
+- **Package naming**: Consider `deb-bootupd` vs `bootupd` package name
+
+## Phase 7: Documentation & Maintenance
+
+### 7.1 Documentation Updates
+**Required Documents**:
+- Debian-specific README
+- Installation guide for particle-os
+- Troubleshooting guide
+- Migration guide from Red Hat systems
+
+### 7.2 Maintenance Strategy
+**Ongoing Tasks**:
+- Track upstream bootupd changes
+- Adapt new features for Debian
+- Maintain Debian package compatibility
+- Community support and bug fixes
+
+## Implementation Priority
+
+### High Priority (Phase 1-2) - Proof-of-Concept Core
+1. **Package system adaptation** (RPM → DPKG) - Essential for Debian compatibility
+2. **Core path and dependency fixes** - Make it compile and run
+3. **Basic Debian compatibility** - Get it working on Debian system
+
+### Medium Priority (Phase 3-4) - Basic Functionality
+1. **Enhanced OS detection** - Proper Debian identification
+2. **Debian-specific features** - Basic bootloader management
+3. **Testing infrastructure** - Verify it works
+
+### Low Priority (Phase 5-7) - Polish & Production
+1. **Advanced features** - Only if proof-of-concept succeeds
+2. **Documentation** - Only if proof-of-concept succeeds
+3. **Long-term maintenance** - Only if proof-of-concept succeeds
+
+## Success Criteria
+
+### Proof-of-Concept Success (Phases 1-2)
+- [ ] **Debian bootupd compiles successfully** - Basic Rust compilation
+- [ ] **Package system queries work with DPKG** - Can read Debian package info
+- [ ] **Basic bootloader detection works** - Can identify EFI/BIOS systems
+
+### Core Functionality Success (Phase 3-4)
+- [ ] **Bootloader management works on Debian** - Can install/update GRUB
+- [ ] **OSTree integration functions** - Works with Debian OSTree deployment
+- [ ] **State management works** - Can track bootloader state
+
+### Full Success (Phase 5+)
+- [ ] **Particle-OS image boots successfully** - Proof-of-concept achieved!
+- [ ] **Bootloader updates work end-to-end** - Can update from new images
+- [ ] **Rollback functionality works** - Can rollback to previous state
+
+**Ultimate Goal**: Boot a Debian-based immutable system using ublue-os tools
+
+## Risk Mitigation
+
+### Technical Risks
+1. **Package format differences**: RPM vs DPKG complexity
+2. **Path conventions**: Red Hat vs Debian filesystem standards
+3. **Tool availability**: Ensuring required tools exist in Debian
+4. **OSTree integration complexity**: Coordinating with Debian OSTree deployment system
+5. **Hybrid system challenges**: Debian packages within immutable OSTree structure
+
+### Mitigation Strategies
+1. **Incremental development**: Test each component individually
+2. **Fallback mechanisms**: Graceful degradation when tools unavailable
+3. **Comprehensive testing**: Multiple Debian versions and environments
+4. **Upstream independence**: Build Debian-specific features without upstream dependencies
+5. **Maintenance planning**: Regular subtree pulls to stay current with upstream fixes
+
+## Next Steps
+
+1. **Immediate**: Set up deb-bootupd directory structure
+2. **Week 1**: Adapt package system integration
+3. **Week 2**: Fix hardcoded paths and dependencies
+4. **Week 3**: Basic testing and validation
+5. **Week 4**: Particle-OS integration testing
+
+## Resources & References
+
+- **Original bootupd**: `.Red_Hat_Version/bootupd/`
+- **Debian packaging**: https://www.debian.org/doc/manuals/debmake-doc/
+- **FHS standards**: https://refspecs.linuxfoundation.org/FHS_3.0/fhs/
+- **Debian bootc tools**: `debian-bootc-image-builder/`