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

- 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

- 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

- 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

# Before (Fedora)
- type: dnf
- type: rpm-ostree
- type: mock

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

2. Convert Repositories

# Before (Fedora)
repos:
  copr:
    - atim/starship
  nonfree: rpmfusion

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

3. Convert Package Groups

# Before (Fedora)
group-install:
  packages:
    - development-tools

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

4. Convert Package Specifications

# 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

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

# 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

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

export DEBUG=1
blue-build build recipe.yml

Contributing

Adding New Package Mappings

Edit debian_package_converter.py to add new package name mappings:

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:

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
• Debian Package Management
• Debian Tasks

Community

• Blue-Build Community
• Debian Community

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.