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

```yaml
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**
```yaml
- 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**
```yaml
- 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**
```yaml
- 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**
```yaml
output:
  formats: ["raw", "qcow2", "vmdk", "vdi"]  # Output formats
  size: "20G"                               # Image size
  path: "my-os"                             # Base filename
```

## 🚀 Using Recipes

### Building from a Recipe

```bash
# 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

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

### Listing Available Recipes

```bash
# 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](https://github.com/particle-os/particle-os).