debian-atomic-config/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

# 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

# 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:

# 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:

# 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:

# 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

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

# 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

# In create-debian-atomic.py
elif variant == "custom":
    return base_packages + [
        "custom-desktop", "custom-tools",
        "custom-config", "custom-themes"
    ]

2. Custom Package Lists

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

   # Ensure running as root
   sudo python3 create-debian-atomic.py minimal
   

2. Package Not Found

   # Check package availability
   apt-cache search package-name
   
   # Update package list
   sudo apt-get update
   

3. OSTree Repository Issues

   # Reinitialize repository
   rm -rf /path/to/repo
   ostree init --repo=/path/to/repo --mode=bare
   

4. Disk Space Issues

   # Check available space
   df -h
   
   # Clean up old builds
   sudo rm -rf /tmp/debian-atomic-*
   

Debug Mode

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