deb-bootc-image-builder/docs/HOW-TO-USE.md

# How to Use deb-bootc-image-builder

## 🎯 **Current Status: PARTIALLY WORKING PROTOTYPE** ⚠️

**⚠️ IMPORTANT**: This tool is currently a **working prototype** with **significant gaps**. It demonstrates the concept and has working foundations, but critical limitations exist that prevent reliable production use.

---

## 📋 **What's Actually Working**

### ✅ **Core Infrastructure (95% Complete)**
- **Container extraction**: Successfully extracts Docker/Podman container images
- **Package management**: apt package installation works correctly in chroot
- **Basic image creation**: Creates GPT partition tables and ext4 filesystems
- **Recipe system**: YAML recipe parsing and validation functional
- **CLI framework**: Professional command-line interface with Cobra

### ✅ **What You Can Do Right Now**
- Extract containers and create rootfs
- Install packages using apt (apt stage works completely)
- Create basic disk image structure
- Parse and validate recipes
- Generate raw disk images with proper partitioning

---

## 🚨 **What's NOT Working (Critical Gaps)**

### ❌ **Stage Execution Failures**
- **Locale stage**: Fails during locale generation (chroot permission issues)
- **Timezone stage**: Untested, likely has similar permission issues
- **Users stage**: Untested, may have chroot permission problems
- **OSTree stages**: Just placeholders, no actual functionality
- **Bootupd stage**: Just placeholder, no actual configuration

### ❌ **Image Creation Pipeline**
- **Final image creation**: The `createFinalImage()` function exists but isn't reached due to stage failures
- **Output formats**: Only raw format is tested, qcow2/vmdk/vdi untested
- **Bootability**: Images lack kernels and proper boot configuration

### ❌ **Production Readiness**
- **Error handling**: Poor error recovery and truncated error messages
- **Testing**: No comprehensive validation or testing
- **Bootability**: Cannot reliably produce bootable images

---

## 🚀 **Installation & Setup**

### **Prerequisites**
```bash
# Required tools
sudo apt install podman docker.io parted mkfs.ext4 extlinux

# Optional (for additional features)
sudo apt install qemu-utils fakemachine
```

### **Current Installation Status**
- **Binary**: Pre-compiled binary available in `bib/particle-os`
- **Source**: Go source code available in `bib/` directory
- **Dependencies**: All required tools must be installed manually

---

## 📖 **Command-Line Usage**

### **Basic Commands**

#### **Build an Image (Limited Functionality)**
```bash
# Basic build (apt stage only works)
./bib/particle-os build recipes/minimal-debug.yml

# With verbose output
./bib/particle-os build recipes/minimal-debug.yml --verbose

# Specify work directory
./bib/particle-os build recipes/minimal-debug.yml --work-dir /tmp/custom-build

# Clean up after build
./bib/particle-os build recipes/minimal-debug.yml --clean
```

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

#### **Validate a Recipe**
```bash
./bib/particle-os validate recipes/minimal-debug.yml
```

#### **Check Version**
```bash
./bib/particle-os version
```

#### **Container Operations**
```bash
# List available containers
./bib/particle-os container list

# Inspect a container
./bib/particle-os container inspect debian:trixie-slim
```

### **Global Flags**
```bash
--verbose, -v    # Enable verbose logging
--work-dir, -w   # Specify working directory for builds
```

### **Build Flags**
```bash
--output, -o     # Output path for the image
--clean, -c      # Clean up work directory after build
--json, -j       # Output results in JSON format (CI/CD friendly)
--quiet, -q      # Suppress non-essential output (CI/CD friendly)
```

---

## 📝 **Recipe Format**

### **Basic Recipe Structure**
```yaml
name: my-custom-image
description: A custom Debian-based image
base-image: debian:trixie-slim
image-version: "1.0"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages:
        - bash
        - coreutils
        - locales
      update: true
      clean: true

  - type: org.osbuild.debian.locale
    options:
      language: en_US.UTF-8
      default_locale: en_US.UTF-8

  - type: org.osbuild.debian.timezone
    options:
      timezone: UTC

  - type: org.osbuild.debian.users
    options:
      users:
        admin:
          password: "$6$rounds=656000$salt$hashed_password"
          shell: /bin/bash
          groups: ["sudo", "users"]
          uid: 1000
          gid: 1000
          home: /home/admin
          comment: "Administrator User"

  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "5G"
      filename: "my-custom-image"

output:
  formats: ["raw", "qcow2"]
  size: "5G"
  path: "my-custom-image"

metadata:
  author: "Your Name"
  category: "custom"
  tags: ["custom", "debian", "particle-os"]
```

### **Available Stage Types**

#### ✅ **Working Stages**
- `org.osbuild.debian.apt`: Package installation (✅ WORKING)
- `org.osbuild.debian.sources`: Package source configuration (✅ WORKING)

#### ❌ **Broken/Incomplete Stages**
- `org.osbuild.debian.locale`: Locale configuration (❌ FAILS DUE TO PERMISSIONS)
- `org.osbuild.debian.timezone`: Timezone configuration (❌ UNTESTED, LIKELY BROKEN)
- `org.osbuild.debian.users`: User creation (❌ UNTESTED, LIKELY BROKEN)

#### 🔧 **Placeholder Stages (Not Implemented)**
- `org.osbuild.debian.ostree`: OSTree repository operations
- `org.osbuild.debian.ostree_boot`: OSTree boot configuration
- `org.osbuild.ostree_deploy`: OSTree deployment

#### 🔧 **Image Creation Stage**
- `org.osbuild.qemu`: QEMU image creation (⚠️ FRAMEWORK EXISTS, NEVER REACHED)

---

## 🧪 **Testing & Development**

### **Current Test Recipes**
- `minimal-debug.yml`: Basic apt stage testing (✅ WORKING)
- `minimal-debug-locale.yml`: Locale stage testing (❌ FAILS DUE TO PERMISSIONS)
- `simple-cli-bootable.yml`: Full workflow testing (❌ FAILS DUE TO STAGE ISSUES)

### **Testing Workflow**
```bash
# 1. Test basic functionality (should work)
./bib/particle-os build recipes/minimal-debug.yml --verbose

# 2. Test with locale stage (currently fails)
./bib/particle-os build recipes/minimal-debug-locale.yml --verbose

# 3. Test full workflow (currently fails)
./bib/particle-os build recipes/simple-cli-bootable.yml --verbose
```

### **Debugging Tips**
- Use `--verbose` flag for detailed logging
- Check work directory for intermediate files
- Monitor disk space (builds require significant space)
- Use `--work-dir` to specify custom working directory

---

## 🔧 **Development & Compilation**

### **Current Source Status**
- **Go source**: Complete in `bib/` directory
- **Permission fixes**: Some fixes implemented but not comprehensive
- **Binary**: Needs recompilation to include latest fixes

### **Compilation (When Go is Available)**
```bash
cd bib
go build -o particle-os cmd/builder/main.go
cd ..
```

### **What's Fixed in Source**
- ✅ Some permission fixes for chroot operations
- ✅ Basic error handling improvements
- ✅ Helper functions for file operations

---

## 🎯 **Planned Features (Not Yet Implemented)**

### **Phase 1: Complete Stage Execution (1-2 weeks)**
- [ ] Fix remaining stage permission issues
- [ ] Test all stages complete successfully
- [ ] Validate end-to-end workflow

### **Phase 2: Complete Image Creation (2-3 weeks)**
- [ ] Integrate working image creation into main build flow
- [ ] Test all output formats (raw, qcow2, vmdk, vdi)
- [ ] Add proper error handling and recovery

### **Phase 3: Improve Bootability (2-3 weeks)**
- [ ] Add kernel installation capability
- [ ] Implement proper init system setup
- [ ] Test full OS boot process

### **Phase 4: Production Readiness (2-4 weeks)**
- [ ] Add comprehensive testing
- [ ] Improve error handling
- [ ] Add disk space management
- [ ] Complete documentation

---

## 🚨 **Known Issues & Limitations**

### **Critical Issues**
1. **Stage failures**: Locale, timezone, and users stages fail due to permission issues
2. **Image creation**: Final image creation never reached due to stage failures
3. **Bootability**: Generated images lack kernels and proper boot configuration
4. **Error handling**: Poor error recovery and truncated error messages

### **Environment Dependencies**
1. **sudo access**: Required for chroot operations and file operations
2. **Disk space**: Builds require significant temporary storage
3. **Tool availability**: parted, mkfs.ext4, extlinux must be installed
4. **Container tools**: podman or docker required

### **Base Image Limitations**
1. **Only tested**: `debian:trixie-slim`
2. **Architecture**: x86_64 only
3. **Kernel support**: Base images lack kernels
4. **Boot system**: Minimal boot configuration only

---

## 💡 **Getting Help**

### **Current Status Documentation**
- `current_stats.md`: Realistic assessment of capabilities
- `todo`: Detailed project status and next steps
- `DEVELOPMENT_ROADMAP.md`: Strategic development plan

### **Reporting Issues**
- **Stage failures**: Include verbose output and recipe used
- **Permission issues**: Check sudo access and tool availability
- **Build failures**: Verify disk space and tool installation

### **Development Progress**
- **Current phase**: Critical issue resolution
- **Timeline**: 6-8 weeks to production readiness
- **Focus**: Fix stage execution failures first

---

## 🎉 **What We've Achieved**

Despite the limitations, we have:

1. **✅ Working prototype**: Demonstrates container-to-image conversion concept
2. **✅ Solid foundation**: Core infrastructure is functional and well-designed
3. **✅ Professional CLI**: User-friendly command-line interface
4. **✅ Recipe system**: Flexible YAML-based configuration
5. **✅ Container integration**: Real Docker/Podman support

**The tool shows great promise and has the right architecture for production use, but needs focused development to address the critical gaps.**

---

**Last Updated**: August 17, 2025  20:00
**Status**: ⚠️ **PARTIALLY WORKING PROTOTYPE - Development in Progress**  
**Next Milestone**: Fix Stage Execution Failures  
**Production Readiness**: 20% (estimated 6-8 weeks to completion)
**Source**: Based on `current_stats.md` - realistic assessment