# 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)
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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 ✅
- [x] particle-os image builds successfully
- [x] particle-os image passes bootc container lint
- [x] debian-bootc-image-builder located and accessible
- [x] 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
```bash
# 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
```bash
# 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
```bash
# 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
