debian-atomic/docs/bootable-atomic.md

# Making Debian Atomic Bootable: A Comprehensive Guide

## Table of Contents
1. [Overview](#overview)
2. [Core Technologies](#core-technologies)
3. [Two Paths to Bootability](#two-paths-to-bootability)
4. [OSTree Architecture](#ostree-architecture)
5. [Boot Process Deep Dive](#boot-process-deep-dive)
6. [Installation Methods](#installation-methods)
7. [Update and Rollback](#update-and-rollback)
8. [Debian-Specific Considerations](#debian-specific-considerations)
9. [Testing and Validation](#testing-and-validation)
10. [Troubleshooting](#troubleshooting)
11. [Advanced Topics](#advanced-topics)
12. [References and Further Reading](#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:

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

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

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

```bash
# 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:
```bash
# Check for updates
bootc upgrade --check

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

# Reboot to apply
reboot
```

#### apt-ostree approach:
```bash
# 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:

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

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

```yaml
# 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](https://ostreedev.github.io/ostree/)
- [Fedora Atomic Documentation](https://docs.fedoraproject.org/en-US/fedora-coreos/)
- [bootc Documentation](https://github.com/containers/bootc)

### 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](https://lists.fedoraproject.org/archives/list/atomic@lists.fedoraproject.org/)
- [OSTree IRC Channel](irc://irc.freenode.net/#ostree)
- [Debian Atomic Project](https://git.raines.xyz/particle-os/debian-atomic)

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