robojerk/particle-os
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
particle-os/OSTREE_REQUIREMENTS.md
robojerk f9fb8d3bd0 Fix critical PATH issues and add related projects to README 
- Fixed sfdisk PATH issue in Containerfile.base (sfdisk is in /usr/sbin)
- Updated Containerfile.minimal to use full path for grub-install
- Enhanced test-bootc-deployment.sh to properly check utility locations
- Added comprehensive section about related projects (apt-ostree, deb-bootupd, debian-bootc-corrected)
- Updated validation script to handle Debian-specific utility locations
- Improved error messages with specific solutions for PATH and utility issues

This addresses the critical requirements from scope.md regarding disk utilities
and PATH environment variables for bootc deployment.
2025-08-10 18:15:04 -07:00

5.4 KiB
Raw Permalink Blame History

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

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

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

# 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

# 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

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

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

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

# 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

# Verify GRUB installation
ls -la /usr/lib/ostree-boot/grub/

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

Test OSTree Functionality

# Basic OSTree commands
ostree --version
ostree admin status
ostree admin os-diff

📚 References

⚠️ 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.