Major refactor: Remove debos integration, add particle-os CLI system, implement OSTree stages, and create comprehensive build pipeline

2025-08-12 16:17:39 -07:00 · 2025-08-12 16:17:39 -07:00 · d2d4c2e4e7
commit d2d4c2e4e7
parent c7e335d60f
101 changed files with 13234 additions and 6342 deletions
--- a/recipes/README.md
+++ b/recipes/README.md
@ -0,0 +1,263 @@
+# 🎯 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).