Debian Atomic Infrastructure Files

This directory contains the missing 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.

📁 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 critical 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 28+ systemd services are required for a functional OSTree system, and Debian packages are missing most of them.

📦 Package Structure

1. ostree-systemd Package

Purpose: Provides essential OSTree systemd services and configuration files.

Files:

• systemd/system/ostree-prepare-root.service - Handles OSTree deployment during initramfs
• systemd/system/ostree-remount.service - Manages OSTree bind mounts after boot
• systemd/system/ostree-state-overlay@.service - Template for OSTree state overlays
• systemd/system/ostree-finalize-staged.service - Finalizes staged deployments
• systemd/system/ostree-finalize-staged-hold.service - Prevents finalization conflicts
• systemd/system/ostree-boot-complete.service - Completes boot process
• ostree/prepare-root.conf - OSTree configuration (composefs, readonly sysroot)
• tmpfiles.d/ostree-tmpfiles.conf - Runtime directory creation and cleanup

Installation Path: /usr/lib/systemd/system/, /usr/lib/ostree/, /usr/lib/tmpfiles.d/

2. 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/

3. 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/

4. 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.

5. ostree-dracut Package

Purpose: Provides OSTree dracut module for initramfs integration.

Files:

• modules.d/98ostree/module-setup.sh - OSTree dracut module setup script

Installation Path: /usr/lib/dracut/modules.d/98ostree/

🔧 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

📋 Next Steps

1. Create Debian packages from these files
2. Test package installation on Debian system
3. Build Debian Atomic container with apt-ostree
4. Test with bootc-image-builder to create bootable image
5. Boot test the resulting image

🔍 Key Insights

The problem was not in the build process - bootc-image-builder works fine. The problem was missing package infrastructure in Debian. These files provide the missing systemd services, configuration files, and hooks that make OSTree work properly.

This approach is much more manageable than initially thought - we just need to package these files and install them, then use the existing proven build process.