particle-os/README.md

# Debian Atomic Desktop Project

A project to create a Debian-based atomic desktop system using `bootc` and `OSTree`, inspired by `ublue-os`.

## Project Structure

This project is organized into phases:

### Phase 1: `01-debian-atomic/` ✅ Complete
- **Goal**: Create a minimal, bootable Debian Trixie atomic image
- **Status**: ✅ Complete
- **Contents**: 
  - `Containerfile` - Defines the base atomic image
  - `justfile` - Build automation
  - `README.md` - Phase 1 documentation

### Phase 2: `02-installer/` 🔄 In Progress
- **Goal**: Create a bootable ISO with Calamares installer using live-build
- **Status**: 🔄 In Progress (Contents file issues being resolved)
- **Contents**:
  - `justfile` - Live-build automation
  - `calamares/` - Installer configuration
  - `config/` - Live-build configuration
  - `scripts/` - Helper scripts

### Phase 2 Alternative: `02-installer-bootc/` 🔄 In Progress
- **Goal**: Modern approach using bootc + Calamares (Recommended)
- **Status**: 🔄 In Progress
- **Contents**:
  - `Containerfile` - Bootc container definition
  - `justfile` - Container build automation
  - `scripts/` - Testing scripts

## 🚀 **BREAKTHROUGH: bootc-image-builder Integration**

**Phase 1 Complete + Advanced Integration Opportunity Discovered**

We have successfully completed Phase 1 (minimal bootable Debian atomic image) and discovered an existing advanced `bootc-image-builder` project with professional-grade infrastructure:

### ✅ **Phase 1 Achievements**
- ✅ **Valid bootc Container**: Passes all `bootc container lint` validation
- ✅ **Complete Disk Utilities**: All partitioning and filesystem tools working
- ✅ **Kernel Integration**: Linux kernel properly detected and accessible
- ✅ **OSTree Structure**: Proper atomic filesystem layout validated
- ✅ **Deployment Testing**: Core functionality verified and working

### 🎯 **Integration Opportunity**
- ✅ **Advanced Project Found**: bootc-image-builder with Phase 4.2 complete
- ✅ **Professional Infrastructure**: 100% test coverage, performance optimization
- ✅ **Production Ready**: Comprehensive osbuild stages, Go integration
- ✅ **Multiple Formats**: QCOW2, ISO, RAW artifact generation
- 🚀 **Perfect Timing**: particle-os foundation ready for professional deployment

### 🔗 **Next Steps**
1. **Locate/Clone** the advanced bootc-image-builder project
2. **Test Integration** with our validated particle-os image
3. **Generate Artifacts** using professional deployment pipeline
4. **Document Workflow** for unified particle-os + bootc-image-builder process

## Critical Prerequisites: Disk Utilities for bootc Deployment

**⚠️ CRITICAL REQUIREMENT:** Successful deployment using `bootc install to-disk` requires specific disk utilities that are often missing from minimal environments.

### Essential Disk Utilities

The following utilities must be available in your deployment environment:

- **`sfdisk`** (from `util-linux`) - **CRITICAL** for automated partitioning
- **`parted`** - Alternative partitioning tool
- **`mkfs.ext4`** (from `e2fsprogs`) - Filesystem creation
- **`mkfs.fat`** (from `dosfstools`) - FAT32 filesystem for EFI
- **`grub-install`** - Bootloader installation
- **`efibootmgr`** - UEFI boot manager

### Installation and Verification

```bash
# Install required utilities
sudo apt update
sudo apt install -y util-linux parted e2fsprogs dosfstools grub-efi-amd64 efibootmgr

# Verify availability (all should return paths)
which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr

# Test sfdisk functionality
sfdisk --version
```

### Common Failure Points

- `error: Installing to disk: Creating rootfs: Failed to run sfdisk: No such file or directory`
- Missing filesystem creation tools
- Incomplete bootloader installation utilities

### Troubleshooting: PATH Issues in Minimal Environments

**Common Issue**: `sfdisk` exists but isn't found due to incomplete PATH in minimal environments.

**Diagnosis:**
```bash
# Check if util-linux is installed
dpkg -l | grep util-linux

# Find sfdisk location
find / -name sfdisk 2>/dev/null

# Check current PATH
echo $PATH

# Test sfdisk directly
/usr/sbin/sfdisk --version
```

**Solution:**
```bash
# Fix PATH and run bootc
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/debian-atomic:latest /usr/bin/bootc install to-disk /dev/target-device
```

**Note:** This requirement affects all phases and deployment scenarios. See `scope.md` for detailed implementation guidance.

## Quick Start

1. **Verify Prerequisites** (Critical):
   ```bash
   # Ensure disk utilities are available
   which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr
   sfdisk --version
   ```

2. **Phase 1** (Atomic Image):
   ```bash
   cd 01-debian-atomic
   just build-image
   just test-image
   ```

3. **Phase 2** (Traditional live-build approach):
   ```bash
   cd 02-installer
   just build-iso
   ```

4. **Phase 2 Alternative** (Modern bootc approach - Recommended):
   ```bash
   cd 02-installer-bootc
   just build-installer
   just test-installer-systemd
   ```

## Which Approach Should You Use?

### For Phase 2, we recommend the **bootc approach** (`02-installer-bootc/`) because:

✅ **Consistent tooling** - Everything uses bootc  
✅ **No sysvinit conflicts** - Pure systemd environment  
✅ **Atomic guarantees** - The installer itself is atomic  
✅ **Simpler maintenance** - One build system instead of two  
✅ **Modern approach** - Uses container-native tooling  

The traditional live-build approach (`02-installer/`) has many hook files and complex dependencies, which is why we created the bootc alternative.

## Prerequisites

- `just` command runner
- `podman` or `docker`
- `live-build` (for Phase 2 traditional approach)
- `qemu-system-x86_64` (for testing)
- **CRITICAL:** Complete disk utilities (`util-linux`, `parted`, `e2fsprogs`, `dosfstools`, `grub-efi-amd64`, `efibootmgr`)

## Performance Optimization

To speed up builds, use apt-cacher-ng:

```bash
# Set up apt-cacher-ng
./scripts/setup-apt-cacher.sh

# Then edit the justfile to enable the proxy
# In 02-installer/justfile, uncomment APT_CACHER_NG_PROXY
```

## Development

See `roadmap.md` for detailed project planning and `todo` for current tasks.

## Working Commands

See `WORKING_COMMANDS.md` for a comprehensive list of all tested and validated commands used throughout the project. This includes:

- Building and validating atomic images
- Testing bootc deployment methods
- Container management operations
- Troubleshooting commands
- Critical environment variables and requirements

All commands in `WORKING_COMMANDS.md` have been tested and validated.

## License

This project is open source. See individual files for specific licensing information.