deb-bootc-image-builder/docs/user-guide.md

# particle-os User Guide

particle-os is a Debian-native OS image builder that creates bootable images from container images and recipes, similar to ublue-os but with a Debian foundation.

## 🚀 Quick Start

### **Installation**

#### **From Source (Recommended)**
```bash
# Clone the repository
git clone https://github.com/your-username/particle-os.git
cd particle-os

# Build particle-os
cd bib
go build -o particle-os cmd/builder/main.go
cd ..

# Test installation
./bib/particle-os --version
```

#### **System Requirements**
- **OS**: Debian 12+ (Bookworm/Trixie) or Ubuntu 22.04+
- **Go**: 1.21+ for building from source
- **Dependencies**: `qemu-utils`, `podman` or `docker`
- **Storage**: 10GB+ free space for builds
- **RAM**: 4GB+ recommended

### **First Build**

```bash
# Build a simple test image
sudo ./bib/particle-os build recipes/debian-test.yml

# Build with custom output
sudo ./bib/particle-os build --output my-image.img recipes/debian-desktop.yml

# Build in CI/CD mode
sudo ./bib/particle-os build --json --quiet --clean recipes/debian-server.yml
```

## 📚 Understanding particle-os

### **What is particle-os?**

particle-os is a **container-first OS image builder** that:

- 🐳 **Extracts base container images** (Debian, Ubuntu, etc.)
- 🔧 **Applies stages** (packages, users, configuration)
- 🖼️ **Creates bootable images** (raw, qcow2, vmdk, vdi)
- 📋 **Uses declarative recipes** (YAML configuration files)

### **Key Concepts**

#### **1. Container-First Approach**
```bash
# Traditional approach: Build OS from scratch
debian-installer → packages → configuration → image

# particle-os approach: Start with container
container-image → stages → bootable-image
```

#### **2. Declarative Recipes**
```yaml
# recipes/debian-server.yml
name: debian-server
base-image: debian:trixie
stages:
  - type: org.osbuild.debian.apt
    options:
      packages: [nginx, docker.io, openssh-server]
```

#### **3. Stage-Based Processing**
```bash
# Each recipe defines stages that run in sequence:
1. Extract base container
2. Run apt stage (install packages)
3. Run locale stage (configure language)
4. Run users stage (create users)
5. Run QEMU stage (create image)
```

## 🔧 Command Line Interface

### **Global Commands**

```bash
particle-os [GLOBAL_FLAGS] COMMAND [COMMAND_FLAGS]
```

#### **Global Flags**
- `-v, --verbose` - Enable verbose logging
- `-w, --work-dir` - Set custom working directory
- `-h, --help` - Show help

### **Available Commands**

#### **1. Build Command**
```bash
particle-os build [RECIPE_PATH] [FLAGS]
```

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

**Examples:**
```bash
# Basic build
particle-os build recipes/debian-desktop.yml

# Build with custom output and cleanup
particle-os build --output server.img --clean recipes/debian-server.yml

# CI/CD mode
particle-os build --json --quiet --clean recipes/debian-gaming.yml
```

#### **2. List Command**
```bash
particle-os list
```

Shows all available recipes with their details.

#### **3. Validate Command**
```bash
particle-os validate [RECIPE_PATH]
```

Validates a recipe file without building.

#### **4. Version Command**
```bash
particle-os version
```

Shows particle-os version information.

#### **5. Container Command**
```bash
particle-os container [CONTAINER_IMAGE] [FLAGS]
```

Build directly from a container image.

## 📋 Recipe System

### **Recipe Structure**

A particle-os recipe is a YAML file that defines:

```yaml
# Basic recipe structure
name: "recipe-name"                    # Required: Recipe identifier
description: "Description"             # Optional: Human-readable description
base-image: "container:tag"           # Required: Base container image
image-version: "version"              # Optional: Image version

stages:                               # Required: List of build stages
  - type: "stage.type"               # Stage type identifier
    options:                          # Stage-specific options
      key: "value"

output:                               # Required: Output configuration
  formats: ["raw", "qcow2"]          # Output formats
  size: "10G"                        # Image size
  path: "output-name"                # Output filename

metadata:                             # Optional: Additional metadata
  author: "Your Name"
  category: "server"
  tags: ["debian", "server"]
```

### **Available Stages**

#### **1. Package Management Stages**

##### **org.osbuild.debian.apt**
```yaml
- type: org.osbuild.debian.apt
  options:
    packages:
      - nginx
      - docker.io
      - openssh-server
    update: true          # Run apt update
    clean: true           # Clean package cache
```

##### **org.osbuild.debian.debootstrap**
```yaml
- type: org.osbuild.debian.debootstrap
  options:
    suite: trixie         # Debian suite
    target: /tmp/rootfs   # Target directory
```

#### **2. System Configuration Stages**

##### **org.osbuild.debian.locale**
```yaml
- type: org.osbuild.debian.locale
  options:
    language: en_US.UTF-8
    default_locale: en_US.UTF-8
```

##### **org.osbuild.debian.timezone**
```yaml
- type: org.osbuild.debian.timezone
  options:
    timezone: UTC
```

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

#### **3. Image Creation Stages**

##### **org.osbuild.qemu**
```yaml
- type: org.osbuild.qemu
  options:
    formats: ["raw", "qcow2", "vmdk", "vdi"]
    size: "20G"
    filename: "debian-server"
```

### **Recipe Examples**

#### **Minimal Server Recipe**
```yaml
# recipes/debian-minimal-server.yml
name: debian-minimal-server
description: Minimal Debian server with essential tools
base-image: debian:trixie-slim
image-version: "13"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages:
        - openssh-server
        - curl
        - wget
        - vim
        - less
        - locales
        - ca-certificates
        - tzdata
      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$hashedpassword"
          shell: /bin/bash
          groups: ["sudo", "users"]
          uid: 1000
          gid: 1000
          home: /home/admin
          comment: "Administrator User"
      default_shell: /bin/bash
      default_home: /home
      
  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "5G"
      filename: "debian-minimal-server"

output:
  formats: ["raw", "qcow2"]
  size: "5G"
  path: "debian-minimal-server"

metadata:
  author: "particle-os"
  category: "server"
  tags: ["minimal", "server", "debian"]
```

#### **Desktop Recipe**
```yaml
# recipes/debian-desktop.yml
name: debian-desktop
description: Debian desktop with GNOME and common applications
base-image: debian:trixie
image-version: "13"

stages:
  - type: org.osbuild.debian.apt
    options:
      packages:
        - gnome
        - firefox-esr
        - libreoffice
        - gimp
        - vlc
        - thunderbird
        - file-roller
        - gnome-tweaks
      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:
        user:
          password: "$6$rounds=656000$salt$hashedpassword"
          shell: /bin/bash
          groups: ["users", "sudo"]
          uid: 1000
          gid: 1000
          home: /home/user
          comment: "Desktop User"
      default_shell: /bin/bash
      default_home: /home
      
  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2", "vmdk"]
      size: "15G"
      filename: "debian-desktop"

output:
  formats: ["raw", "qcow2", "vmdk"]
  size: "15G"
  path: "debian-desktop"

metadata:
  author: "particle-os"
  category: "desktop"
  tags: ["desktop", "gnome", "debian"]
```

## 🚀 Advanced Usage

### **Custom Working Directory**

```bash
# Use custom working directory
particle-os build --work-dir /tmp/my-build recipes/debian-server.yml

# This creates:
# /tmp/my-build/rootfs/     - Extracted container filesystem
# /tmp/my-build/output/     - Generated images
# /tmp/my-build/stages/     - Stage execution logs
```

### **Verbose Logging**

```bash
# Enable detailed logging
particle-os build --verbose recipes/debian-server.yml

# Shows:
# - Container extraction progress
# - Stage execution details
# - File operations
# - Timing information
```

### **CI/CD Integration**

```bash
# Build with CI/CD flags
particle-os build --json --quiet --clean recipes/debian-server.yml

# Output is pure JSON for parsing:
{
  "success": true,
  "recipe": "debian-server",
  "image_path": "/tmp/particle-os-build/output/debian-server.img",
  "exit_code": 0
}
```

### **Building from Container Images**

```bash
# Build directly from container
particle-os container debian:trixie --output my-image.img

# This creates a minimal image with just the base container
```

## 🔍 Troubleshooting

### **Common Issues**

#### **1. Permission Denied Errors**

**Problem:**
```bash
chroot: cannot change root directory: Operation not permitted
```

**Solution:**
```bash
# particle-os requires sudo for chroot operations
sudo particle-os build recipes/debian-server.yml
```

#### **2. Container Pull Failures**

**Problem:**
```bash
Error: failed to pull image: network error
```

**Solution:**
```bash
# Check network connectivity
ping deb.debian.org

# Verify container runtime
podman --version
docker --version

# Try with different registry
# Edit recipe to use: base-image: "docker.io/debian:trixie"
```

#### **3. Package Installation Failures**

**Problem:**
```bash
E: Package 'package-name' not found
```

**Solution:**
```bash
# Check package availability
podman run --rm debian:trixie apt search package-name

# Update package lists in recipe
- type: org.osbuild.debian.apt
  options:
    packages: [package-name]
    update: true  # This runs apt update first
```

#### **4. Insufficient Disk Space**

**Problem:**
```bash
No space left on device
```

**Solution:**
```bash
# Check available space
df -h

# Clean up old builds
sudo rm -rf /tmp/particle-os-build

# Use custom work directory with more space
particle-os build --work-dir /mnt/large-disk/build recipes/debian-server.yml
```

#### **5. Build Hangs**

**Problem:**
```bash
# Build seems to hang during package installation
```

**Solution:**
```bash
# Check if it's actually working (verbose mode)
particle-os build --verbose recipes/debian-server.yml

# Some operations take time (locale generation, package downloads)
# Use --verbose to see progress
```

### **Debug Mode**

```bash
# Enable debug logging
export PARTICLE_OS_DEBUG=1
particle-os build --verbose recipes/debian-server.yml

# Check work directory contents
ls -la /tmp/particle-os-build/
ls -la /tmp/particle-os-build/rootfs/
ls -la /tmp/particle-os-build/output/
```

### **Log Files**

particle-os creates detailed logs in the work directory:

```bash
# View stage logs
cat /tmp/particle-os-build/stages/*.log

# View container extraction log
cat /tmp/particle-os-build/container-extraction.log

# View final build log
cat /tmp/particle-os-build/build.log
```

## 📊 Performance Optimization

### **Build Time Optimization**

#### **1. Use Slim Base Images**
```yaml
# Faster builds with smaller base images
base-image: debian:trixie-slim    # ✅ Fast
base-image: debian:trixie         # ❌ Slower
```

#### **2. Minimize Package Count**
```yaml
# Install only essential packages
packages:
  - nginx                    # ✅ Essential
  - nginx-extras            # ❌ Unnecessary extras
```

#### **3. Parallel Stage Execution**
```yaml
# Stages run sequentially, but you can optimize:
# 1. Group related operations in single stages
# 2. Use efficient package lists
# 3. Minimize file operations
```

### **Storage Optimization**

#### **1. Clean After Builds**
```bash
# Always use --clean flag in CI/CD
particle-os build --clean recipes/debian-server.yml

# Or manually clean
sudo rm -rf /tmp/particle-os-build
```

#### **2. Use Appropriate Image Sizes**
```yaml
# Don't over-allocate space
size: "5G"    # ✅ Appropriate for minimal server
size: "50G"   # ❌ Excessive for most use cases
```

## 🔒 Security Considerations

### **Password Security**

```yaml
# Use hashed passwords, not plain text
users:
  admin:
    password: "$6$rounds=656000$salt$hashedpassword"  # ✅ Secure
    password: "mypassword123"                         # ❌ Insecure
```

**Generate secure hashes:**
```bash
# Generate password hash
openssl passwd -6 -salt salt mypassword

# Or use Python
python3 -c "import crypt; print(crypt.crypt('mypassword', crypt.mksalt(crypt.METHOD_SHA512)))"
```

### **Base Image Security**

```yaml
# Use specific, trusted base images
base-image: debian:trixie-slim@sha256:abc123...  # ✅ Pinned digest
base-image: debian:latest                        # ❌ Unpinned tag
```

### **Package Security**

```yaml
# Only install necessary packages
packages:
  - nginx                    # ✅ Required
  - nginx-doc               # ❌ Potentially unnecessary
```

## 🚀 Next Steps

### **What You Can Do Now**

1. **Build your first image** with the test recipe
2. **Create custom recipes** for your specific needs
3. **Integrate with CI/CD** using the provided examples
4. **Optimize builds** for your use case
5. **Contribute recipes** to the community

### **Advanced Topics to Explore**

- **Custom stages** - Create your own build stages
- **Multi-architecture builds** - Build for ARM64, etc.
- **Cloud integration** - Deploy to AWS, GCP, Azure
- **Automated testing** - Test images in virtual machines
- **Distribution** - Share your custom OS images

### **Getting Help**

- **Documentation**: Check this guide and other docs
- **Issues**: Report bugs on GitHub
- **Discussions**: Ask questions in GitHub Discussions
- **Community**: Join the particle-os community

## 📚 Additional Resources

- **[CI/CD Integration Guide](ci-cd-integration.md)** - Complete CI/CD examples
- **[Recipe Examples](recipes/README.md)** - More recipe templates
- **[API Reference](api-reference.md)** - Technical documentation
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute

---

**Happy building! 🚀**

particle-os makes it easy to create custom Debian-based operating systems. Start with simple recipes and gradually build more complex systems as you learn the platform.