debian-atomic-system-files/README.md

# 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
```bash
# 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
```bash
# 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
```bash
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.