Debian Atomic Desktop Project

A project to create a Debian-based atomic desktop system using bootc and OSTree, inspired by ublue-os.

Project Structure

This project is organized into phases:

Phase 1: 01-debian-atomic/ ✅ Complete

• Goal: Create a minimal, bootable Debian Trixie atomic image
• Status: ✅ Complete
• Contents:
  • Containerfile - Defines the base atomic image
  • justfile - Build automation
  • README.md - Phase 1 documentation

Phase 2: 02-installer/ 🔄 In Progress

• Goal: Create a bootable ISO with Calamares installer using live-build
• Status: 🔄 In Progress (Contents file issues being resolved)
• Contents:
  • justfile - Live-build automation
  • calamares/ - Installer configuration
  • config/ - Live-build configuration
  • scripts/ - Helper scripts

Phase 2 Alternative: 02-installer-bootc/ 🔄 In Progress

• Goal: Modern approach using bootc + Calamares (Recommended)
• Status: 🔄 In Progress
• Contents:
  • Containerfile - Bootc container definition
  • justfile - Container build automation
  • scripts/ - Testing scripts

🚀 BREAKTHROUGH: bootc-image-builder Integration

Phase 1 Complete + Advanced Integration Opportunity Discovered

We have successfully completed Phase 1 (minimal bootable Debian atomic image) and discovered an existing advanced bootc-image-builder project with professional-grade infrastructure:

✅ Phase 1 Achievements

• ✅ Valid bootc Container: Passes all bootc container lint validation
• ✅ Complete Disk Utilities: All partitioning and filesystem tools working
• ✅ Kernel Integration: Linux kernel properly detected and accessible
• ✅ OSTree Structure: Proper atomic filesystem layout validated
• ✅ Deployment Testing: Core functionality verified and working

🎯 Integration Opportunity

• ✅ Advanced Project Found: bootc-image-builder with Phase 4.2 complete
• ✅ Professional Infrastructure: 100% test coverage, performance optimization
• ✅ Production Ready: Comprehensive osbuild stages, Go integration
• ✅ Multiple Formats: QCOW2, ISO, RAW artifact generation
• 🚀 Perfect Timing: particle-os foundation ready for professional deployment

🔗 Next Steps

1. Locate/Clone the advanced bootc-image-builder project
2. Test Integration with our validated particle-os image
3. Generate Artifacts using professional deployment pipeline
4. Document Workflow for unified particle-os + bootc-image-builder process

Critical Prerequisites: Disk Utilities for bootc Deployment

⚠️ CRITICAL REQUIREMENT: Successful deployment using bootc install to-disk requires specific disk utilities that are often missing from minimal environments.

Essential Disk Utilities

The following utilities must be available in your deployment environment:

• sfdisk (from util-linux) - CRITICAL for automated partitioning
• parted - Alternative partitioning tool
• mkfs.ext4 (from e2fsprogs) - Filesystem creation
• mkfs.fat (from dosfstools) - FAT32 filesystem for EFI
• grub-install - Bootloader installation
• efibootmgr - UEFI boot manager

Installation and Verification

# Install required utilities
sudo apt update
sudo apt install -y util-linux parted e2fsprogs dosfstools grub-efi-amd64 efibootmgr

# Verify availability (all should return paths)
which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr

# Test sfdisk functionality
sfdisk --version

Common Failure Points

• error: Installing to disk: Creating rootfs: Failed to run sfdisk: No such file or directory
• Missing filesystem creation tools
• Incomplete bootloader installation utilities

Troubleshooting: PATH Issues in Minimal Environments

Common Issue: sfdisk exists but isn't found due to incomplete PATH in minimal environments.

Diagnosis:

# Check if util-linux is installed
dpkg -l | grep util-linux

# Find sfdisk location
find / -name sfdisk 2>/dev/null

# Check current PATH
echo $PATH

# Test sfdisk directly
/usr/sbin/sfdisk --version

Solution:

# Fix PATH and run bootc
sudo env PATH="/usr/sbin:/sbin:/usr/local/bin:/usr/bin:/bin" \
  podman run --rm --privileged --pid=host --volume /dev:/dev \
  localhost/debian-atomic:latest /usr/bin/bootc install to-disk /dev/target-device

Note: This requirement affects all phases and deployment scenarios. See scope.md for detailed implementation guidance.

Quick Start

1. Verify Prerequisites (Critical):

   # Ensure disk utilities are available
   which sfdisk parted mkfs.ext4 mkfs.fat grub-install efibootmgr
   sfdisk --version
   

2. Phase 1 (Atomic Image):

   cd 01-debian-atomic
   just build-image
   just test-image
   

3. Phase 2 (Traditional live-build approach):

   cd 02-installer
   just build-iso
   

4. Phase 2 Alternative (Modern bootc approach - Recommended):

   cd 02-installer-bootc
   just build-installer
   just test-installer-systemd
   

Which Approach Should You Use?

For Phase 2, we recommend the bootc approach (02-installer-bootc/) because:

✅ Consistent tooling - Everything uses bootc
✅ No sysvinit conflicts - Pure systemd environment
✅ Atomic guarantees - The installer itself is atomic
✅ Simpler maintenance - One build system instead of two
✅ Modern approach - Uses container-native tooling

The traditional live-build approach (02-installer/) has many hook files and complex dependencies, which is why we created the bootc alternative.

Prerequisites

• just command runner
• podman or docker
• live-build (for Phase 2 traditional approach)
• qemu-system-x86_64 (for testing)
• CRITICAL: Complete disk utilities (util-linux, parted, e2fsprogs, dosfstools, grub-efi-amd64, efibootmgr)

Performance Optimization

To speed up builds, use apt-cacher-ng:

# Set up apt-cacher-ng
./scripts/setup-apt-cacher.sh

# Then edit the justfile to enable the proxy
# In 02-installer/justfile, uncomment APT_CACHER_NG_PROXY

Development

See roadmap.md for detailed project planning and todo for current tasks.

Working Commands

See WORKING_COMMANDS.md for a comprehensive list of all tested and validated commands used throughout the project. This includes:

• Building and validating atomic images
• Testing bootc deployment methods
• Container management operations
• Troubleshooting commands
• Critical environment variables and requirements

All commands in WORKING_COMMANDS.md have been tested and validated.

License

This project is open source. See individual files for specific licensing information.