particle-os/INTEGRATION_GUIDE.md

particle-os + debian-bootc-image-builder Integration Guide

🎯 Integration Overview

This guide documents the integration between the particle-os project (Phase 1 complete) and the debian-bootc-image-builder project (Phase 4.2 complete with 100% test coverage).

✅ Current Status

• particle-os: ✅ Phase 1 complete - Valid bootc container image ready
• debian-bootc-image-builder: ✅ Phase 4.2 complete - Professional deployment infrastructure
• Integration: 🔄 Ready to test and validate

📍 Project Locations

particle-os (This Project)

# Location: /home/rob/Documents/Projects/particle-os
# Key Files:
# - 01-debian-atomic/Containerfile  # Creates the bootc container
# - 01-debian-atomic/justfile       # Build automation
# - WORKING_COMMANDS.md             # All validated commands

debian-bootc-image-builder

# Location: joe@particle-os:~/bootc-image-builder/debian-bootc-image-builder
# Status: Advanced project with osbuild stages, Go integration, QCOW2 generation
# Features: Multiple output formats, performance optimization, comprehensive testing

🚀 Integration Testing Steps

Step 1: Access debian-bootc-image-builder

# Method 1: SSH to VM (if accessible)
ssh joe@particle-os
cd ~/bootc-image-builder/debian-bootc-image-builder

# Method 2: Clone locally (if Git repository)
# git clone <repository-url> ~/Documents/Projects/debian-bootc-image-builder

Step 2: Verify particle-os Image

# In particle-os directory
cd /path/to/particle-os/01-debian-atomic

# Build and validate the image
just build-image
just validate-image

# Verify image is ready
podman images localhost/debian-atomic:latest

Step 3: Test Integration

# In debian-bootc-image-builder directory
cd ~/bootc-image-builder/debian-bootc-image-builder

# Test the integration (command to be validated)
./bootc-image-builder --type qcow2 localhost/debian-atomic:latest

# Alternative syntax (if different)
./debian-bootc-image-builder --type qcow2 localhost/debian-atomic:latest

Step 4: Generate Bootable Artifacts

# Generate QCOW2 image for VM testing
./bootc-image-builder --type qcow2 --output ./output/ localhost/debian-atomic:latest

# Generate ISO for installation media
./bootc-image-builder --type iso --output ./output/ localhost/debian-atomic:latest

# Generate RAW image for physical deployment
./bootc-image-builder --type raw --output ./output/ localhost/debian-atomic:latest

Step 5: Test Generated Artifacts

# Test QCOW2 in QEMU
qemu-system-x86_64 -m 4G -enable-kvm -drive file=output/particle-os.qcow2,format=qcow2

# Verify ISO structure
file output/particle-os.iso
isoinfo -l -i output/particle-os.iso

🔧 Expected Integration Points

particle-os Provides:

• ✅ Valid bootc Container: Passes bootc container lint
• ✅ Complete Disk Utilities: sfdisk, parted, mkfs.ext4, etc.
• ✅ Kernel Integration: Linux kernel properly placed and accessible
• ✅ OSTree Structure: Proper atomic filesystem layout
• ✅ Environment Setup: Locale, PATH, critical environment variables

debian-bootc-image-builder Provides:

• ✅ osbuild Stages: APT, Filesystem, Kernel, GRUB stages
• ✅ Go Integration: Professional Go codebase with full testing
• ✅ Multiple Formats: QCOW2, ISO, RAW artifact generation
• ✅ Performance Optimization: 25-30% faster execution, memory optimized
• ✅ Professional Infrastructure: 100% test coverage, CI/CD ready

📋 Integration Validation Checklist

Pre-Integration ✅

• particle-os image builds successfully
• particle-os image passes bootc container lint
• debian-bootc-image-builder located and accessible
• Integration plan documented

Integration Testing

• debian-bootc-image-builder recognizes particle-os image
• QCOW2 generation completes successfully
• Generated QCOW2 boots in VM
• ISO generation works (if needed)
• Performance meets expectations

Post-Integration

• Document successful workflow
• Update particle-os documentation
• Create automated pipeline
• Plan CI/CD integration

🚨 Troubleshooting Guide

If Image Not Recognized

# Verify image labels
podman inspect localhost/debian-atomic:latest | grep -A 10 -B 10 ostree

# Check image is properly tagged
podman images | grep debian-atomic

# Ensure image is available to debian-bootc-image-builder
podman load -i debian-atomic.tar  # if needed

If Build Fails

# Check debian-bootc-image-builder logs
./bootc-image-builder --type qcow2 --verbose localhost/debian-atomic:latest

# Verify osbuild stages
./test_debian_integration.py  # if available

# Check system requirements
df -h  # disk space
free -h  # memory

If Performance Issues

# Use performance optimization
./scripts/performance_optimization.py  # if available

# Monitor resource usage
htop  # during build process

📊 Expected Results

Successful Integration Should Produce:

• QCOW2 Image: ~2-4GB bootable VM image
• Boot Time: < 30 seconds to desktop
• Functionality: Full atomic OS with update capabilities
• Performance: Optimized for production use

Performance Targets:

• Build Time: < 10 minutes for QCOW2 generation
• Memory Usage: < 2GB during build
• Disk Usage: < 10GB temporary space
• Output Size: Optimized image sizes

🎯 Success Criteria

Integration is successful when:

1. ✅ debian-bootc-image-builder successfully processes particle-os image
2. ✅ Generated QCOW2 boots and runs properly in VM
3. ✅ Atomic updates work correctly in deployed system
4. ✅ Performance meets or exceeds expectations
5. ✅ Workflow is documented and reproducible

📝 Next Steps After Integration

1. Document Workflow: Update README.md with integration steps
2. Automate Pipeline: Create scripts for particle-os → debian-bootc-image-builder
3. CI/CD Integration: Set up automated artifact generation
4. Performance Tuning: Optimize the integrated workflow
5. Multi-Format Support: Test ISO, RAW, and other output formats

---

Status: Ready for integration testing Priority: HIGH - This integration provides the missing deployment piece for particle-os Impact: Transforms particle-os from development project to production-ready solution