particle-os/debian-atomic-system-files
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

first commit

Browse source
This commit is contained in:
robojerk 2025-09-01 14:05:34 -07:00
commit 93e2ad4b29
35 changed files with 1048 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

224
README.md Normal file
View file

@ -0,0 +1,224 @@
# 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
```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**
## 📋 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.