0409f1d67c
Some checks failed
particle-os CI / Test particle-os (push) Failing after 1s
particle-os CI / Integration Test (push) Has been skipped
particle-os CI / Security & Quality (push) Failing after 1s
Test particle-os Basic Functionality / test-basic (push) Failing after 1s
Tests / test (1.21.x) (push) Failing after 1s
Tests / test (1.22.x) (push) Failing after 1s
particle-os CI / Build and Release (push) Has been skipped
- Add extensive documentation covering current status, usage, and testing strategies - Add recipe files for various image configurations (minimal, debug, kernel test, etc.) - Add testing and management scripts for comprehensive testing workflows - Add Go module configuration and updated Go code - Add manual bootable image creation script - Update todo with current project status and next steps
249 lines
6.5 KiB
Markdown
249 lines
6.5 KiB
Markdown
# 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.
|