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.