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](#installation)
2. [Basic Setup](#basic-setup)
3. [Basic Operations](#basic-operations)
4. [Advanced Features](#advanced-features)
5. [Troubleshooting](#troubleshooting)
6. [Migration Guide](#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
```bash
# 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
```bash
# 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:**
   ```bash
   sudo mkdir -p /etc/apt-ostree
   ```

2. **Create configuration file:**
   ```bash
   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:**
   ```bash
   sudo mkdir -p /var/lib/apt-ostree
   sudo mkdir -p /var/log
   sudo mkdir -p /var/cache/apt-ostree
   ```

4. **Set up systemd service:**
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable apt-ostreed
   sudo systemctl start apt-ostreed
   ```

### OSTree Repository Setup
1. **Initialize OSTree repository:**
   ```bash
   sudo mkdir -p /ostree/repo
   sudo ostree init --repo=/ostree/repo --mode=bare
   ```

2. **Create initial deployment:**
   ```bash
   sudo apt-ostree deploy debian/13/amd64
   ```

## Basic Operations

### Package Management

#### Installing Packages
```bash
# 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
```bash
# Remove a package
sudo apt-ostree remove apache2

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

#### Upgrading Packages
```bash
# Upgrade all packages
sudo apt-ostree upgrade

# Check for available upgrades
sudo apt-ostree status
```

#### Searching Packages
```bash
# Search for packages
sudo apt-ostree search nginx

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

### System Management

#### Deployment Operations
```bash
# 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
```bash
# 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
```bash
# Regenerate initramfs
sudo apt-ostree initramfs --enable

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

### Transaction Management
```bash
# 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:

```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check repository status
sudo ostree show --repo=/ostree/repo

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

#### Package Installation Failures
```bash
# 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:

```bash
# 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:**
   ```bash
   sudo apt-mark showmanual > installed-packages.txt
   sudo dpkg --get-selections > package-selections.txt
   ```

2. **Install apt-ostree:**
   ```bash
   sudo dpkg -i apt-ostree_0.1.0-2_amd64.deb
   ```

3. **Initialize OSTree repository:**
   ```bash
   sudo apt-ostree deploy debian/13/amd64
   ```

4. **Install essential packages:**
   ```bash
   sudo apt-ostree install $(cat installed-packages.txt)
   ```

### From rpm-ostree
1. **Export package list:**
   ```bash
   rpm -qa > installed-packages.txt
   ```

2. **Convert package names (if needed):**
   ```bash
   # 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:**
   ```bash
   sudo apt-ostree install $(cat deb-packages.txt)
   ```

### Post-Migration
1. **Verify system functionality:**
   ```bash
   sudo apt-ostree internals diagnostics
   sudo apt-ostree status
   ```

2. **Test package operations:**
   ```bash
   sudo apt-ostree search test-package
   sudo apt-ostree install test-package
   sudo apt-ostree remove test-package
   ```

3. **Configure automatic updates:**
   ```bash
   # 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.*