d2d4c2e4e7
Some checks failed
particle-os CI / Test particle-os (push) Failing after 1s
particle-os CI / Integration Test (push) Has been skipped
particle-os CI / Security & Quality (push) Failing after 1s
Test particle-os Basic Functionality / test-basic (push) Failing after 1s
Tests / test (1.21.x) (push) Failing after 2s
Tests / test (1.22.x) (push) Failing after 1s
particle-os CI / Build and Release (push) Has been skipped
263 lines
6.6 KiB
Markdown
263 lines
6.6 KiB
Markdown
# 🎯 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).
|