# 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