# particle-os Process Guide

## Overview

This guide covers the process of using particle-os to create bootable Debian-based operating system images. particle-os is a modified version of bootc-image-builder that includes disk creation capabilities, adapted from the original Fedora tooling to work with Debian systems.

## Debian Atomic Foundation

particle-os builds on [Debian Atomic](https://git.raines.xyz/particle-os/debian-atomic), which provides the immutable OS foundation. Debian Atomic creates container images with:

- OSTree tools and structure
- Unified `/usr` hierarchy
- UEFI boot support
- Pure Debian 13+ (Trixie) base

particle-os uses these Debian Atomic container images as base images for creating bootable disk images. The workflow is:

1. **Debian Atomic** creates immutable container images
2. **particle-os** converts those containers to bootable disk images
3. **Result**: Bootable Debian-based immutable operating system

## Current Status

**particle-os is a working prototype with core functionality operational but incomplete.**

### What Works
- Container extraction and rootfs creation
- Package installation via apt in chroot
- Basic disk image creation with GPT partitioning
- Bootloader installation (extlinux/syslinux)
- YAML recipe parsing and validation
- Multiple output formats (raw, qcow2, vmdk, vdi)

### What's Incomplete
- Some recipe stages fail due to chroot permission issues
- Kernel installation not fully implemented
- Limited error handling and recovery
- Images boot to bootloader but lack full OS boot capability

## Prerequisites

### System Requirements
- Debian 12+ (Bookworm/Trixie) or Ubuntu 22.04+
- Go 1.21+ for building from source
- sudo access for chroot operations
- 10GB+ free disk space
- 4GB+ RAM recommended

### Dependencies
```bash
sudo apt update
sudo apt install golang-go qemu-utils podman
```

## Installation

### Build from Source
```bash
cd deb-bootc-image-builder
cd bib
go build -o particle-os cmd/particle_os/main.go
cd ..
```

### Verify Installation
```bash
./bib/particle-os --version
./bib/particle-os --help
```

## Basic Usage

### List Available Recipes
```bash
./bib/particle-os list
```

### Validate a Recipe
```bash
./bib/particle-os validate recipes/simple-cli-bootable.yml
```

### Build an Image
```bash
sudo ./bib/particle-os build recipes/simple-cli-bootable.yml
```

## Recipe System

### Recipe Structure
Recipes are YAML files that define the build process:

```yaml
name: simple-cli-bootable
description: Generate bootable image from simple-cli container
base-image: git.raines.xyz/robojerk/simple-cli:latest
image-version: "1.0"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages: [systemd, ostree, linux-image-amd64]
  
  - type: org.osbuild.debian.locale
    options:
      locale: en_US.UTF-8
  
  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "10G"
      filename: "simple-cli-bootable"
```

### Available Stages
- **org.osbuild.debian.apt**: Package installation and management
- **org.osbuild.debian.locale**: Locale configuration
- **org.osbuild.debian.timezone**: Timezone configuration
- **org.osbuild.debian.users**: User creation and management
- **org.osbuild.qemu**: Image creation and formatting

## Build Process

### 1. Container Extraction
- Downloads specified base container image
- Extracts filesystem to temporary directory
- Prepares chroot environment

### 2. Stage Execution
- Runs each stage in sequence
- Installs packages, configures system
- May fail on certain stages due to permission issues

### 3. Image Creation
- Creates disk image with GPT partitioning
- Installs bootloader (extlinux/syslinux)
- Generates output in specified formats

### 4. Output
- Raw disk image (.img)
- QCOW2 format for QEMU/KVM
- VMDK format for VMware
- VDI format for VirtualBox

## Current Limitations

### Stage Failures
Some stages may fail due to chroot permission issues:
- Locale generation
- Timezone configuration
- User creation

### Bootability Issues
- Images boot to bootloader successfully
- Full OS boot requires kernel installation
- Init system setup incomplete

### Error Handling
- Limited error recovery
- Error messages may be truncated
- Silent failures possible

## Troubleshooting

### Common Issues

#### Permission Denied Errors
```bash
# Ensure running with sudo
sudo ./bib/particle-os build recipe.yml
```

#### Stage Failures
- Check recipe validation first
- Verify base image exists and is accessible
- Review error logs for specific failure points

#### Build Failures
- Ensure sufficient disk space
- Check network connectivity for container downloads
- Verify all dependencies installed

### Debug Mode
```bash
./bib/particle-os build -v recipe.yml
```

## Testing Created Images

### QEMU Testing
```bash
# Test raw image
qemu-system-x86_64 -hda output.img

# Test QCOW2 image
qemu-system-x86_64 -hda output.qcow2
```

### Expected Behavior
- Image should be recognized as bootable
- System should boot to bootloader
- Full OS boot may not work due to missing kernel

## Development Status

### Working Components
- Container extraction: 95% complete
- Package management: 90% complete
- Recipe parsing: 100% complete
- Stage execution: 40% complete
- Image creation: 80% complete
- Bootloader installation: 85% complete

### Next Steps
1. Fix remaining stage execution issues
2. Complete image creation pipeline
3. Implement kernel installation
4. Improve error handling and testing

## Production Readiness

**particle-os is NOT ready for production use.**

Current limitations include:
- Incomplete stage execution
- Limited error handling
- Bootability issues
- Insufficient testing coverage

## Alternative Approaches

If particle-os cannot complete the build process:

### Manual Image Creation
- Use container extraction manually
- Create filesystem manually
- Install bootloader manually
- Test bootability manually

### Container-Based Testing
- Test functionality within containers
- Validate concepts without full boot
- Use for development and testing

## Conclusion

particle-os provides a foundation for creating bootable Debian images from containers, but requires completion of several components before it can reliably produce fully bootable systems. The tool demonstrates the concept and has working core functionality, but is not yet suitable for production use.

For development and testing purposes, particle-os can create images that boot to bootloader, allowing validation of the basic boot process. Full OS functionality requires addressing the remaining stage execution issues and implementing kernel installation.
