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

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.

License

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