Add mmdebstrap support. Moved docs into docs

docs/INTEGRATION-GUIDE.md

@@ -0,0 +1,384 @@
+# Debian Atomic Integration Guide
+
+## Overview
+
+This guide explains how to integrate the alternative Debian Atomic solution with the broader Debian Forge ecosystem. The alternative solution bypasses `apt-ostree` limitations by using `debootstrap` + `ostree` directly.
+
+## Architecture
+
+```
+debian-atomic-configs/
+├── create-debian-atomic.py    # Core build script
+├── test-all-variants.py       # Comprehensive testing
+├── variants/                  # Variant definitions
+├── treefiles/                 # Treefile configurations
+└── INTEGRATION-GUIDE.md       # This file
+```
+
+## Quick Start
+
+### 1. Build a Minimal Variant
+
+```bash
+# Build minimal Debian Atomic system
+sudo python3 create-debian-atomic.py minimal
+
+# Build with custom work directory
+sudo python3 create-debian-atomic.py minimal /path/to/work/dir
+```
+
+### 2. Test All Variants
+
+```bash
+# Test all variants and generate report
+sudo python3 test-all-variants.py
+
+# Keep test artifacts for inspection
+sudo python3 test-all-variants.py --keep
+```
+
+### 3. Available Variants
+
+- **minimal**: Base system (Fedora CoreOS equivalent)
+- **gnome**: GNOME desktop environment
+- **plasma**: KDE Plasma desktop environment
+- **cosmic**: Pop!_OS desktop environment
+- **sway**: Sway Wayland compositor
+- **budgie**: Budgie desktop environment
+
+## Integration Points
+
+### 1. With deb-bootc-image-builder
+
+The alternative solution generates OSTree repositories that can be consumed by `deb-bootc-image-builder`:
+
+```bash
+# Build Debian Atomic variant
+sudo python3 create-debian-atomic.py minimal /tmp/debian-atomic
+
+# Use with deb-bootc-image-builder
+deb-bootc-image-builder \
+  --ostree-repo /tmp/debian-atomic/minimal/repo \
+  --ostree-ref debian/14/x86_64/minimal \
+  --output minimal-debian-atomic.qcow2
+```
+
+### 2. With debian-forge
+
+The generated OSTree repositories can be used as base images in `debian-forge`:
+
+```yaml
+# debian-forge blueprint
+name = "debian-atomic-base"
+description = "Debian Atomic base system"
+version = "0.0.1"
+
+[[packages]]
+name = "debian-atomic-minimal"
+version = "*"
+
+[[customizations.ostree]]
+ref = "debian/14/x86_64/minimal"
+```
+
+### 3. With debian-koji
+
+Build the alternative solution as a package in `debian-koji`:
+
+```bash
+# Package the build script
+cd debian-atomic-configs
+dpkg-buildpackage -us -uc
+
+# Install in koji build environment
+koji build --scratch debian-atomic-configs_*.dsc
+```
+
+## Workflow Integration
+
+### 1. CI/CD Pipeline
+
+```yaml
+# .forgejo/workflows/debian-atomic.yml
+name: Debian Atomic Build
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-variants:
+    runs-on: debian-trixie
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y debootstrap ostree python3-yaml
+      - name: Build all variants
+        run: |
+          sudo python3 create-debian-atomic.py minimal
+          sudo python3 create-debian-atomic.py gnome
+          sudo python3 create-debian-atomic.py plasma
+      - name: Test variants
+        run: sudo python3 test-all-variants.py
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: debian-atomic-variants
+          path: |
+            minimal/repo/
+            gnome/repo/
+            plasma/repo/
+```
+
+### 2. Development Workflow
+
+```bash
+# 1. Make changes to variant definitions
+vim variants/minimal.yaml
+
+# 2. Test individual variant
+sudo python3 create-debian-atomic.py minimal
+
+# 3. Run comprehensive tests
+sudo python3 test-all-variants.py
+
+# 4. Generate bootable image
+deb-bootc-image-builder --ostree-repo minimal/repo --ostree-ref debian/14/x86_64/minimal
+
+# 5. Test bootable image
+qemu-system-x86_64 -enable-kvm -m 2048 -hda minimal-debian-atomic.qcow2
+```
+
+## Customization
+
+### 1. Adding New Variants
+
+```python
+# In create-debian-atomic.py
+elif variant == "custom":
+    return base_packages + [
+        "custom-desktop", "custom-tools",
+        "custom-config", "custom-themes"
+    ]
+```
+
+### 2. Custom Package Lists
+
+```python
+def get_custom_packages(self, variant: str) -> List[str]:
+    """Get custom package list from YAML file"""
+    variant_file = Path(f"variants/{variant}.yaml")
+    if variant_file.exists():
+        with open(variant_file) as f:
+            config = yaml.safe_load(f)
+            return config.get("packages", [])
+    return []
+```
+
+### 3. Post-Processing Hooks
+
+```python
+def post_process_rootfs(self, variant: str) -> bool:
+    """Custom post-processing for variants"""
+    # Run variant-specific scripts
+    script_path = Path(f"scripts/{variant}-post.sh")
+    if script_path.exists():
+        subprocess.run(["chroot", str(self.rootfs_dir), "/bin/bash", str(script_path)])
+    
+    return True
+```
+
+## Monitoring and Debugging
+
+### 1. Build Logs
+
+```bash
+# Enable verbose output
+sudo python3 create-debian-atomic.py minimal 2>&1 | tee build.log
+
+# Check specific stage
+sudo python3 create-debian-atomic.py minimal --debug-stage=debootstrap
+```
+
+### 2. OSTree Repository Inspection
+
+```bash
+# List all references
+ostree refs --repo=/path/to/repo
+
+# Show commit details
+ostree show --repo=/path/to/repo debian/14/x86_64/minimal
+
+# Browse repository contents
+ostree ls --repo=/path/to/repo debian/14/x86_64/minimal
+```
+
+### 3. Rootfs Inspection
+
+```bash
+# Mount rootfs for inspection
+sudo mount --bind /dev /path/to/rootfs/dev
+sudo mount --bind /proc /path/to/rootfs/proc
+sudo mount --bind /sys /path/to/rootfs/sys
+sudo chroot /path/to/rootfs
+
+# Check installed packages
+dpkg -l | grep -E "(systemd|gnome|plasma)"
+
+# Verify services
+systemctl list-unit-files --root=/path/to/rootfs
+```
+
+## Performance Optimization
+
+### 1. Parallel Builds
+
+```python
+# Build multiple variants in parallel
+import concurrent.futures
+
+def build_parallel(variants: List[str]):
+    with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
+        futures = {executor.submit(build_variant, v): v for v in variants}
+        for future in concurrent.futures.as_completed(futures):
+            variant = futures[future]
+            try:
+                result = future.result()
+                print(f"{variant}: {result}")
+            except Exception as e:
+                print(f"{variant}: {e}")
+```
+
+### 2. Caching
+
+```python
+# Cache debootstrap results
+def get_cached_rootfs(self, variant: str) -> Optional[Path]:
+    cache_dir = Path("/var/cache/debian-atomic")
+    cache_file = cache_dir / f"{variant}-rootfs.tar.gz"
+    
+    if cache_file.exists():
+        # Extract cached rootfs
+        return self.extract_cached_rootfs(cache_file)
+    return None
+```
+
+### 3. Incremental Updates
+
+```python
+# Only rebuild changed components
+def needs_rebuild(self, variant: str) -> bool:
+    variant_file = Path(f"variants/{variant}.yaml")
+    repo_path = self.work_dir / variant / "repo"
+    
+    if not repo_path.exists():
+        return True
+    
+    # Check if variant definition changed
+    variant_mtime = variant_file.stat().st_mtime
+    repo_mtime = repo_path.stat().st_mtime
+    
+    return variant_mtime > repo_mtime
+```
+
+## Security Considerations
+
+### 1. Package Verification
+
+```python
+# Verify package signatures
+def verify_packages(self, packages: List[str]) -> bool:
+    for package in packages:
+        if not self.verify_package_signature(package):
+            print(f"Warning: Package {package} signature verification failed")
+            return False
+    return True
+```
+
+### 2. Repository Security
+
+```python
+# Use HTTPS repositories
+def get_secure_repositories(self) -> List[str]:
+    return [
+        "https://deb.debian.org/debian trixie main contrib non-free",
+        "https://deb.debian.org/debian-security trixie-security main contrib non-free"
+    ]
+```
+
+### 3. Build Isolation
+
+```python
+# Isolate build environment
+def create_isolated_build(self):
+    # Use unshare for namespace isolation
+    subprocess.run(["unshare", "--mount", "--uts", "--ipc", "--net", "--pid", "--"])
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Permission Denied**
+   ```bash
+   # Ensure running as root
+   sudo python3 create-debian-atomic.py minimal
+   ```
+
+2. **Package Not Found**
+   ```bash
+   # Check package availability
+   apt-cache search package-name
+   
+   # Update package list
+   sudo apt-get update
+   ```
+
+3. **OSTree Repository Issues**
+   ```bash
+   # Reinitialize repository
+   rm -rf /path/to/repo
+   ostree init --repo=/path/to/repo --mode=bare
+   ```
+
+4. **Disk Space Issues**
+   ```bash
+   # Check available space
+   df -h
+   
+   # Clean up old builds
+   sudo rm -rf /tmp/debian-atomic-*
+   ```
+
+### Debug Mode
+
+```bash
+# Enable debug output
+export DEBIAN_ATOMIC_DEBUG=1
+sudo python3 create-debian-atomic.py minimal
+
+# Check specific component
+sudo python3 create-debian-atomic.py minimal --debug-component=debootstrap
+```
+
+## Next Steps
+
+1. **Extend Variant Support**: Add more desktop environments and server configurations
+2. **Integration Testing**: Test with real hardware and virtual machines
+3. **Performance Benchmarking**: Compare with upstream Fedora Atomic
+4. **Community Adoption**: Share with Debian community for feedback
+5. **Documentation**: Expand user guides and tutorials
+
+## Support
+
+- **Issues**: Report bugs via project issue tracker
+- **Discussions**: Join community discussions
+- **Contributions**: Submit pull requests for improvements
+- **Documentation**: Help improve this guide
+
+---
+
+*This guide covers the integration of the alternative Debian Atomic solution. For more information, see the main project documentation.*