particle-os/debian-atomic-system-files
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
debian-atomic-system-files/README.md
robojerk 6a8134be49 Update README: Major discovery - Debian already has most OSTree infrastructure 
- Debian ostree-boot package provides 6/6 core OSTree systemd services
- Includes dracut integration, tmpfiles config, and GRUB integration
- Reduces scope from 35 files to ~15 files (57% reduction)
- Only need to create bootc and apt-ostree specific infrastructure
- Updated implementation strategy with 3 phases
- Added scope reduction summary and key insights
2025-09-01 17:11:14 -07:00

11 KiB
Raw Blame History

Debian Atomic Infrastructure Files

This directory contains the additional systemd services, configuration files, and infrastructure components needed to make Debian work with OSTree and bootc-image-builder, based on our analysis of the successful Fedora Atomic system.

🎉 Major Discovery: Debian Already Has Most OSTree Infrastructure!

After examining the ostree-boot package in Debian, we discovered that Debian already provides 6 of the 6 core OSTree systemd services plus dracut integration! This significantly reduces what we need to create.

📁 Directory Structure

debian-atomic-files/
├── ostree-systemd/           # OSTree systemd services and configuration
├── bootc/                    # Bootc systemd services and infrastructure
├── apt-ostree-systemd/       # APT-OSTree systemd services and kernel hooks
├── ostree-dracut/           # OSTree dracut module
└── README.md                # This file

🎯 Purpose

These files address the remaining missing infrastructure that prevents Debian from working with OSTree and bootc-image-builder. Based on our analysis of the successful Fedora Atomic system, we discovered that while Debian already has the core OSTree services, it's missing the bootc and apt-ostree specific infrastructure.

✅ What's Already Available in Debian

ostree-boot Package (Install with: apt install ostree-boot)

Already Provides:

  • ✅ ostree-prepare-root.service - Prepare root filesystem in initramfs
  • ✅ ostree-remount.service - Remount filesystem with overlays
  • ✅ ostree-state-overlay@.service - State overlay management
  • ✅ ostree-finalize-staged.service - Finalize staged deployments
  • ✅ ostree-finalize-staged-hold.service - Hold service for finalization
  • ✅ ostree-boot-complete.service - Boot completion service
  • ✅ 98ostree/module-setup.sh - OSTree dracut module (includes erofs, overlay)
  • ✅ ostree.conf - Dracut configuration (adds ostree + systemd modules)
  • ✅ ostree-tmpfiles.conf - Runtime directory creation and cleanup
  • ✅ ostree-prepare-root - Binary executable
  • ✅ ostree-remount - Binary executable
  • ✅ grub2-15_ostree - GRUB integration script
  • ✅ ostree-system-generator - Systemd system generator

This covers 6/6 core OSTree systemd services!

📦 What We Still Need to Create

1. bootc Package

Purpose: Provides bootc infrastructure for automatic updates, filesystem growth, and cleanup.

Files:

  • systemd/system/bootc-fetch-apply-updates.service - Automatic updates service
  • systemd/system/bootc-fetch-apply-updates.timer - Timer for automatic updates (1h after boot, then every 8h)
  • systemd/system/bootc-generic-growpart.service - Auto-grow root filesystem on VMs
  • systemd/system/bootc-destructive-cleanup.service - Cleanup after installations
  • systemd/system/bootc-publish-rhsm-facts.service - Publish facts to subscription manager
  • systemd/system/bootc-status-updated.target - Status coordination target
  • systemd/system/bootc-status-updated-onboot.target - Boot status target
  • systemd/system/bootc-root-setup.service - Bootc root setup in initramfs

Installation Path: /usr/lib/systemd/system/

2. bootc-dracut Package

Purpose: Provides bootc dracut configuration for initramfs generation.

Files:

  • usr/lib/dracut.conf.d/10-bootc-base.conf - Bootc dracut configuration (hostonly=no, add ostree module)

Installation Path: /usr/lib/dracut.conf.d/

3. apt-ostree Package (Enhanced)

Purpose: APT-OSTree package should include all systemd services and kernel installation hooks (like rpm-ostree does).

Files:

  • systemd/system/apt-ostreed.service - APT-OSTree system management daemon
  • systemd/system/apt-ostree-bootstatus.service - Log boot status to journal
  • systemd/system/apt-ostree-countme.service - Analytics reporting service
  • systemd/system/apt-ostree-countme.timer - Weekly analytics timer
  • systemd/system/apt-ostree-fix-shadow-mode.service - Fix shadow permissions
  • systemd/system/apt-ostreed-automatic.service - Automatic updates service
  • systemd/system/apt-ostreed-automatic.timer - Automatic updates timer
  • kernel/install.d/05-aptostree.install - Kernel installation hook for OSTree
  • kernel/install.conf - Kernel install configuration (layout=ostree)
  • tmpfiles.d/apt-ostree-0-integration.conf - APT-OSTree tmpfiles integration
  • tmpfiles.d/apt-ostree-0-integration-opt-usrlocal.conf - /usr/local and /opt directory setup
  • tmpfiles.d/apt-ostree-0-integration-opt-usrlocal-compat.conf - Backwards compatibility for /usr/local
  • apt-ostreed.conf - APT-OSTree daemon configuration
  • org.debian.aptostree1.conf - D-Bus policy configuration

Installation Path: /usr/lib/systemd/system/, /usr/lib/kernel/install.d/, /usr/lib/kernel/, /usr/lib/tmpfiles.d/, /etc/, /usr/share/dbus-1/system.d/

Note: These files should be bundled with the apt-ostree package itself, not as a separate package.

4. Missing Configuration Files

Purpose: Additional configuration files needed for complete OSTree integration.

Files:

  • ostree/prepare-root.conf - OSTree configuration (composefs, readonly sysroot) - Note: May need to be added to ostree-boot package
  • kernel/install.conf - Kernel install configuration (layout=ostree) - Note: May need to be added to ostree-boot package

Installation Path: /usr/lib/ostree/, /usr/lib/kernel/

Note: The OSTree dracut module is already provided by the ostree-boot package.

🔧 What Each File Does

OSTree Systemd Services

ostree-prepare-root.service:

  • Purpose: Handles OSTree deployment during initramfs phase
  • Function: Runs /usr/lib/ostree/ostree-prepare-root /sysroot
  • Timing: After sysroot.mount, before initrd-root-fs.target
  • Critical: This is what makes OSTree deployment work during boot

ostree-remount.service:

  • Purpose: Handles OSTree bind mounts after boot
  • Function: Runs /usr/lib/ostree/ostree-remount binary
  • Timing: After var.mount, before local-fs.target
  • Critical: Manages overlay filesystems for /etc, /var, etc.

ostree-state-overlay@.service:

  • Purpose: Template service for OSTree state overlays
  • Function: Runs ostree admin state-overlay %i /%I
  • Critical: Enables writable overlays on read-only OSTree deployments

ostree-finalize-staged.service:

  • Purpose: Finalizes staged deployments
  • Function: Runs ostree admin finalize-staged on service stop
  • Timing: After local-fs.target, before basic.target
  • Critical: Required for proper deployment finalization

ostree-boot-complete.service:

  • Purpose: Completes boot process and handles soft-reboot cleanup
  • Function: Runs ostree admin boot-complete
  • Timing: After sysinit.target, before ostree-finalize-staged.service
  • Critical: Handles boot completion and cleanup

Bootc Systemd Services

bootc-fetch-apply-updates.service + .timer:

  • Purpose: Automatic updates via bootc upgrade --apply --quiet
  • Timer: Runs 1h after boot, then every 8h with 2h randomization
  • Critical: Provides automatic update functionality

bootc-generic-growpart.service:

  • Purpose: Automatically grow root filesystem on VMs
  • Function: Runs /usr/libexec/bootc-generic-growpart
  • Condition: Only runs on VMs with /sysroot mounted
  • Critical: Handles filesystem growth automatically

bootc-destructive-cleanup.service:

  • Purpose: Cleanup after alongside installation
  • Function: Runs /usr/lib/bootc/fedora-bootc-destructive-cleanup
  • Critical: Cleans up after destructive operations

APT-OSTree Services

apt-ostreed.service:

  • Purpose: APT-OSTree system management daemon
  • Type: DBus service (org.debian.aptostree1)
  • Function: Runs apt-ostree start-daemon
  • Critical: Provides system management API

apt-ostree-bootstatus.service:

  • Purpose: Log booted deployment status to journal
  • Function: Runs apt-ostree status -b
  • Critical: Provides boot status logging

Kernel Installation Hooks

05-aptostree.install:

  • Purpose: OSTree-aware kernel installation hook
  • Function: Delegates to apt-ostree kernel-install for OSTree systems
  • Critical: Ensures proper kernel installation in OSTree environment

install.conf:

  • Purpose: Kernel install configuration
  • Content: layout=ostree
  • Critical: Tells kernel-install to use OSTree-specific hooks

Dracut Module

98ostree/module-setup.sh:

  • Purpose: OSTree dracut module for initramfs
  • Function: Installs OSTree binaries and services into initramfs
  • Critical: Required for OSTree integration in initramfs

🚀 Implementation Strategy

Phase 1: Create Debian Packages

  1. ostree-systemd - Essential OSTree services
  2. bootc - Bootc infrastructure
  3. ostree-dracut - Dracut module
  4. apt-ostree - Enhanced with systemd services and kernel hooks

Phase 2: Package Installation

# Install the packages
sudo dpkg -i ostree-systemd_*.deb
sudo dpkg -i bootc_*.deb
sudo dpkg -i ostree-dracut_*.deb
sudo dpkg -i apt-ostree_*.deb  # Enhanced with systemd services

Phase 3: Test with bootc-image-builder

# Use existing bootc-image-builder with Debian container
bootc-image-builder build --config debian-atomic.yaml

🎯 Expected Results

After installing these packages, Debian should have:

  • ✅ Complete OSTree infrastructure (28+ systemd services)
  • ✅ Proper kernel installation hooks for OSTree
  • ✅ Dracut integration for initramfs
  • ✅ Automatic update functionality via bootc
  • ✅ Filesystem growth and cleanup capabilities
  • ✅ Compatibility with bootc-image-builder

🚀 Revised Implementation Strategy

Phase 1: Install Existing Infrastructure

apt install ostree-boot  # Provides 6/6 core OSTree systemd services + dracut integration

Phase 2: Create Missing Packages

  1. Create bootc package - 8 systemd services + dracut config
  2. Enhance apt-ostree package - 7 systemd services + kernel hooks + configs
  3. Add missing config files - prepare-root.conf, install.conf (may need ostree-boot package updates)

Phase 3: Test Complete System

  1. Test with bootc-image-builder using a Debian container
  2. Build and boot a complete Debian Atomic system
  3. Iterate and improve based on testing results

📊 Scope Reduction Summary

Original Assessment: 35 files needed (6 OSTree + 8 bootc + 7 apt-ostree + 14 configs)

Revised Assessment: ~15 files needed (8 bootc + 7 apt-ostree + 2 configs)

Reduction: ~57% fewer files needed thanks to existing ostree-boot package!

🔍 Key Insights

Major Discovery: Debian already has 6/6 core OSTree systemd services in ostree-boot package!

The problem was not in the build process - bootc-image-builder works fine. The problem was missing bootc and apt-ostree specific infrastructure in Debian.

This approach is much more manageable than initially thought - we just need to create the missing bootc and apt-ostree packages, then use the existing proven build process.