debian-forge/docs/debian/debos-osbuild-mapping.md

Debian Forge: debos to OSBuild Stage Mapping

Overview

This document maps debos actions to OSBuild stages to enable Debian package management and OSTree composition in the OSBuild pipeline.

Action Mappings

Package Management

debos: apt → OSBuild: org.osbuild.apt

• Purpose: Install Debian packages using apt
• Input: Package list, repository configuration
• Output: Installed packages in target filesystem
• Dependencies: Repository configuration, package sources

debos: debootstrap → OSBuild: org.osbuild.debootstrap

• Purpose: Create base Debian filesystem
• Input: Debian suite, architecture, mirror
• Output: Base Debian root filesystem
• Dependencies: Network access, Debian mirror

OSTree Integration

debos: ostree-commit → OSBuild: org.osbuild.ostree.commit

• Purpose: Create OSTree commit from filesystem
• Input: Filesystem tree, commit metadata
• Output: OSTree commit in repository
• Dependencies: OSTree repository, filesystem tree

debos: ostree-deploy → OSBuild: org.osbuild.ostree.deploy

• Purpose: Deploy OSTree branch to target
• Input: OSTree repository, branch name
• Output: Deployed OSTree filesystem
• Dependencies: OSTree repository, target device

Filesystem Operations

debos: overlay → OSBuild: org.osbuild.overlay

• Purpose: Copy files/directories to target
• Input: Source files, target paths
• Output: Files copied to target filesystem
• Dependencies: Source files, target filesystem

debos: filesystem-deploy → OSBuild: org.osbuild.filesystem.deploy

• Purpose: Deploy filesystem to image
• Input: Filesystem tree, target image
• Output: Image with deployed filesystem
• Dependencies: Filesystem tree, target device

Image Creation

debos: image-partition → OSBuild: org.osbuild.image.partition

• Purpose: Create and partition disk image
• Input: Partition layout, filesystem types
• Output: Partitioned disk image
• Dependencies: Partition specification

Implementation Priority

Phase 1: Core Package Management

1. org.osbuild.apt - Debian package installation
2. org.osbuild.debootstrap - Base filesystem creation
3. org.osbuild.apt.repos - Repository configuration

Phase 2: OSTree Integration

1. org.osbuild.ostree.commit - Commit creation
2. org.osbuild.ostree.deploy - Deployment
3. org.osbuild.ostree.repo - Repository management

Phase 3: Advanced Features

1. org.osbuild.overlay - File operations
2. org.osbuild.filesystem.deploy - Filesystem deployment
3. org.osbuild.image.partition - Image creation

Stage Structure

Each OSBuild stage should follow the standard pattern:

• Python script for the stage logic
• JSON metadata file defining options and dependencies
• Integration with OSBuild pipeline system
• Proper error handling and logging

Dependencies

• Python 3.6+ for stage execution
• apt/dpkg for Debian package management
• ostree for atomic filesystem management
• debootstrap for base filesystem creation
• sbuild/pbuilder for build environments
• apt-cacher-ng for package caching (optional, improves performance)

apt-cacher-ng Integration

Configuration

Both org.osbuild.apt and org.osbuild.debootstrap stages support apt-cacher-ng proxy configuration:

{
  "name": "org.osbuild.apt",
  "options": {
    "packages": ["systemd", "dbus"],
    "apt_proxy": "http://localhost:3142"
  }
}

Benefits

• Faster builds - Packages are cached locally
• Reduced network usage - Avoids re-downloading packages
• Offline capability - Can build without internet after initial cache
• Development efficiency - Faster iteration during development

Setup

Use the provided setup-apt-cacher.sh script to configure apt-cacher-ng:

sudo ./debian-forge/setup-apt-cacher.sh