# OSTree Requirements and Conventions

This document outlines the critical requirements and conventions that must be followed when building OSTree-compliant systems for Particle-OS.

## 🏗️ **Critical Filesystem Structure**

### **Required Directories**
```
/ostree/                    # OSTree repository root
/sysroot/                   # System root for deployments
/boot/                      # Boot files (EFI, GRUB)
/usr/lib/ostree-boot/       # OSTree-specific boot files
/usr/lib/modules/           # Kernel modules (versioned)
/usr/lib/kernel/            # Kernel headers (versioned)
/usr/lib/firmware/          # Hardware firmware
/etc/ostree/                # OSTree configuration
/var/lib/ostree/            # OSTree data
/var/home/                  # User home directories
```

### **OSTree Deployment Structure**
```
/sysroot/ostree/deploy/{osname}/{variant}/
├── deploy/                 # Current deployment
├── var/                    # Variable data
└── usr/                    # User space
```

## 🏷️ **Required Labels and Metadata**

### **OCI Image Labels**
```dockerfile
LABEL org.opencontainers.image.ostree.osname="particle-os"
LABEL org.opencontainers.image.ostree.osversion="0.1.0"
LABEL org.opencontainers.image.ostree.osvariant="minimal|server|desktop"
LABEL org.opencontainers.image.ostree.desktop="plasma"  # For desktop variants
```

### **OSTree Configuration**
```bash
# /etc/ostree/ostree.conf
OSTREE_BOOTABLE=true
OSTREE_OSNAME=particle-os
OSTREE_OSVERSION=0.1.0
OSTREE_OSVARIANT=minimal|server|desktop
OSTREE_SERVICES=ssh,cockpit,sddm
OSTREE_DESKTOP=plasma  # For desktop variants
```

## 🐧 **Kernel and Module Requirements**

### **Kernel Versioning**
- **Must use specific kernel versions** (not generic `uname -r`)
- **Modules must be in `/usr/lib/modules/{version}/`**
- **Headers must be in `/usr/lib/kernel/{version}/`**
- **Proper symlinks for build and source directories**

### **Module Setup Commands**
```bash
# Get kernel version from package
KERNEL_VERSION=$(dpkg-query -W -f='${Version}' linux-image-amd64 | sed 's/-.*//')

# Create versioned directories
mkdir -p "/usr/lib/modules/$KERNEL_VERSION"
mkdir -p "/usr/lib/kernel/$KERNEL_VERSION"

# Set up symlinks
ln -sf "/usr/src/linux-headers-$KERNEL_VERSION" "/usr/lib/modules/$KERNEL_VERSION/build"
ln -sf "/usr/src/linux-headers-$KERNEL_VERSION" "/usr/lib/kernel/$KERNEL_VERSION/build"

# Copy source
cp -r "/usr/src/linux-headers-$KERNEL_VERSION" "/usr/lib/modules/$KERNEL_VERSION/source"

# Generate module dependencies
depmod -b "/usr/lib/modules/$KERNEL_VERSION" "$KERNEL_VERSION"
```

## 🔧 **Bootloader Configuration**

### **GRUB Installation**
```bash
# Must use /usr/lib/ostree-boot as boot directory
grub-install --target=x86_64-efi \
    --efi-directory=/boot/efi \
    --boot-directory=/usr/lib/ostree-boot
```

### **Boot Directory Structure**
```
/usr/lib/ostree-boot/
├── grub/
│   ├── grub.cfg
│   └── grubenv
└── [other boot files]
```

## 📦 **Required Packages**

### **Base OSTree Packages**
- `ostree` - Core OSTree functionality
- `ostree-boot` - Boot integration
- `ostree-grub2` - GRUB2 integration

### **Kernel Packages**
- `linux-image-amd64` - Kernel image
- `linux-headers-amd64` - Kernel headers

### **Bootloader Packages**
- `grub-efi-amd64` - EFI GRUB2
- `efibootmgr` - EFI boot manager

## 🚫 **Common Mistakes to Avoid**

### **1. Generic Kernel References**
```bash
# ❌ WRONG - Don't use uname -r
ln -sf /usr/src/linux-headers-$(uname -r) /usr/lib/modules/$(uname -r)/build

# ✅ CORRECT - Use package version
KERNEL_VERSION=$(dpkg-query -W -f='${Version}' linux-image-amd64 | sed 's/-.*//')
ln -sf "/usr/src/linux-headers-$KERNEL_VERSION" "/usr/lib/modules/$KERNEL_VERSION/build"
```

### **2. Wrong Boot Directory**
```bash
# ❌ WRONG - Don't use /boot/grub
grub-install --boot-directory=/boot/grub

# ✅ CORRECT - Use OSTree boot directory
grub-install --boot-directory=/usr/lib/ostree-boot
```

### **3. Missing OSTree Structure**
```bash
# ❌ WRONG - Don't skip OSTree directories
mkdir -p /boot /usr/lib/modules

# ✅ CORRECT - Create complete OSTree structure
mkdir -p /ostree /sysroot /usr/lib/ostree-boot /usr/lib/modules /usr/lib/kernel
```

## 🔍 **Validation Commands**

### **Check OSTree Structure**
```bash
# Verify required directories exist
ls -la /ostree /sysroot /usr/lib/ostree-boot /usr/lib/modules /usr/lib/kernel

# Check OSTree configuration
cat /etc/ostree/ostree.conf

# Verify kernel modules
ls -la /usr/lib/modules/
ls -la /usr/lib/kernel/
```

### **Check Bootloader**
```bash
# Verify GRUB installation
ls -la /usr/lib/ostree-boot/grub/

# Check EFI setup
ls -la /boot/efi/
```

### **Test OSTree Functionality**
```bash
# Basic OSTree commands
ostree --version
ostree admin status
ostree admin os-diff
```

## 📚 **References**

- [OSTree Documentation](https://ostreedev.github.io/ostree/)
- [Fedora CoreOS OSTree Guide](https://docs.fedoraproject.org/en-US/fedora-coreos/)
- [ublue-os OSTree Integration](https://github.com/ublue-os/main)

## ⚠️ **Important Notes**

1. **OSTree is strict** about filesystem structure and naming
2. **Kernel versions must match exactly** between packages and modules
3. **Bootloader must use OSTree-specific directories**
4. **All labels and metadata must be properly set**
5. **Testing is critical** - validate each step before proceeding

Following these requirements ensures that Particle-OS images will be properly recognized and managed by OSTree systems.