debian-atomic/docs/bootable-atomic.md

Making Debian Atomic Bootable: A Comprehensive Guide

Table of Contents

1. Overview
2. Core Technologies
3. Two Paths to Bootability
4. OSTree Architecture
5. Boot Process Deep Dive
6. Installation Methods
7. Update and Rollback
8. Debian-Specific Considerations
9. Testing and Validation
10. Troubleshooting
11. Advanced Topics
12. References and Further Reading

Overview

Debian Atomic aims to provide the same atomic update capabilities as Fedora Atomic, but adapted for the Debian ecosystem. The core challenge is transforming a collection of Debian packages and configurations into a bootable, immutable system that can be updated atomically.

This document explores the technical foundations, implementation approaches, and practical considerations for making Debian Atomic systems bootable.

Core Technologies

OSTree: The Foundation

OSTree is a system for managing bootable, versioned filesystem trees. Think of it as "Git for your operating system":

• Immutable base: The entire /usr filesystem is stored as an OSTree commit
• Atomic operations: Updates either succeed completely or fail completely
• Efficient storage: Files are deduplicated across versions
• Rollback capability: Can instantly switch to previous versions

Key OSTree Concepts

• Repository: Stores all filesystem trees and metadata
• Commit: A specific version of the filesystem
• Deployment: An installed, bootable version
• Branch: A named reference to a commit (e.g., debian-atomic/stable)

Two Paths to Bootability

Fedora Atomic provides two distinct approaches to creating bootable systems:

Path 1: Traditional rpm-ostree

What it does: Composes bootable systems directly from package lists How it works: Installs RPM packages into OSTree trees and manages them natively Advantages: Direct package control, mature tooling, fine-grained customization Disadvantages: Fedora-specific, requires understanding of OSTree internals

Path 2: Modern bootc

What it does: Converts OCI containers into bootable systems How it works: Extracts container images and commits them to OSTree Advantages: Simpler workflow, container-native, cross-platform compatibility Disadvantages: Less direct package control, newer tooling

OSTree Architecture

Filesystem Structure

/
├── ostree/                    # OSTree repository
│   ├── repo/                 # Git-like repository
│   └── deploy/               # Deployed systems
│       ├── debian-atomic/    # Current deployment
│       └── debian-atomic.0/  # Previous deployment
├── boot/                     # Bootloader files
│   ├── grub2/               # GRUB2 configuration
│   └── ostree/              # OSTree boot files
├── usr/                      # Immutable system (OSTree)
├── var/                      # Writable data
│   ├── lib/                  # Application data
│   ├── log/                  # System logs
│   └── tmp/                  # Temporary files
└── home/                     # User data

Key Characteristics

• /usr is read-only: Immutable system files managed by OSTree
• /var is writable: Logs, databases, and application data
• /home is writable: User data and configurations
• OSTree manages deployments: Multiple versions can coexist

Boot Process Deep Dive

1. Bootloader Phase

GRUB2 loads with OSTree-specific configuration:

# Example GRUB2 configuration
menuentry 'Debian Atomic' {
    linux /boot/vmlinuz root=ostree:/ostree/boot-1/debian-atomic/0
    initrd /boot/initramfs.img
}

2. Initramfs Phase

The initramfs:

• Mounts the OSTree repository
• Sets up the immutable /usr filesystem
• Prepares writable directories (/var, /home)
• Transitions to systemd

3. System Boot

Systemd starts with:

• /usr mounted as read-only from OSTree
• /var and /home as writable overlays
• OSTree deployment tracking enabled

Installation Methods

Understanding the Bootable System Creation

There are two fundamentally different approaches to creating bootable Debian Atomic systems:

Approach A: Live Installation (bootc install)

• What it does: Converts an existing running system to boot from OSTree
• Output: Bootable system on existing hardware
• Use case: Converting existing Debian systems to Atomic
• Limitation: Requires existing running system

Approach B: Image Creation (bootc-image-builder)

• What it does: Creates bootable disk images from containers
• Output: ISO files, raw disk images, cloud images
• Use case: Creating installable media, cloud deployments, new hardware
• Advantage: Can create bootable media from scratch

Method 1: bootc install (Live Installation)

Prerequisites: Container image, bootc tool, target system with existing OS Process: Extracts container and commits to OSTree on the target system

# Build container image
podman build -t debian-atomic:latest .

# Install to system (requires running system)
bootc install debian-atomic:latest

# System becomes bootable
reboot

What happens internally:

1. Container image is pulled and extracted
2. Filesystem tree is committed to OSTree repository on the target system
3. GRUB2 is configured to boot from OSTree instead of traditional filesystem
4. System becomes bootable from OSTree deployment
5. No disk image is created - the system boots directly from OSTree

Important: This method requires an existing running system to install onto. It doesn't create a bootable disk image.

Method 2: apt-ostree compose

Prerequisites: Treefile (YAML), apt-ostree tool Process: Composes system from package lists

# Compose system from treefile
apt-ostree compose tree debian-atomic.yaml

# Deploy to system
apt-ostree deploy debian-atomic:latest

# System becomes bootable
reboot

What happens internally:

1. Package list is resolved and downloaded
2. Packages are installed into OSTree tree
3. Tree is committed to repository
4. System is deployed and made bootable

Method 3: bootc-image-builder (Image Creation)

Prerequisites: Container image, bootc-image-builder tool Process: Creates bootable disk images from containers

# Build container image
podman build -t debian-atomic:latest .

# Create bootable ISO
bootc-image-builder --type iso debian-atomic:latest

# Create bootable raw disk image
bootc-image-builder --type raw debian-atomic:latest

# Create cloud image
bootc-image-builder --type qcow2 debian-atomic:latest

What happens internally:

1. Container image is extracted and analyzed
2. OSTree tree is created from container
3. Bootloader (GRUB2) is configured for the target format
4. Initramfs is generated with OSTree support
5. Bootable disk image is created - can be written to media or deployed to cloud

Choosing the Right Method

Method	Use When	Output	Requirements
bootc install	Converting existing system	Bootable system on hardware	Running system, bootc tool
apt-ostree compose	Building from packages	Bootable system on hardware	Package lists, apt-ostree tool
bootc-image-builder	Creating installable media	ISO, raw disk, cloud images	Container image, bootc-image-builder tool

Key Insight: No Traditional "Disk Image" in Live Installation

Important distinction: When using bootc install or apt-ostree compose, you're not creating a disk image file. Instead:

• The system boots directly from the OSTree-managed filesystem
• The existing disk becomes the OSTree repository
• GRUB2 is configured to boot from OSTree instead of traditional filesystem
• The system itself becomes the "bootable image"

This is fundamentally different from traditional OS installation where you create an ISO or disk image file.

Update and Rollback

Update Process

bootc approach:

# Check for updates
bootc upgrade --check

# Pull and stage update
bootc upgrade debian-atomic:v2

# Reboot to apply
reboot

apt-ostree approach:

# Check for updates
apt-ostree upgrade --check

# Pull and stage update
apt-ostree upgrade

# Reboot to apply
reboot

Rollback Process

Both approaches support instant rollbacks:

# List deployments
bootc status
# or
apt-ostree status

# Rollback to previous version
bootc rollback
# or
apt-ostree rollback

# Reboot to apply rollback
reboot

Debian-Specific Considerations

Package Management Differences

Aspect	Fedora	Debian
Package format	.rpm	.deb
Package manager	rpm-ostree	apt-ostree
Repository structure	Different	Different
Configuration files	Different locations	Different locations

System Service Differences

• Service names: Different systemd service names
• Configuration paths: Different default locations
• Dependencies: Different package dependencies
• Security policies: Different default security frameworks

Filesystem Layout

Debian uses different default paths:

• Package data: /var/lib/dpkg/ vs /var/lib/rpm/
• Configuration: /etc/apt/ vs /etc/yum/
• Cache: /var/cache/apt/ vs /var/cache/yum/

Testing and Validation

Pre-Installation Testing

1. Container validation: Test container builds and functionality
2. Package compatibility: Verify all packages work together
3. Service integration: Test systemd service functionality
4. Dependency resolution: Ensure all dependencies are satisfied

Installation Testing

1. bootc install: Test container-to-OSTree conversion
2. apt-ostree compose: Test package-to-OSTree composition
3. Boot process: Verify system boots correctly
4. Service startup: Ensure all services start properly

Post-Installation Testing

1. Update process: Test upgrade functionality
2. Rollback process: Test rollback functionality
3. Performance: Compare with traditional Debian
4. Compatibility: Test with existing Debian tools

Troubleshooting

Common Issues

bootc Issues

• Container extraction failures: Check container image integrity
• OSTree commit failures: Verify disk space and permissions
• Bootloader configuration: Check GRUB2 configuration
• Permission issues: Ensure proper file ownership

apt-ostree Issues

• Package resolution: Check package availability and dependencies
• Installation failures: Verify package integrity and conflicts
• OSTree composition: Check treefile syntax and validity
• Deployment failures: Verify system requirements

Debugging Tools

# OSTree debugging
ostree log debian-atomic
ostree show debian-atomic
ostree refs

# System debugging
journalctl -b
systemctl status
bootc status
apt-ostree status

# Filesystem debugging
ls -la /ostree/
mount | grep ostree

Advanced Topics

Custom OSTree Compositions

Advanced users can create custom OSTree compositions:

# Example custom treefile
include: debian-atomic.yaml

packages:
  - custom-package
  - another-package

remove-packages:
  - unwanted-package

customizations:
  - path: /etc/custom.conf
    content: |
      [custom]
      setting = value

Multi-Architecture Support

OSTree supports multiple architectures:

• amd64: Standard x86_64 systems
• arm64: ARM 64-bit systems
• ppc64le: PowerPC 64-bit little-endian
• s390x: IBM S390x systems

Network Boot Support

OSTree can boot from network repositories:

• HTTP/HTTPS: Standard web protocols
• NFS: Network file system
• Custom protocols: Extensible transport layer

References and Further Reading

Official Documentation

• OSTree Documentation
• Fedora Atomic Documentation
• bootc Documentation

Technical Papers

• "OSTree: A Git-like model for operating system deployment"
• "Atomic Updates: A Foundation for Reliable System Updates"

Community Resources

• Fedora Atomic Mailing List
• OSTree IRC Channel
• Debian Atomic Project

Related Projects

• Fedora Atomic: The reference implementation
• Ubuntu Core: Canonical's atomic Ubuntu variant
• NixOS: Functional package management approach
• Guix: GNU's functional package manager

---

Conclusion

Making Debian Atomic bootable requires understanding the interplay between OSTree, bootc, and apt-ostree. The system provides two complementary approaches: the modern container-based bootc method and the traditional package-based apt-ostree method.

Success depends on careful testing, understanding Debian-specific differences, and leveraging the mature OSTree infrastructure that powers Fedora Atomic. The result is a system that combines Debian's stability and package ecosystem with the reliability and atomicity of modern immutable operating systems.

The journey from container images or package lists to a bootable, atomic-updatable system is complex but rewarding, providing a foundation for reliable, maintainable Debian-based systems.