# Particle-OS

A Debian-based immutable operating system following the ublue-os pattern, built from the ground up using modern container technologies.

## 🎯 Project Vision

**Create the Debian equivalent of the ublue-os ecosystem:**
- **Debian CoreOS** (immutable server OS using `apt-ostree`)
- **Debian Desktop variants** (immutable desktop OS using `apt-ostree`)
- **Complete bootc integration** for Debian systems
- **Modern immutable workflow** following established best practices

## 🚀 Quick Start

### Prerequisites

- **Podman** - Container runtime
- **Just** - Command runner (install with `cargo install just`)

### Build Your First Image

```bash
# Validate prerequisites
just validate-prereqs

# Build the minimal bootable image (Phase 1 goal)
just build-minimal

# Test the image
just test-image
```

### One-Command Setup

```bash
# Complete quick start (build + test)
just quick-start
```

## 🛠️ Available Commands

### Image Building
- `just build-image` - Build base Debian bootc image
- `just build-minimal` - Build minimal bootable image (Phase 1)
- `just build-server` - Build server-focused image (Phase 2)
- `just build-desktop` - Build desktop variant (Phase 3)

### Testing & Validation
- `just test-image` - Test built image in VM
- `just test-bootupd` - Test deb-bootupd functionality
- `just test-ostree` - Test apt-ostree functionality

### Utility Commands
- `just clean` - Clean up build artifacts
- `just status` - Show current build status
- `just help` - Show help message

## 🏗️ Architecture

### Base Image Strategy
```
debian:trixie-slim → bootc image → bootable OS
```

### Technology Stack
- **Base:** `debian:trixie-slim`
- **Immutable Layer:** `apt-ostree` (your project)
- **Bootloader Management:** `deb-bootupd` (your project)
- **Container Integration:** `bootc`
- **Image Building:** `bootc-image-builder`

### Key Differences from ublue-os
- **Base:** Debian instead of Fedora
- **Package System:** APT/DPKG instead of RPM
- **OSTree:** `apt-ostree` instead of `rpm-ostree`
- **Bootloader:** `deb-bootupd` instead of `bootupd`

## 🔗 Related Projects

This project is part of a larger ecosystem of Debian immutable technologies. The following projects work together to create the complete Debian immutable experience:

### Core Technologies
- **[apt-ostree](https://git.raines.xyz/robojerk/apt-ostree)** - Debian equivalent to `rpm-ostree`
  - Provides immutable package management for Debian systems
  - Handles system updates and rollbacks
  - Core dependency for Particle-OS

- **[deb-bootupd](https://git.raines.xyz/robojerk/deb-bootupd)** - Debian equivalent to `bootupd`
  - Manages bootloader updates and configuration
  - Handles UEFI boot entries
  - Critical for system deployment and updates

- **[bootc-image-builder](https://git.raines.xyz/robojerk/bootc-image-builder)** Debian fork of bootc-image-builder

### Build Tools
- **[bootc-image-builder](https://git.raines.xyz/robojerk/bootc-image-builder)** - Comprehensive Debian-adapted bootc image builder
  - **Not just a fork** - Complete osbuild module development project
  - Adapts Debian's mutable toolchain (apt/dpkg) to immutable paradigm (OSTree)
  - Provides Debian-specific osbuild stages for creating bootable images
  - Includes EFI support, bootloader management, and OSTree integration
  - **Critical for Particle-OS**: Handles the complex build process we need

### Integration
These projects are designed to work together seamlessly:
1. **apt-ostree** provides the immutable base system
2. **deb-bootupd** manages the bootloader and deployment
3. **debian-bootc-corrected** builds the container images
4. **Particle-OS** combines everything into a complete operating system

For more information about these projects, visit their respective repositories or check the [Integration Guide](INTEGRATION_GUIDE.md).

## 📋 Development Phases

### Phase 1: Foundation & Core Technologies 🔄 **IN PROGRESS**
- **Goal:** Establish foundational Debian immutable technologies
- **Deliverable:** Working Debian bootc image
- **Status:** Building minimal bootable image

### Phase 2: Debian CoreOS Foundation 📋 **PLANNED**
- **Goal:** Create minimal, server-focused Debian immutable OS
- **Deliverable:** Debian CoreOS equivalent

### Phase 3: Desktop Variants 📋 **PLANNED**
- **Goal:** Create specialized desktop images
- **Deliverable:** Debian Aurora/Bazzite/Bluefin equivalents

### Phase 4: Distribution & Ecosystem 📋 **PLANNED**
- **Goal:** Establish complete Debian immutable ecosystem
- **Deliverable:** Distributable OS images

## 🔧 Current Focus

**Immediate Priority:** Complete Phase 1 by testing `deb-bootupd` and creating the first minimal bootable image.

**Next Steps:**
1. Test `deb-bootupd` in particle-os VM
2. Build minimal `debian:trixie-slim` → bootc image
3. Validate boot process and OSTree functionality
4. Document the process for future phases

## 📚 Documentation

- [Roadmap](roadmap.md) - Detailed development plan
- [Terminology](terminology.md) - Key concepts and definitions
- [Archive](.archive/) - Previous project approaches and research

## 🤝 Contributing

This project is building the first Debian immutable ecosystem from the ground up. Contributions are welcome as we establish the foundation and build upon it.

## 📄 License

[Add your license here]

---

**Particle-OS** - Building the future of Debian, one immutable layer at a time.