apt-ostree/docs

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 - Get up and running in minutes
• User Manual - Complete user guide
• Examples - Common use cases and examples
• Troubleshooting - Solutions to common problems

Administrator Documentation

• Installation Guide - System installation and setup
• Configuration - System configuration options
• Security - Security considerations and best practices
• Monitoring - System monitoring and logging

Developer Documentation

• Architecture Overview - System architecture and design
• API Reference - Complete API documentation
• Contributing Guide - How to contribute to the project
• Testing Guide - Running and writing tests

Reference Documentation

• Command Reference - Complete command documentation
• Configuration Files - Configuration file formats
• Error Codes - Error codes and meanings
• Performance Tuning - 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. Here's a basic example:

# 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

# 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

# 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
• Discussions: GitHub Discussions
• Documentation: This documentation site
• Source Code: GitHub Repository

📄 License

APT-OSTree is licensed under the MIT License. See the 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 or check the Troubleshooting section for common issues.