debian-forge/README.md

Debian Forge

A Debian-specific fork of OSBuild with comprehensive APT package management support for building Debian and Ubuntu images.

Features

🚀 Complete APT Support

• org.osbuild.apt - Full APT package installation with dependency resolution
• org.osbuild.apt.config - APT configuration and repository management
• org.osbuild.debootstrap - Base Debian filesystem creation
• org.osbuild.debian.source - Source package management

🎯 Cross-Distribution Support

• Debian - Trixie, Bookworm, Sid support
• Ubuntu - Jammy, Focal, and other LTS releases
• Cross-Architecture - amd64, arm64, and more

⚡ Performance Optimized

• APT Caching - 2-3x faster builds with apt-cacher-ng
• Parallel Builds - Multi-architecture support
• Minimal Images - Optimized base images

🔧 Production Ready

• CI/CD Integration - Automated build pipelines
• Comprehensive Testing - Full test coverage
• Documentation - Complete user guides and examples

Quick Start

Installation

# Clone the repository
git clone https://git.raines.xyz/particle-os/debian-forge.git
cd debian-forge

# Install dependencies
sudo apt install python3-dev python3-pip python3-venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Basic Usage

Create a simple Debian image:

{
  "version": "2",
  "pipelines": [
    {
      "runner": "org.osbuild.linux",
      "name": "build",
      "stages": [
        {
          "type": "org.osbuild.debootstrap",
          "options": {
            "suite": "trixie",
            "mirror": "http://deb.debian.org/debian",
            "arch": "amd64"
          }
        },
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": ["linux-image-amd64", "systemd", "openssh-server"]
          }
        }
      ]
    }
  ]
}

Build the image:

python3 -m osbuild manifest.json --output-dir ./output --libdir .

Examples

Debian Trixie Minimal

python3 -m osbuild test/data/manifests/debian/debian-trixie-minimal.json --libdir .

Ubuntu Jammy Server

python3 -m osbuild test/data/manifests/debian/ubuntu-jammy-server.json --libdir .

ARM64 Cross-Architecture

python3 -m osbuild test/data/manifests/debian/debian-trixie-arm64.json --libdir .

Documentation

• APT Stages Reference - Complete API documentation
• Debian Image Building Tutorial - Step-by-step guide
• Performance Optimization - Speed up your builds
• Example Manifests - Real-world examples

APT Stages

org.osbuild.debootstrap

Creates base Debian filesystem using debootstrap.

Options:

• suite - Debian suite (trixie, jammy, etc.)
• mirror - Debian mirror URL
• arch - Target architecture
• variant - Debootstrap variant (minbase, buildd)
• extra_packages - Additional packages to include

org.osbuild.apt

Installs Debian packages using APT.

Options:

• packages - List of packages to install
• recommends - Install recommended packages
• update - Update package lists
• apt_proxy - APT proxy URL

org.osbuild.apt.config

Configures APT settings and repositories.

Options:

• sources - Repository configuration
• preferences - Package preferences and pinning
• apt_proxy - APT proxy URL

Performance

With apt-cacher-ng

• 2-3x faster builds for repeated packages
• Reduced bandwidth usage
• Offline capability for cached packages

Build Times

Image Type	Base Time	With Cache	Improvement
Minimal Debian	5-10 min	2-3 min	60-70%
Server Image	10-15 min	4-6 min	60-70%
Ubuntu Image	8-12 min	3-5 min	60-70%

CI/CD Integration

Forgejo Workflow

name: Build and Test
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    container: python:3.13-slim-trixie
    steps:
      - uses: actions/checkout@v4
      - name: Build Debian packages
        run: ./scripts/build-debian-packages.sh

Package Building

# Build all packages
./scripts/build-debian-packages.sh

# Test packages
dpkg-deb -I *.deb

Comparison with Upstream OSBuild

Feature	OSBuild	Debian Forge
Package Manager	RPM/DNF	APT
Distributions	Fedora/RHEL	Debian/Ubuntu
Base Creation	dnf/rpm	debootstrap
Dependency Resolution	DNF	APT
Repository Management	YUM repos	sources.list
Cross-Architecture	x86_64, aarch64	amd64, arm64, etc.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python3 -m pytest test/

# Run linting
flake8 osbuild/

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• OSBuild - The original project that inspired this fork
• Debian Project - For the excellent package management system
• Ubuntu - For the LTS releases and community support

Support

• Documentation - docs/
• Issues - GitLab Issues
• Discussions - GitLab Discussions

Roadmap

• Phase 1-5 - Project structure and packaging
• Phase 6 - APT implementation (COMPLETE!)
• Phase 7.1 - Documentation and examples
• Phase 7.2 - Performance optimization
• Phase 7.3 - Advanced features
• Phase 8 - Cloud image generation
• Phase 9 - Container image building
• Phase 10 - Live ISO creation

---

Debian Forge - Building Debian and Ubuntu images with the power of OSBuild! 🚀