# APT-OSTree Documentation

Welcome to the APT-OSTree documentation! This guide will help you understand, install, and use APT-OSTree for managing packages in Debian/Ubuntu-based OSTree systems.

## 📚 **Documentation Sections**

### **User Documentation**
- [**Quick Start Guide**](user/quick-start.md) - Get up and running in minutes
- [**User Manual**](user/manual.md) - Complete user guide
- [**Examples**](user/examples.md) - Common use cases and examples
- [**Troubleshooting**](user/troubleshooting.md) - Solutions to common problems

### **Administrator Documentation**
- [**Installation Guide**](admin/installation.md) - System installation and setup
- [**Configuration**](admin/configuration.md) - System configuration options
- [**Security**](admin/security.md) - Security considerations and best practices
- [**Monitoring**](admin/monitoring.md) - System monitoring and logging

### **Developer Documentation**
- [**Architecture Overview**](developer/architecture.md) - System architecture and design
- [**API Reference**](developer/api.md) - Complete API documentation
- [**Contributing Guide**](developer/contributing.md) - How to contribute to the project
- [**Testing Guide**](developer/testing.md) - Running and writing tests

### **Reference Documentation**
- [**Command Reference**](reference/commands.md) - Complete command documentation
- [**Configuration Files**](reference/config.md) - Configuration file formats
- [**Error Codes**](reference/errors.md) - Error codes and meanings
- [**Performance Tuning**](reference/performance.md) - Performance optimization

## 🚀 **What is APT-OSTree?**

APT-OSTree is a Debian/Ubuntu equivalent of `rpm-ostree` that provides atomic package management for OSTree-based systems. It combines the familiar APT package management interface with the atomic update capabilities of OSTree.

### **Key Features**
- **Atomic Updates**: Package installations and updates are atomic - they either complete fully or rollback completely
- **OSTree Integration**: Seamless integration with OSTree for system image management
- **APT Compatibility**: Familiar APT commands and package management workflow
- **Dependency Resolution**: Advanced dependency resolution with conflict detection
- **Security**: Sandboxed package operations using bubblewrap

### **Use Cases**
- **Immutable Infrastructure**: Deploy and manage immutable server images
- **Atomic Desktop Updates**: Update desktop systems atomically
- **Container Base Images**: Manage package layers in container base images
- **System Rollbacks**: Easy system rollbacks to previous states

## 📖 **Quick Start**

If you want to get started immediately, check out the [Quick Start Guide](user/quick-start.md). Here's a basic example:

```bash
# Install a package atomically
apt-ostree install nginx

# Check system status
apt-ostree status

# Rollback if needed
apt-ostree rollback
```

## 🔧 **System Requirements**

- **Operating System**: Debian 13 (Trixie) or Ubuntu 24.04 (Noble) or later
- **Architecture**: x86_64, aarch64
- **Dependencies**: OSTree, bubblewrap, libapt-pkg
- **Storage**: Minimum 2GB free space for package operations

## 📦 **Installation**

### **From Debian Package**
```bash
# Download the latest package
wget https://github.com/particle-os/apt-ostree/releases/latest/download/apt-ostree_amd64.deb

# Install
sudo dpkg -i apt-ostree_amd64.deb
sudo apt-get install -f  # Install dependencies if needed
```

### **From Source**
```bash
# Clone the repository
git clone https://github.com/particle-os/apt-ostree.git
cd apt-ostree

# Build and install
cargo build --release
sudo cp target/release/apt-ostree /usr/local/bin/
```

## 🤝 **Getting Help**

- **Issues**: [GitHub Issues](https://github.com/particle-os/apt-ostree/issues)
- **Discussions**: [GitHub Discussions](https://github.com/particle-os/apt-ostree/discussions)
- **Documentation**: This documentation site
- **Source Code**: [GitHub Repository](https://github.com/particle-os/apt-ostree)

## 📄 **License**

APT-OSTree is licensed under the MIT License. See the [LICENSE](https://github.com/particle-os/apt-ostree/blob/main/LICENSE) file for details.

## 🙏 **Acknowledgments**

- **OSTree**: The underlying system image management system
- **rpm-ostree**: Inspiration and reference implementation
- **Debian/Ubuntu**: The package management systems we integrate with
- **Rust Community**: The excellent Rust ecosystem and tools

---

**Need help?** Start with the [Quick Start Guide](user/quick-start.md) or check the [Troubleshooting](user/troubleshooting.md) section for common issues.