robojerk/particle-os
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix critical PATH issues and add related projects to README

Browse source 
- Fixed sfdisk PATH issue in Containerfile.base (sfdisk is in /usr/sbin)
- Updated Containerfile.minimal to use full path for grub-install
- Enhanced test-bootc-deployment.sh to properly check utility locations
- Added comprehensive section about related projects (apt-ostree, deb-bootupd, debian-bootc-corrected)
- Updated validation script to handle Debian-specific utility locations
- Improved error messages with specific solutions for PATH and utility issues

This addresses the critical requirements from scope.md regarding disk utilities
and PATH environment variables for bootc deployment.
This commit is contained in:
robojerk 2025-08-10 18:15:04 -07:00
parent 04c7fd1e4c
commit f9fb8d3bd0
149 changed files with 1625 additions and 9188 deletions
Download patch file Download diff file Expand all files Collapse all files

308
README.md
View file

@ -1,203 +1,153 @@
# Debian Atomic Desktop Project
# Particle-OS
A project to create a Debian-based atomic desktop system using `bootc` and `OSTree`, inspired by `ublue-os`.
A Debian-based immutable operating system following the ublue-os pattern, built from the ground up using modern container technologies.
## Project Structure
## 🎯 Project Vision
This project is organized into phases:
**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
### 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
## 🚀 Quick Start
### 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
### Prerequisites
### 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
- **Podman** - Container runtime
- **Just** - Command runner (install with `cargo install just`)
## 🚀 **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
### Build Your First Image
```bash
# Install required utilities
sudo apt update
sudo apt install -y util-linux parted e2fsprogs dosfstools grub-efi-amd64 efibootmgr
# Validate prerequisites
just validate-prereqs
# Verify availability (all should return paths)
which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr
# Build the minimal bootable image (Phase 1 goal)
just build-minimal
# Test sfdisk functionality
sfdisk --version
# Test the image
just test-image
```
### 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:
### One-Command Setup
```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
# Complete quick start (build + test)
just quick-start
```
## Development
## 🛠️ Available Commands
See `roadmap.md` for detailed project planning and `todo` for current tasks.
### 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)
## Working Commands
### Testing & Validation
- `just test-image` - Test built image in VM
- `just test-bootupd` - Test deb-bootupd functionality
- `just test-ostree` - Test apt-ostree functionality
See `WORKING_COMMANDS.md` for a comprehensive list of all tested and validated commands used throughout the project. This includes:
### Utility Commands
- `just clean` - Clean up build artifacts
- `just status` - Show current build status
- `just help` - Show help message
- Building and validating atomic images
- Testing bootc deployment methods
- Container management operations
- Troubleshooting commands
- Critical environment variables and requirements
## 🏗️ Architecture
All commands in `WORKING_COMMANDS.md` have been tested and validated.
### Base Image Strategy
```
debian:trixie-slim → bootc image → bootable OS
```
## License
### 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`
This project is open source. See individual files for specific licensing information.
### 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
### Build Tools
- **[debian-bootc-corrected](https://git.raines.xyz/robojerk/-/packages/container/bootc-image-builder/debian-bootc-corrected)** - Bootc image builder for Debian
- Container image for building bootc-compatible Debian images
- Pre-configured with all necessary build tools
- Used in the Particle-OS build process
### 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.