apt-ostree/docs/README.md

# apt-ostree Documentation

**Last Updated**: July 18, 2025

## Overview

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. This documentation provides comprehensive technical details, architectural insights, and implementation guidance.

## 📚 Documentation Structure

### 🏗️ Architecture & Design
- **[Architecture Overview](architecture/overview.md)** - Core architectural principles and design philosophy
- **[System Architecture](architecture/system.md)** - Detailed system architecture and component interactions
- **[Data Flow](architecture/data-flow.md)** - Package installation and deployment data flow
- **[Security Model](architecture/security.md)** - Security architecture and sandboxing

### 🔧 Implementation Details
- **[APT Integration](implementation/apt-integration.md)** - APT package management integration
- **[OSTree Integration](implementation/ostree-integration.md)** - OSTree deployment and commit management
- **[Package Management](implementation/package-management.md)** - Package installation, removal, and layering
- **[Script Execution](implementation/script-execution.md)** - DEB script execution and sandboxing
- **[Filesystem Assembly](implementation/filesystem-assembly.md)** - Filesystem assembly and optimization

### 📖 User Guides
- **[Installation Guide](user-guides/installation.md)** - System installation and setup
- **[Basic Usage](user-guides/basic-usage.md)** - Common commands and operations
- **[Advanced Usage](user-guides/advanced-usage.md)** - Advanced features and workflows
- **[CLI Compatibility](user-guides/cli-compatibility.md)** - rpm-ostree compatibility guide
- **[Troubleshooting](user-guides/troubleshooting.md)** - Common issues and solutions

### 🧪 Development & Testing
- **[Development Setup](development/setup.md)** - Development environment setup
- **[Testing Guide](development/testing.md)** - Testing strategies and procedures
- **[Contributing](development/contributing.md)** - Contribution guidelines and workflow
- **[API Reference](development/api.md)** - Internal API documentation

### 📋 Reference
- **[Command Reference](reference/commands.md)** - Complete command reference
- **[Configuration](reference/configuration.md)** - Configuration file formats and options
- **[Error Codes](reference/errors.md)** - Error codes and troubleshooting
- **[Performance](reference/performance.md)** - Performance characteristics and optimization

## 🎯 Current Status

### ✅ Completed Features
- **Real Package Install/Commit Logic**: Working APT/OSTree integration with atomic commits
- **FFI Segfaults Fixed**: Stable rust-apt FFI calls with proper error handling
- **Atomic Filesystem Layout**: OSTree-compatible filesystem structure following best practices
- **Package Metadata Parsing**: Real DEB control file parsing with dependency resolution
- **Complete CLI Framework**: Full command structure with rpm-ostree compatibility
- **Permissions System**: Robust root privilege validation and error messages
- **rpm-ostree Install Command**: Complete CLI interface matching rpm-ostree install exactly

### 🔄 Current Phase: rpm-ostree CLI Mirroring
- ✅ **Install Command**: Fully implemented with all 20+ rpm-ostree options
- [ ] **Remaining Commands**: Implementing all other rpm-ostree commands for identical UX
- [ ] **Integration Tests**: Testing real workflows in containers/VMs
- [ ] **Performance Optimization**: Optimizing package extraction and commit creation

## 🏗️ Core Architecture

### Key Principles
1. **"From Scratch" Philosophy**: Every change regenerates the target filesystem completely
2. **Atomic Operations**: All changes are atomic with proper rollback support
3. **Immutable Base + Layered Packages**: Base image remains unchanged, user packages layered on top

### Component Architecture
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Client    │    │   D-Bus Daemon  │    │  OSTree Manager │
│                 │◄──►│                 │◄──►│                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  APT Manager    │    │ Package Manager │
                       │                 │    │                 │
                       └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Filesystem      │    │ Script Execution│
                       │ Assembly        │    │ & Sandboxing    │
                       └─────────────────┘    └─────────────────┘
```

## 🚀 Quick Start

### Installation
```bash
# Clone the repository
git clone https://github.com/your-org/apt-ostree.git
cd apt-ostree

# Install dependencies
sudo apt install libapt-pkg-dev libostree-dev bubblewrap

# Build and install
cargo build --release
sudo cargo install --path .
```

### Basic Usage
```bash
# Initialize the system
sudo apt-ostree init

# Install packages (identical to rpm-ostree)
sudo apt-ostree install nginx vim
sudo apt-ostree install --dry-run htop
sudo apt-ostree install --uninstall package-name

# Check status
apt-ostree status

# Rollback if needed
sudo apt-ostree rollback
```

## 📖 Documentation Philosophy

This documentation follows these principles:

1. **Comprehensive Coverage**: All aspects of the system are documented
2. **Technical Depth**: Detailed technical information for developers
3. **User-Focused**: Clear guidance for end users
4. **Living Documentation**: Updated with code changes
5. **Examples**: Practical examples for all major features

## 🤝 Contributing to Documentation

### Documentation Standards
- Use clear, concise language
- Include practical examples
- Maintain technical accuracy
- Update when code changes
- Follow the established structure

### How to Contribute
1. Identify documentation gaps or improvements
2. Create or update relevant documentation files
3. Ensure examples work with current code
4. Submit pull requests with documentation changes
5. Review and test documentation changes

## 📞 Support

### Getting Help
- **GitHub Issues**: For bug reports and feature requests
- **Documentation**: Check relevant documentation sections
- **Development Plan**: See `.notes/plan.md` for current status

### Community Resources
- **IRC**: #apt-ostree on Libera.Chat (when available)
- **Mailing List**: apt-ostree@lists.example.com (when available)
- **Discussions**: GitHub Discussions (when available)

---

**Note**: This documentation reflects the current state of apt-ostree development. The project has achieved major milestones with working real APT/OSTree integration and complete rpm-ostree install command compatibility. The project is now focused on implementing the remaining rpm-ostree commands for identical user experience.