apt-ostree/docs/user-guide.md

apt-ostree User Guide

System Requirements

Supported Operating Systems

• Debian 13+ (Trixie) or newer
• Ubuntu 25.04+ (Noble Numbat) or newer

Required System Components

• OSTree 2025.2+
• APT 3.0+
• Systemd 255+
• Polkit 123+

Table of Contents

1. Installation
2. Basic Setup
3. Basic Operations
4. Advanced Features
5. Troubleshooting
6. Migration Guide

Installation

Prerequisites

apt-ostree requires the following system components:

• Debian 13+ or Ubuntu 24.04+
• OSTree 2025.2+
• APT 3.0+
• systemd
• Polkit
• D-Bus

Installing from Debian Package

# Download and install the package
sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb

# Install dependencies if needed
sudo apt-get install -f

Installing from Source

# Clone the repository
git clone https://github.com/robojerk/apt-ostree.git
cd apt-ostree

# Install build dependencies
sudo apt-get install build-essential cargo rustc pkg-config \
    libostree-dev libapt-pkg-dev libpolkit-gobject-1-dev \
    libdbus-1-dev libsystemd-dev

# Build and install
cargo build --release
sudo install -m 755 target/release/apt-ostree /usr/local/bin/
sudo install -m 755 target/release/apt-ostreed /usr/local/libexec/

Basic Setup

Initial Configuration

1. Create configuration directory:

   sudo mkdir -p /etc/apt-ostree
   

2. Create configuration file:

   sudo tee /etc/apt-ostree/config.toml > /dev/null <<EOF
   [system]
   data_dir = "/var/lib/apt-ostree"
   log_level = "info"
   max_deployments = 3
   
   [ostree]
   repo_path = "/ostree/repo"
   deploy_path = "/ostree/deploy"
   default_branch = "debian/13/amd64"
   
   [apt]
   sources_list = "/etc/apt/sources.list"
   cache_dir = "/var/cache/apt"
   
   [security]
   polkit_enabled = true
   require_auth = true
   
   [daemon]
   user = "root"
   group = "root"
   log_file = "/var/log/apt-ostreed.log"
   EOF
   

3. Create required directories:

   sudo mkdir -p /var/lib/apt-ostree
   sudo mkdir -p /var/log
   sudo mkdir -p /var/cache/apt-ostree
   

4. Set up systemd service:

   sudo systemctl daemon-reload
   sudo systemctl enable apt-ostreed
   sudo systemctl start apt-ostreed
   

OSTree Repository Setup

1. Initialize OSTree repository:

   sudo mkdir -p /ostree/repo
   sudo ostree init --repo=/ostree/repo --mode=bare
   

2. Create initial deployment:

   sudo apt-ostree deploy debian/13/amd64
   

Basic Operations

Package Management

Installing Packages

# Install a single package
sudo apt-ostree install nginx

# Install multiple packages
sudo apt-ostree install nginx curl wget

# Install with specific version
sudo apt-ostree install nginx=1.18.0-6

Removing Packages

# Remove a package
sudo apt-ostree remove apache2

# Remove multiple packages
sudo apt-ostree remove apache2 mysql-server

Upgrading Packages

# Upgrade all packages
sudo apt-ostree upgrade

# Check for available upgrades
sudo apt-ostree status

Searching Packages

# Search for packages
sudo apt-ostree search nginx

# Search with wildcards
sudo apt-ostree search "nginx*"

System Management

Deployment Operations

# Show current status
sudo apt-ostree status

# List deployments
sudo apt-ostree log

# Rollback to previous deployment
sudo apt-ostree rollback

# Clean up old deployments
sudo apt-ostree cleanup

Kernel Management

# View current kernel arguments
sudo apt-ostree kargs

# Add kernel argument
sudo apt-ostree kargs --append "console=ttyS0"

# Remove kernel argument
sudo apt-ostree kargs --delete "console=ttyS0"

# Replace kernel argument
sudo apt-ostree kargs --replace "console=tty0" "console=ttyS0"

Initramfs Management

# Regenerate initramfs
sudo apt-ostree initramfs --enable

# Disable initramfs regeneration
sudo apt-ostree initramfs --disable

Transaction Management

# Start a transaction
sudo apt-ostree transaction start

# Check transaction status
sudo apt-ostree transaction status

# Commit transaction
sudo apt-ostree transaction commit

# Rollback transaction
sudo apt-ostree transaction rollback

Advanced Features

Development Commands

Development commands are hidden from normal help output but provide useful debugging tools:

# Run system diagnostics
sudo apt-ostree internals diagnostics

# Validate system state
sudo apt-ostree internals validate-state

# Dump debug information
sudo apt-ostree internals debug-dump

# Execute script in container
sudo apt-ostree testutils script-shell /tmp/test.sh --read-only

# Get system architecture
sudo apt-ostree shlib-backend get-basearch

Remote Management

# Add remote repository
sudo apt-ostree remote add production https://ostree.example.com/repo

# List remotes
sudo apt-ostree remote list

# Remove remote
sudo apt-ostree remote delete production

Branch Management

# List available references
sudo apt-ostree refs

# Switch to different branch
sudo apt-ostree rebase https://ostree.example.com/repo stable/13/amd64

# Create new branch
sudo apt-ostree refs --create new-branch

Troubleshooting

Common Issues

Daemon Not Running

# Check service status
sudo systemctl status apt-ostreed

# Start the service
sudo systemctl start apt-ostreed

# Check logs
sudo journalctl -u apt-ostreed -f

Permission Denied

# Check Polkit policies
sudo polkit-policy-file-validate /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy

# Verify user permissions
groups $USER

OSTree Repository Issues

# Check repository status
sudo ostree show --repo=/ostree/repo

# Verify repository integrity
sudo ostree fsck --repo=/ostree/repo

Package Installation Failures

# Check APT sources
sudo apt-ostree internals diagnostics

# Verify package availability
sudo apt-ostree search <package-name>

# Check for dependency conflicts
sudo apt-ostree info <package-name>

Debug Mode

Enable debug logging for troubleshooting:

# Set debug log level
export APT_OSTREE_LOG_LEVEL=debug

# Run command with verbose output
sudo apt-ostree --verbose install nginx

Log Files

• Daemon logs: /var/log/apt-ostreed.log
• System logs: sudo journalctl -u apt-ostreed
• OSTree logs: sudo ostree log --repo=/ostree/repo

Migration Guide

From Traditional APT

1. Backup current system:

   sudo apt-mark showmanual > installed-packages.txt
   sudo dpkg --get-selections > package-selections.txt
   

2. Install apt-ostree:

   sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
   

3. Initialize OSTree repository:

   sudo apt-ostree deploy debian/13/amd64
   

4. Install essential packages:

   sudo apt-ostree install $(cat installed-packages.txt)
   

From rpm-ostree

1. Export package list:

   rpm -qa > installed-packages.txt
   

2. Convert package names (if needed):

   # Some package names may differ between RPM and DEB
   sed 's/^python3-/python3-/g' installed-packages.txt > deb-packages.txt
   

3. Install with apt-ostree:

   sudo apt-ostree install $(cat deb-packages.txt)
   

Post-Migration

1. Verify system functionality:

   sudo apt-ostree internals diagnostics
   sudo apt-ostree status
   

2. Test package operations:

   sudo apt-ostree search test-package
   sudo apt-ostree install test-package
   sudo apt-ostree remove test-package
   

3. Configure automatic updates:

   # Set up cron job for regular upgrades
   echo "0 2 * * * /usr/bin/apt-ostree upgrade" | sudo crontab -
   

Best Practices

System Administration

• Regular maintenance: Run apt-ostree cleanup periodically
• Backup deployments: Keep at least 2-3 deployments for rollback
• Monitor logs: Check daemon logs for errors or warnings
• Test updates: Test package updates in development environment first

Security

• Limit access: Only authorized users should have access to apt-ostree
• Audit policies: Regularly review Polkit policies
• Monitor changes: Log all system changes for audit purposes
• Update regularly: Keep apt-ostree and system packages updated

Performance

• Optimize storage: Use appropriate filesystem for OSTree repository
• Network optimization: Use local mirrors for package repositories
• Cache management: Monitor and clean APT cache regularly
• Resource limits: Set appropriate limits for daemon processes

Support and Resources

Documentation

• Manual pages: man apt-ostree, man apt-ostree-dev, man apt-ostree.conf
• Help system: apt-ostree --help, apt-ostree <command> --help
• Online documentation: Project wiki and documentation

Community

• Issue tracker: GitHub Issues for bug reports
• Discussions: GitHub Discussions for questions and ideas
• Contributing: Pull requests and contributions welcome

Professional Support

For enterprise deployments and professional support, contact the project maintainers.

---

This guide covers the basic usage of apt-ostree. For advanced features and development, refer to the developer documentation and source code.