deb-bootc-image-builder/recipes/README.md

🎯 particle-os Recipe System

Welcome to the particle-os recipe system! This system allows you to create custom Debian-based OS images using declarative YAML recipes, similar to BlueBuild in the ublue-os ecosystem.

🌟 What is particle-os?

particle-os is a Debian-native OS image builder that creates bootable images from container images and recipes. It provides:

• Container-first workflow - Build OS from containers
• Declarative configuration - YAML-based recipes
• Multiple output formats - raw, qcow2, vmdk, vdi
• OSTree + bootupd integration - Atomic updates and bootloader management
• Debian-native stages - Built specifically for Debian

📚 Available Recipes

🖥️ debian-desktop.yml

A full-featured desktop OS with GNOME, office applications, and multimedia tools.

Features:

• GNOME desktop environment
• LibreOffice suite
• Firefox ESR browser
• GIMP image editor
• VLC media player
• Thunderbird email client

Use case: Daily desktop computing, office work, content creation

🖥️ debian-server.yml

A server-focused OS with web servers, databases, and monitoring tools.

Features:

• Nginx and Apache web servers
• MariaDB and PostgreSQL databases
• Docker and Docker Compose
• Redis cache server
• Monitoring and security tools
• SSH server with fail2ban

Use case: Web hosting, application servers, development environments

🎮 debian-gaming.yml

A gaming-focused OS with Steam, Wine, and performance optimization tools.

Features:

• Steam gaming platform
• Wine for Windows games
• Lutris game manager
• Performance monitoring tools
• Graphics and audio optimization
• Gaming-specific utilities

Use case: Gaming, streaming, content creation

🔧 Creating Your Own Recipes

Basic Recipe Structure

name: my-custom-os
description: My custom Debian-based OS
base-image: debian:trixie
image-version: "13"

stages:
  - type: org.osbuild.debian.debootstrap
    options:
      suite: trixie
      target: /tmp/rootfs
      arch: amd64
      
  - type: org.osbuild.debian.apt
    options:
      packages:
        - my-package-1
        - my-package-2
      update: true
      
  - type: org.osbuild.qemu
    options:
      formats: ["raw", "qcow2"]
      size: "10G"

output:
  formats: ["raw", "qcow2"]
  size: "10G"

Available Stage Types

Debian System Stages

• org.osbuild.debian.debootstrap - Create base system
• org.osbuild.debian.sources - Configure package sources
• org.osbuild.debian.apt - Install packages
• org.osbuild.debian.locale - Set system locale
• org.osbuild.debian.timezone - Set timezone
• org.osbuild.debian.users - Create user accounts

System Integration Stages

• org.osbuild.ostree - OSTree repository management
• org.osbuild.bootupd - Bootloader configuration
• org.osbuild.qemu - Image creation and formatting

Stage Options

Debootstrap Options

- type: org.osbuild.debian.debootstrap
  options:
    suite: trixie          # Debian suite (sid, trixie, bookworm)
    target: /tmp/rootfs    # Target directory
    arch: amd64            # Architecture
    variant: minbase       # Variant (minbase, buildd, fakechroot)
    components: ["main", "contrib", "non-free"]

APT Options

- type: org.osbuild.debian.apt
  options:
    packages:               # List of packages to install
      - package1
      - package2
    update: true            # Run apt update
    clean: true             # Clean package cache
    sources:                # Additional sources
      - "deb http://example.com/debian trixie main"

Users Options

- type: org.osbuild.debian.users
  options:
    users:
      username:
        password: "$6$hash$password"  # Encrypted password
        shell: /bin/bash
        groups: ["sudo", "users"]
        uid: 1000
        gid: 1000
        home: /home/username
        comment: "User description"

Output Options

output:
  formats: ["raw", "qcow2", "vmdk", "vdi"]  # Output formats
  size: "20G"                               # Image size
  path: "my-os"                             # Base filename

🚀 Using Recipes

Building from a Recipe

# Basic build
particle-os build recipes/debian-desktop.yml

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

# Build with custom work directory
particle-os build --work-dir /tmp/my-build recipes/debian-desktop.yml

# Build and cleanup
particle-os build --clean recipes/debian-desktop.yml

Validating Recipes

# Validate a recipe before building
particle-os validate recipes/debian-desktop.yml

Listing Available Recipes

# List all available recipes
particle-os list

🎨 Recipe Best Practices

1. Start Simple

Begin with basic stages and add complexity gradually.

2. Use Descriptive Names

Choose clear, descriptive names for your recipes and stages.

3. Group Related Packages

Organize packages by category in your apt stages.

4. Test Incrementally

Test each stage as you build to catch issues early.

5. Document Dependencies

Include all necessary packages and their purposes.

6. Version Control

Keep your recipes in version control for collaboration.

🔍 Troubleshooting

Common Issues

Recipe Validation Fails

• Check YAML syntax
• Ensure all required fields are present
• Verify stage types are correct

Build Fails

• Check package availability in Debian repositories
• Verify target directories exist
• Check disk space availability

Image Won't Boot

• Ensure bootupd stage is included
• Verify partition configuration
• Check bootloader installation

Getting Help

• Check the recipe validation output
• Review the build logs
• Test with simpler recipes first
• Consult the particle-os documentation

🌟 Advanced Features

Custom Stages

You can extend particle-os with custom stages for specific needs.

Template Variables

Use variables in recipes for dynamic configuration.

Multi-Architecture Support

Build images for different architectures (amd64, arm64, etc.).

Integration with CI/CD

Automate builds in your CI/CD pipeline.

📖 Examples and Templates

Check the examples/ directory for more recipe templates and advanced configurations.

🤝 Contributing

We welcome contributions to the particle-os recipe system! Please:

1. Test your recipes thoroughly
2. Document new features
3. Follow the existing style guidelines
4. Submit pull requests with clear descriptions

---

Happy building! 🚀

For more information, visit the particle-os documentation.