apt-ostree/docs/architecture/overview.md

apt-ostree Architecture Overview

Project Organization

Directory Structure

The apt-ostree project follows a well-organized structure designed for maintainability and clarity:

apt-ostree/
├── src/                          # Source code
│   ├── main.rs                   # CLI application entry point
│   ├── lib.rs                    # Library interface
│   ├── apt.rs                    # APT package management
│   ├── ostree.rs                 # OSTree operations
│   ├── system.rs                 # System integration
│   ├── package_manager.rs        # High-level package operations
│   ├── ostree_detection.rs       # Environment detection
│   ├── permissions.rs            # Permission handling
│   ├── error.rs                  # Error types
│   ├── bin/                      # Binary applications
│   │   ├── apt-ostreed.rs        # D-Bus daemon
│   │   └── test_runner.rs        # Test runner
│   └── daemon/                   # Daemon and service files
├── docs/                         # Documentation
│   ├── architecture/             # Architecture documentation
│   ├── development/              # Development guides
│   └── user-guide/               # User documentation
├── scripts/                      # Scripts
│   ├── testing/                  # Test scripts
│   └── daemon/                   # Daemon management scripts
├── tests/                        # Test files
├── .notes/                       # Research and planning notes
├── Cargo.toml                    # Project configuration
└── README.md                     # Project overview

Key Design Decisions

• Modular Architecture: Each component is self-contained with clear interfaces
• Separation of Concerns: CLI, daemon, and library code are clearly separated
• Documentation-First: Comprehensive documentation for all components
• Testing Infrastructure: Dedicated testing framework and utilities
• Research Integration: Planning and research notes preserved for reference

Introduction

apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree, providing a hybrid image/package system that combines APT package management with OSTree's atomic, immutable deployment model.

Core Design Principles

1. "From Scratch" Philosophy

Every change regenerates the target filesystem completely, avoiding hysteresis and ensuring reproducible results.

2. Atomic Operations

All changes are atomic with proper rollback support, ensuring no partial states.

3. Immutable Base + Layered Packages

• Base image remains unchanged
• User packages layered on top
• Clear separation of concerns

Architecture Components

Core Modules

APT Manager (src/apt.rs)

• Package management using libapt-pkg
• Repository management and metadata handling
• Package downloading and dependency resolution

OSTree Manager (src/ostree.rs)

• Deployment management and filesystem operations
• Repository operations and commit management
• Boot configuration management

System Integration (src/system.rs)

• Coordination between APT and OSTree
• High-level system operations
• Transaction management and rollback

Package Manager (src/package_manager.rs)

• High-level package operations
• Atomic transaction handling
• State synchronization

OSTree Detection (src/ostree_detection.rs)

• Environment detection and validation
• Multiple detection methods
• Error handling for non-OSTree environments

Integration Modules

APT-OSTree Integration (src/apt_ostree_integration.rs)

• Bridge between APT and OSTree systems
• Package conversion and metadata handling
• Filesystem layout management

Filesystem Assembly (src/filesystem_assembly.rs)

• "From scratch" filesystem regeneration
• Hardlink optimization for content deduplication
• Proper layering order for packages

Dependency Resolver (src/dependency_resolver.rs)

• Package dependency resolution
• Topological sorting for layering
• Conflict detection and resolution

Script Execution (src/script_execution.rs)

• Sandboxed execution using bubblewrap
• Namespace isolation and security controls
• Rollback support for failed script execution

Bubblewrap Sandbox (src/bubblewrap_sandbox.rs)

• Security sandboxing for script execution
• Namespace isolation and capability management
• Environment variable handling

APT Database (src/apt_database.rs)

• APT database management in OSTree context
• State persistence and synchronization
• Package tracking and metadata management

OSTree Commit Manager (src/ostree_commit_manager.rs)

• OSTree commit management
• Atomic commit creation and deployment
• Layer tracking and metadata management

Support Modules

Error Handling (src/error.rs)

• Unified error types
• Error conversion and propagation
• User-friendly error messages

Permissions (src/permissions.rs)

• Root privilege checks
• Permission validation
• User-friendly error messages

Daemon Architecture

D-Bus Service (src/bin/apt-ostreed.rs)

• System service providing D-Bus interface
• Privileged operations and transaction management
• Progress reporting and cancellation support

Client Library

• D-Bus communication with daemon
• Fallback to direct system calls
• Error handling and retry logic

Data Flow

Package Installation Flow

1. Command Parsing: CLI options and package list
2. Permission Check: Root privilege validation
3. Environment Detection: OSTree environment validation
4. Package Resolution: APT dependency resolution
5. Download: Package downloading and verification
6. Extraction: DEB package extraction
7. Filesystem Assembly: "From scratch" filesystem creation
8. Script Execution: Sandboxed script execution
9. Commit Creation: Atomic OSTree commit
10. Deployment: Boot configuration update

Rollback Flow

1. State Validation: Verify rollback target
2. Transaction Start: Begin rollback transaction
3. State Restoration: Restore previous state
4. Boot Configuration: Update boot configuration
5. Transaction Commit: Complete rollback

Security Model

Script Sandboxing

• All DEB scripts run in bubblewrap sandbox
• Namespace isolation and capability management
• Seccomp profiles for system call filtering

Permission Controls

• Proper file and directory permissions
• Root privilege validation
• Environment validation

Atomic Operations

• No partial states that could be exploited
• Instant rollback capability
• Transactional updates

Performance Characteristics

Optimization Features

• Hardlink Optimization: Content deduplication for identical files
• Caching Strategies: Efficient package and metadata caching
• Parallel Processing: Async operations for better performance
• Content Addressing: SHA256-based deduplication

Expected Performance

• Package Resolution: Comparable to native APT
• Memory Usage: Reduced due to Rust's ownership system
• Deployment Speed: Optimized with OSTree's content addressing
• Error Recovery: Faster due to compile-time guarantees

Integration Points

System Integration

• systemd: Service management and boot integration
• D-Bus: Inter-process communication
• OSTree: Deployment and filesystem management
• APT: Package management and dependency resolution

External Dependencies

• bubblewrap: Script sandboxing
• libapt-pkg: APT package management
• libostree: OSTree deployment management
• zbus: D-Bus communication

Error Handling

Error Types

• AptOstreeError: Unified error type for all operations
• Permission Errors: Root privilege and access control
• Environment Errors: OSTree environment validation
• Package Errors: APT package management errors
• OSTree Errors: OSTree operation errors

Error Recovery

• Automatic Rollback: Failed operations automatically rollback
• Graceful Degradation: Fallback mechanisms for failures
• User Feedback: Clear error messages and recovery suggestions

Testing Strategy

Test Categories

• Unit Tests: Individual component testing
• Integration Tests: End-to-end workflow testing
• OSTree Integration Tests: Real OSTree repository testing
• Sandbox Testing: Bubblewrap integration validation
• Rollback Testing: Rollback functionality validation

Test Infrastructure

• Test Runner: Comprehensive test execution framework
• Test Utilities: Common test helpers and utilities
• Mock Objects: Mock implementations for testing
• Test Data: Test packages and repositories