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)

# 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

# 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

# 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

# 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

# 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

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

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:

# 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

particle-os list

Shows all available recipes with their details.

3. Validate Command

particle-os validate [RECIPE_PATH]

Validates a recipe file without building.

4. Version Command

particle-os version

Shows particle-os version information.

5. Container Command

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:

# 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

- 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

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

2. System Configuration Stages

org.osbuild.debian.locale

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

org.osbuild.debian.timezone

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

org.osbuild.debian.users

- 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

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

Recipe Examples

Minimal Server Recipe

# 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

# 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

# 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

# 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

# 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

# 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:

chroot: cannot change root directory: Operation not permitted

Solution:

# particle-os requires sudo for chroot operations
sudo particle-os build recipes/debian-server.yml

2. Container Pull Failures

Problem:

Error: failed to pull image: network error

Solution:

# 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:

E: Package 'package-name' not found

Solution:

# 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:

No space left on device

Solution:

# 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:

# Build seems to hang during package installation

Solution:

# 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

# 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:

# 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

# Faster builds with smaller base images
base-image: debian:trixie-slim    # ✅ Fast
base-image: debian:trixie         # ❌ Slower

2. Minimize Package Count

# Install only essential packages
packages:
  - nginx                    # ✅ Essential
  - nginx-extras            # ❌ Unnecessary extras

3. Parallel Stage Execution

# 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

# 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

# Don't over-allocate space
size: "5G"    # ✅ Appropriate for minimal server
size: "50G"   # ❌ Excessive for most use cases

🔒 Security Considerations

Password Security

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

Generate secure hashes:

# 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

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

Package Security

# 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 - Complete CI/CD examples
• Recipe Examples - More recipe templates
• API Reference - Technical documentation
• Contributing Guide - 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.