# apt-ostree Overview

## Executive Summary

apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree, providing a hybrid image/package system that combines the strengths of APT package management with OSTree's atomic, immutable deployment model. The project aims to bring the benefits of image-based deployments to the Debian/Ubuntu ecosystem.

### Core Philosophy: Every Change is "From Scratch"

apt-ostree follows the same fundamental principle as rpm-ostree: **every change regenerates the target filesystem "from scratch"**. This approach:
- Avoids hysteresis (state-dependent behavior)
- Ensures reproducible results
- Maintains system consistency
- Simplifies debugging and testing

### Key Benefits

- **Atomic Upgrades/Rollbacks**: Provides a reliable and safe way to update and revert the operating system
- **Immutable Base System**: Enhances stability and predictability
- **Reduced Update Size**: Only downloads the changes, not the entire OS
- **Client-side Customization**: Allows layering of packages and overrides for specific needs
- **Easily Create Derivatives**: Simplifies the process of creating custom OS images
- **100% CLI Compatibility**: Identical user experience to rpm-ostree

## Project Architecture

### Core Design Philosophy
- **Hybrid System**: Combines APT package management with OSTree image-based deployments
- **Atomic Operations**: All system modifications are transactional and atomic
- **Daemon-Client Architecture**: Centralized daemon with D-Bus communication
- **Rollback Capability**: Maintains previous deployments for safe rollbacks
- **Identical User Experience**: 100% CLI compatibility with rpm-ostree

## Directory Structure

```
apt-ostree/
├── src/                          # Source code
│   ├── main.rs                   # CLI application
│   ├── 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 Components

### 1. APT Manager (`src/apt.rs`)

**Purpose**: APT package management using libapt-pkg

**Key Features**:
- Real DEB package download and extraction
- APT database management in OSTree context
- Package metadata extraction from control files
- Dependency resolution using APT's native resolver
- Package script execution with Bubblewrap sandboxing

**Implementation**:
- Direct libapt-pkg integration via FFI
- OSTree-aware package installation
- Atomic transaction management
- Rollback support for failed operations

### 2. OSTree Manager (`src/ostree.rs`)

**Purpose**: OSTree deployment management and filesystem operations

**Key Features**:
- OSTree commit creation and management
- Deployment switching and rollback
- Filesystem assembly from commits and layers
- Boot configuration management
- State tracking and synchronization

**Implementation**:
- Direct libostree integration
- Atomic commit operations
- Layer management and application
- Deployment state tracking

### 3. System Integration (`src/system.rs`)

**Purpose**: Coordination between APT and OSTree systems

**Key Features**:
- APT-OSTree state synchronization
- Transaction management
- Error handling and recovery
- System state monitoring

**Implementation**:
- Coordinated package and deployment operations
- Atomic transaction handling
- Comprehensive error handling
- State consistency management

### 4. Package Manager (`src/package_manager.rs`)

**Purpose**: High-level package operations

**Key Features**:
- Package installation with atomic commits
- Package removal with rollback support
- System upgrades with automatic policies
- Package search and information display

**Implementation**:
- Integrated APT-OSTree operations
- Atomic transaction management
- User-friendly error messages
- Progress reporting

### 5. OSTree Detection (`src/ostree_detection.rs`)

**Purpose**: Environment detection and validation

**Key Features**:
- Comprehensive OSTree environment detection
- Multiple detection methods for reliability
- Clear error messages for non-OSTree systems
- Environment validation

**Implementation**:
- Filesystem detection (`/ostree` directory)
- Boot detection (`/run/ostree-booted` file)
- Kernel parameter detection (`ostree` in `/proc/cmdline`)
- Library detection (OSTree sysroot loading)
- Service detection (daemon availability)

### 6. Permissions (`src/permissions.rs`)

**Purpose**: Root privilege checks and error handling

**Key Features**:
- Robust root privilege validation
- User-friendly error messages
- Security model enforcement
- Privilege separation

**Implementation**:
- Root privilege checks for all operations
- Clear error messages for permission issues
- Security model validation
- User guidance for privilege issues

## Daemon-Client Architecture

### Daemon (`src/bin/apt-ostreed.rs`)

**Purpose**: Centralized system service for privileged operations

**Key Features**:
- D-Bus service exposing system management interface
- Privileged package and deployment operations
- Transaction management with atomicity guarantees
- Progress reporting and cancellation support

**Implementation**:
- D-Bus service registration and activation
- Method call handling and validation
- Transaction execution and management
- Error propagation and recovery

### Client (`src/main.rs`)

**Purpose**: Command-line interface for user interaction

**Key Features**:
- 100% rpm-ostree CLI compatibility
- D-Bus client communication with daemon
- Fallback to direct system calls if daemon fails
- User-friendly error messages and help

**Implementation**:
- Identical CLI interface to rpm-ostree
- D-Bus client library for daemon communication
- Fallback mechanisms for daemon failures
- Comprehensive help and error messages

## CLI Commands (100% Complete)

### Core Commands (21/21 - 100% Complete)

- **install**: Package installation with atomic commits
- **deploy**: Deployment management and switching
- **apply-live**: Live application of changes
- **cancel**: Transaction cancellation
- **cleanup**: Old deployment cleanup
- **compose**: Tree composition
- **status**: System status with rich formatting
- **upgrade**: System upgrades with automatic policies
- **rollback**: Deployment rollback
- **db**: Package database queries (diff, list, version)
- **search**: Enhanced package search
- **override**: Package overrides (replace, remove, reset, list)
- **refresh-md**: Repository metadata refresh
- **reload**: Configuration reload
- **reset**: State reset
- **rebase**: Tree switching
- **initramfs-etc**: Initramfs file management
- **usroverlay**: Transient overlayfs to /usr
- **kargs**: Kernel argument management
- **uninstall**: Package removal (alias for remove)
- **initramfs**: Initramfs management

### Command Architecture

All commands follow the same architecture:
1. **CLI Parsing**: Parse command-line arguments
2. **Daemon Communication**: Request operation via D-Bus
3. **Fallback Handling**: Use direct system calls if daemon fails
4. **Progress Reporting**: Show operation progress
5. **Result Display**: Display operation results

## D-Bus Interface

### Service Interface (`org.aptostree.dev`)

**Main Objects**:
- `/org/aptostree/dev/Sysroot`: System root management
- `/org/aptostree/dev/OS`: Operating system operations

**Key Methods**:
- `install_packages`: Install packages with atomic commits
- `remove_packages`: Remove packages with rollback support
- `upgrade_system`: Upgrade system with automatic policies
- `rollback`: Rollback to previous deployment
- `show_status`: Show system status and deployment information
- `list_packages`: List installed packages
- `search_packages`: Search for packages
- `show_package_info`: Show package information

**Transaction System**:
- All operations return transaction addresses
- Progress reporting via D-Bus signals
- Atomic execution with rollback capability
- Cancellation support

## Systemd Services

### Core Services

- **apt-ostreed.service**: Main daemon service with OSTree detection
- **apt-ostree-bootstatus.service**: Boot-time status logging
- **apt-ostreed-automatic.service**: Automatic system updates (planned)
- **apt-ostree-countme.service**: Usage reporting (planned)

### Service Configuration

- D-Bus service activation
- OSTree environment detection
- Automatic update policies
- Boot-time status reporting

## Security Model

### Privilege Separation
- Daemon runs with elevated privileges
- Client operations are unprivileged
- D-Bus communication for privileged operations
- PolicyKit integration for authentication

### Bubblewrap Sandboxing
- Package script execution in sandboxed environment
- Namespace isolation for security
- Controlled filesystem access
- Privilege restrictions

## OSTree Environment Detection

apt-ostree automatically detects if it's running in an OSTree environment using multiple methods:

1. **Filesystem Detection**: Check for `/ostree` directory
2. **Boot Detection**: Check for `/run/ostree-booted` file
3. **Kernel Parameter Detection**: Check for `ostree` in `/proc/cmdline`
4. **Library Detection**: Try to load OSTree sysroot
5. **Service Detection**: Check for daemon availability

### Error Handling

When not running in an OSTree environment, apt-ostree provides clear error messages:

```
Error: apt-ostree requires an OSTree environment to operate.

This system does not appear to be running on an OSTree deployment.

To use apt-ostree:
1. Ensure you are running on an OSTree-based system
2. Verify that /ostree directory exists
3. Verify that /run/ostree-booted file exists
4. Ensure you have a valid booted deployment
```



## Performance Characteristics

### Optimization Strategies
- OSTree deduplication for storage efficiency
- Incremental updates for network efficiency
- Parallel package processing
- Caching mechanisms for repeated operations

### Resource Usage
- Memory usage scales with package count
- Disk usage optimized through OSTree deduplication
- Network usage minimized through delta updates
- CPU usage optimized through parallel processing

## Deployment Model

### OSTree Integration
- Atomic commit-based deployments
- Rollback capability through multiple deployments
- Bootloader integration for deployment switching
- State tracking and management

### Package Layering
- Base image remains immutable
- User packages layered on top
- Clear separation of base and user content
- Atomic layer application and removal

## Future Development

### Planned Features
- **OCI Integration**: Container image support
- **Multi-architecture Support**: ARM, x86_64, etc.
- **Advanced Security Features**: Enhanced sandboxing and security
- **Cloud Integration**: Cloud deployment support
- **Enterprise Features**: Advanced enterprise capabilities

### Community and Ecosystem
- **Community Building**: User and developer community
- **Ecosystem Integration**: Integration with Debian/Ubuntu ecosystem
- **Adoption Strategies**: Strategies for widespread adoption
- **Long-term Maintenance**: Sustainable maintenance model 