deb-osbuild/README.md

particle-os

A Debian-based fork of ublue-os that provides osbuild backend support for Debian ecosystems. This project adapts the Red Hat osbuild system to work seamlessly with Debian-based distributions, replacing RPM/DNF components with APT/DPKG equivalents.

Project Overview

particle-os is designed to provide a robust, pipeline-based image building solution for Debian ecosystems, enabling the creation of reproducible, customized operating system images through declarative manifests.

Key Features

• Debian Package Management: Full APT/DPKG integration
• OSTree Support: Native OSTree repository management
• Bootc Integration: Modern bootloader management with bootc
• Multi-Architecture: Support for amd64, arm64, and other Debian architectures
• Pipeline-Based: Declarative manifest system for reproducible builds
• Container Support: Docker and OCI image creation
• Cloud Integration: AWS, GCP, Azure image support

Architecture

particle-os CLI → Manifest Parser → Pipeline Builder → Stage Executor → Object Store → Assembler → Final Artifact
     ↓              ↓                ↓               ↓            ↓          ↓         ↓
  Main Entry   JSON Schema    Dependency Graph   Stage Runner   Cache      Output Gen  Image/Archive

Quick Start

Prerequisites

# Install required packages
sudo apt update
sudo apt install -y python3 python3-pip python3-venv git

# Install built packages (from debs/ directory)
sudo dpkg -i debs/*.deb
sudo apt-get install -f  # Fix any dependency issues

Basic Usage

# Create a simple Debian system image
particle-os manifest.json

# Build with custom options
particle-os --cache .cache --output-dir ./outputs manifest.json

Example Manifest

{
  "version": "2",
  "pipelines": [
    {
      "name": "build",
      "runner": "org.osbuild.linux",
      "stages": [
        {
          "name": "org.osbuild.debian.debootstrap",
          "options": {
            "suite": "trixie",
            "mirror": "https://deb.debian.org/debian",
            "variant": "minbase"
          }
        },
        {
          "name": "org.osbuild.debian.apt",
          "options": {
            "packages": ["sudo", "openssh-server", "systemd-sysv"]
          }
        }
      ]
    }
  ],
  "assembler": {
    "name": "org.osbuild.qemu",
    "options": {
      "format": "qcow2",
      "filename": "particle-os.qcow2",
      "size": "10G"
    }
  }
}

Project Structure

particle-os/
├── README.md                 # This file
├── roadmap.md               # Development roadmap
├── progress.md              # Current progress tracking
├── debs/                    # Built Debian packages
├── .Red_Hat_Version/       # Original Red Hat source (read-only)
├── src/                     # Debian-adapted source code
│   ├── osbuild/            # Core osbuild implementation
│   ├── stages/             # Debian-specific stages
│   ├── assemblers/         # Output format handlers
│   └── schemas/            # JSON schemas for validation
├── examples/                # Example manifests and configurations
├── tests/                   # Test suite
├── docs/                    # Documentation
└── scripts/                 # Build and utility scripts

Development Status

• Package building (bootc, apt-ostree, ostree)
• Project structure setup
• Architecture planning
• Core osbuild adaptation
• Debian stage implementations
• Testing and validation
• Documentation completion

Contributing

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

License

This project is licensed under the Apache License 2.0, same as the original osbuild project.

Related Projects

• osbuild - Original Red Hat build system
• debos - Debian OS image builder
• bootc - Container-native bootloader
• apt-ostree - APT integration for OSTree