debian-atomic-config/docs/INTEGRATION-GUIDE.md

# 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.*