particle-os-modules/DEBIAN_README.md

# Debian Modules for Blue-Build

This document provides comprehensive information about the Debian modules available in blue-build, which offer 1:1 compatibility with the original Fedora modules while providing full Debian support.

## Overview

The Debian modules are designed to maintain the exact same file structure and user experience as the original blue-build system, ensuring that users familiar with the Fedora version will intuitively understand how to use the Debian implementation.

## Supported Debian Versions

- **Debian 13 (Trixie)** - Current stable release
- **Debian 14 (Forky)** - Testing release
- **Debian Sid** - Unstable release

## Available Modules

### 1. apt Module

The `apt` module replaces the `dnf` module and provides Debian package management capabilities.

#### Features
- Package installation and removal
- Repository management (PPA, backports, custom)
- GPG key management
- Task-based package groups (replaces RPM groups)
- .deb package file support
- Repository cleanup options

#### Example Usage
```yaml
- type: apt
  repos:
    cleanup: true
    backports: true
    ppa:
      - ppa:ondrej/php
    keys:
      - https://example.com/gpg.key
  install:
    skip-unavailable: true
    packages:
      - nginx
      - postgresql
      - php8.2
  task-install:
    with-optional: true
    packages:
      - gnome-desktop-environment
  remove:
    packages:
      - nano
      - less
```

#### Key Differences from dnf
- **COPR → PPA**: Use `ppa:` instead of `copr:`
- **RPM Groups → Debian Tasks**: Use `task-install` instead of `group-install`
- **RPM Fusion → Backports**: Enable `backports: true` for additional packages
- **Package Files**: Supports `.deb` files instead of `.rpm`

### 2. apt-ostree Module

The `apt-ostree` module replaces the `rpm-ostree` module and provides Debian package layering with ostree.

#### Features
- Package layering using ostree
- Repository and key management
- Package replacement and removal
- Automatic ostree commits
- Fallback to regular apt when ostree operations fail

#### Example Usage
```yaml
- type: apt-ostree
  repos:
    - https://example.com/repo.list
  keys:
    - https://example.com/gpg.key
  install:
    - starship
    - brave-browser
  remove:
    - firefox
  replace:
    - from-repo: https://example.com/repo
      packages:
        - php8.2
        - php8.2-common
```

#### Key Differences from rpm-ostree
- Uses Debian package database format
- Integrates with `apt-ostree` tool
- Debian-specific package layering

### 3. deb-mock Module

The `deb-mock` module replaces the `mock` module and provides Debian build environment management.

#### Features
- Build environment setup (pbuilder, sbuild, schroot)
- Build dependency management
- Custom repository configuration
- Build script execution
- Artifact collection

#### Example Usage
```yaml
- type: deb-mock
  environment: bookworm-amd64
  packages:
    - build-essential
    - devscripts
    - debhelper
  repositories:
    - deb http://deb.debian.org/debian bookworm main
    - deb http://deb.debian.org/debian bookworm-backports main
  build-script: |
    #!/bin/bash
    set -e
    dpkg-buildpackage -b -us -uc
  artifacts:
    - ../*.deb
    - ../*.dsc
    - ../*.tar.gz
```

#### Key Differences from mock
- **Chroot → Environment**: Use `environment` instead of `chroot`
- **Builddeps → Packages**: Use `packages` for build dependencies
- **Resultdir → Artifacts**: Use `artifacts` for output files

## Migration Guide

### Converting from Fedora to Debian

#### 1. Update Module Types
```yaml
# Before (Fedora)
- type: dnf
- type: rpm-ostree
- type: mock

# After (Debian)
- type: apt
- type: apt-ostree
- type: deb-mock
```

#### 2. Convert Repositories
```yaml
# Before (Fedora)
repos:
  copr:
    - atim/starship
  nonfree: rpmfusion

# After (Debian)
repos:
  ppa:
    - ppa:atim/starship
  backports: true
```

#### 3. Convert Package Groups
```yaml
# Before (Fedora)
group-install:
  packages:
    - development-tools

# After (Debian)
task-install:
  packages:
    - development-tools
```

#### 4. Convert Package Specifications
```yaml
# Before (Fedora)
install:
  packages:
    - https://example.com/package.rpm

# After (Debian)
install:
  packages:
    - https://example.com/package.deb
```

## Compatibility Layer

The system includes a compatibility layer that automatically converts Fedora module configurations to Debian equivalents:

### Automatic Conversions
- **Module Types**: `dnf` → `apt`, `rpm-ostree` → `apt-ostree`, `mock` → `deb-mock`
- **Repositories**: `copr:` → `ppa:`, `rpmfusion` → `backports`
- **Package Groups**: `group-install` → `task-install`
- **Package Names**: Common package name mappings (e.g., `gcc-c++` → `g++`)

### Usage
```python
from debian_module_adapter import DebianModuleAdapter

adapter = DebianModuleAdapter()
adapted_config = adapter.adapt_module_config(original_config)
result = adapter.execute_module(adapted_config)
```

## Example Recipes

### Basic Debian Server
See `examples/debian-basic/debian-server.yml` for a complete server setup example.

### GNOME Desktop
See `examples/debian-gnome/debian-gnome.yml` for a GNOME desktop environment.

### KDE Desktop
See `examples/debian-kde/debian-kde.yml` for a KDE Plasma desktop environment.

## Testing

### Module Testing
```bash
# Test apt module
cd blue-build-modules/modules/apt
docker build -t apt-module .
docker run --rm -e BLUEBUILD_MODULE_CONFIG='{"type":"apt","install":{"packages":["curl"]}}' apt-module

# Test apt-ostree module
cd blue-build-modules/modules/apt-ostree
docker build -t apt-ostree-module .
docker run --rm -e BLUEBUILD_MODULE_CONFIG='{"type":"apt-ostree","install":["curl"]}' apt-ostree-module

# Test deb-mock module
cd blue-build-modules/modules/deb-mock
docker build -t deb-mock-module .
docker run --rm -e BLUEBUILD_MODULE_CONFIG='{"type":"deb-mock","environment":"bookworm-amd64"}' deb-mock-module
```

### Integration Testing
```bash
# Test with blue-build-cli
blue-build build examples/debian-basic/debian-server.yml

# Test with existing Debian tools
python3 debian_module_adapter.py
python3 debian_package_converter.py
```

## Troubleshooting

### Common Issues

#### 1. Package Not Found
- Ensure the package name is correct for Debian
- Check if the package is available in the specified repositories
- Use `apt-cache search <package>` to find package names

#### 2. Repository Issues
- Verify GPG keys are correctly imported
- Check repository URLs are accessible
- Ensure repository format is correct for Debian

#### 3. Build Environment Issues
- Verify build dependencies are installed
- Check if the target architecture is supported
- Ensure sufficient disk space for build artifacts

### Debug Mode
Enable debug logging by setting the `DEBUG` environment variable:
```bash
export DEBUG=1
blue-build build recipe.yml
```

## Contributing

### Adding New Package Mappings
Edit `debian_package_converter.py` to add new package name mappings:
```python
self.package_mappings.update({
    "new-rpm-package": "new-debian-package",
    "another-rpm-pkg": "another-debian-pkg"
})
```

### Adding New Repository Mappings
Edit `debian_package_converter.py` to add new repository mappings:
```python
self.repo_mappings.update({
    "new-rpm-repo": "new-debian-repo"
})
```

### Testing Changes
1. Make your changes
2. Run the test suite
3. Test with real Debian images
4. Submit a pull request

## Support

### Documentation
- [Blue-Build Documentation](https://blue-build.org/)
- [Debian Package Management](https://wiki.debian.org/PackageManagement)
- [Debian Tasks](https://wiki.debian.org/tasksel)

### Community
- [Blue-Build Community](https://github.com/blue-build)
- [Debian Community](https://www.debian.org/support)

### Issues
Report issues and feature requests through the project's issue tracker.

## License

This project is licensed under the same terms as the original blue-build project.