# 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

```bash
# 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

```bash
# 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

```json
{
  "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

- [x] Package building (bootc, apt-ostree, ostree)
- [x] Project structure setup
- [x] 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](https://github.com/osbuild/osbuild) - Original Red Hat build system
- [debos](https://github.com/go-debos/debos) - Debian OS image builder
- [bootc](https://github.com/containers/bootc) - Container-native bootloader
- [apt-ostree](https://github.com/robojerk/apt-ostree) - APT integration for OSTree