particle-os/deb-bootc-image-builder-new

Fork 0

robojerk 7584207f76 first commit

2025-09-05 07:10:12 -07:00

9.4 KiB

Raw Blame History

GitHub Issue: Add Debian/APT Support to OSBuild

Title

Feature Request: Add Debian/APT package management support to OSBuild

Labels

enhancement
debian
apt
package-management
cross-distro

Description

Summary

OSBuild currently lacks support for Debian/APT package management, limiting its usefulness for Debian-based distributions and container image building. This issue requests the addition of org.osbuild.apt stage and related infrastructure to support Debian package management.

Background

While working on a Debian version of bootc-image-builder, we discovered that OSBuild's manifest generation works correctly, but the actual execution fails because there's no org.osbuild.apt stage to handle APT package installation.

Current Behavior

When attempting to use OSBuild with a manifest containing APT packages:

{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "grub-efi-amd64", "systemd"]
          }
        }
      ]
    }
  ]
}

OSBuild fails with:

./output/manifest.json has errors:
.pipelines[0].stages[0]:
  could not find schema information for 'org.osbuild.apt'

Expected Behavior

OSBuild should support APT package management similar to how it supports RPM/DNF:

{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "grub-efi-amd64", "systemd"],
            "repositories": [
              {
                "name": "debian",
                "url": "http://deb.debian.org/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ],
            "keys": ["/etc/apt/trusted.gpg.d/debian-archive-keyring.gpg"]
          }
        }
      ]
    }
  ]
}

Use Cases

1. Debian Container Image Building

{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["bootc", "apt-ostree", "systemd"],
            "repositories": [
              {
                "name": "debian-forge",
                "url": "https://git.raines.xyz/api/packages/particle-os/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ]
          }
        }
      ]
    }
  ]
}

2. Ubuntu Image Building

{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["ubuntu-minimal", "cloud-init"],
            "repositories": [
              {
                "name": "ubuntu",
                "url": "http://archive.ubuntu.com/ubuntu",
                "suite": "jammy",
                "components": ["main", "restricted"]
              }
            ]
          }
        }
      ]
    }
  ]
}

3. Cross-Architecture Building

{
  "pipelines": [
    {
      "stages": [
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-arm64", "grub-efi-arm64"],
            "architecture": "arm64",
            "repositories": [
              {
                "name": "debian",
                "url": "http://deb.debian.org/debian",
                "suite": "trixie",
                "components": ["main"]
              }
            ]
          }
        }
      ]
    }
  ]
}

Technical Requirements

1. Core APT Stage (`org.osbuild.apt`)

Package installation via apt-get install
Dependency resolution using APT's solver
Repository management via sources.list and sources.list.d/
GPG key handling for repository authentication
Architecture support (amd64, arm64, etc.)
Suite/component support (main, contrib, non-free)

2. Repository Configuration

type APTRepository struct {
    Name       string   `json:"name"`
    URL        string   `json:"url"`
    Suite      string   `json:"suite"`
    Components []string `json:"components"`
    SignedBy   string   `json:"signed_by,omitempty"`
    Insecure   bool     `json:"insecure,omitempty"`
}

3. Package Options

type APTOptions struct {
    Packages     []string        `json:"packages"`
    Repositories []APTRepository `json:"repositories,omitempty"`
    Keys         []string        `json:"keys,omitempty"`
    Architecture string          `json:"architecture,omitempty"`
    Update       bool            `json:"update,omitempty"`
    Upgrade      bool            `json:"upgrade,omitempty"`
    Clean        bool            `json:"clean,omitempty"`
}

4. Implementation Details

Chroot environment for package installation
APT configuration generation (apt.conf, sources.list)
GPG key management for repository authentication
Cross-architecture support via dpkg --add-architecture
Error handling for package conflicts and missing dependencies

Comparison with Existing Stages

Feature	`org.osbuild.rpm`	`org.osbuild.dnf`	`org.osbuild.apt` (proposed)
Package Format	RPM	RPM	DEB
Package Manager	rpm	dnf	apt
Repository Config	YUM repos	DNF repos	sources.list
Key Management	RPM-GPG	RPM-GPG	GPG
Architecture	x86_64, aarch64	x86_64, aarch64	amd64, arm64, etc.
Dependency Resolution	YUM/DNF	DNF	APT

Implementation Approach

Phase 1: Basic APT Support

Create org.osbuild.apt stage
Implement package installation
Add repository configuration
Handle basic dependencies

Phase 2: Advanced Features

GPG key management
Cross-architecture support
Custom APT configuration
Package pinning

Phase 3: Integration

Debian-specific image types
Ubuntu support
Container image building
Cloud image generation

Code Structure

osbuild/
├── stages/
│   ├── apt/
│   │   ├── apt.go              # Main APT stage implementation
│   │   ├── repository.go       # Repository management
│   │   ├── package.go          # Package installation
│   │   └── key.go              # GPG key handling
│   └── ...
├── schemas/
│   └── apt.json                # JSON schema for APT stage
└── ...

Testing Requirements

Unit Tests

Package installation
Repository configuration
Dependency resolution
Error handling

Integration Tests

Debian Trixie image building
Ubuntu Jammy image building
Cross-architecture builds
Container image generation

Test Cases

# Test basic package installation
osbuild --output-dir ./output ./test-manifests/debian-basic.json

# Test with custom repositories
osbuild --output-dir ./output ./test-manifests/debian-custom-repo.json

# Test cross-architecture
osbuild --output-dir ./output ./test-manifests/debian-arm64.json

Documentation Requirements

1. Stage Documentation

APT stage reference
Configuration options
Examples and use cases

2. Tutorials

Building Debian images
Ubuntu image creation
Container image building

3. Migration Guide

From custom scripts to OSBuild
From RPM-based to APT-based workflows

#1234: Add Ubuntu support
#5678: Cross-architecture building
#9012: Container image building

Additional Context

Current Workaround

We're currently bypassing OSBuild and using direct Debian tools:

# Current approach
debootstrap trixie /mnt/debian http://deb.debian.org/debian
chroot /mnt/debian apt-get install -y bootc

Benefits of OSBuild Integration

Standardized approach - consistent with RPM-based workflows
Pipeline support - complex multi-stage builds
Error handling - robust error reporting and recovery
Caching - package download and installation caching
Reproducibility - deterministic builds

Community Impact

Debian users can use OSBuild for image building
Ubuntu users benefit from standardized tooling
Container developers get better Debian support
CI/CD pipelines can use OSBuild for Debian images

Acceptance Criteria

org.osbuild.apt stage implemented
Basic package installation working
Repository configuration supported
GPG key management implemented
Cross-architecture support added
Unit tests passing
Integration tests passing
Documentation updated
Example manifests provided

Priority

High - This is a significant gap in OSBuild's cross-distribution support and limits adoption in Debian/Ubuntu ecosystems.

Estimated Effort

Phase 1: 2-3 weeks
Phase 2: 2-3 weeks
Phase 3: 2-3 weeks
Total: 6-9 weeks

References

Note: This issue was created based on real-world experience building a Debian version of bootc-image-builder. The lack of APT support in OSBuild significantly impacts the ability to create Debian-based container images and limits OSBuild's adoption in Debian/Ubuntu ecosystems.

9.4 KiB Raw Blame History