apt-ostree/docs/user-guide/getting-started.md

# Getting Started with apt-ostree

## Introduction

apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree that provides atomic, immutable system updates with APT package management. This guide will help you get started with apt-ostree.

## Prerequisites

### System Requirements
- **Operating System**: Debian/Ubuntu-based system with OSTree support
- **Architecture**: x86_64 (other architectures may work but are not fully tested)
- **Memory**: 2GB RAM minimum, 4GB+ recommended
- **Disk Space**: 10GB+ free space for OSTree repository

### Required Software
- OSTree (version 2023.1 or later)
- APT package manager
- systemd
- D-Bus

## Installation

### Install apt-ostree

#### From Source
```bash
# Clone the repository
git clone <repository-url>
cd apt-ostree

# Build the project
cargo build --release

# Install binaries
sudo cp target/release/apt-ostree /usr/bin/
sudo cp target/release/apt-ostreed /usr/bin/
```

#### Install System Components
```bash
# Install service files
sudo cp src/daemon/apt-ostreed.service /etc/systemd/system/
sudo cp src/daemon/apt-ostree-bootstatus.service /etc/systemd/system/

# Install D-Bus policy
sudo cp src/daemon/org.aptostree.dev.conf /etc/dbus-1/system.d/

# Enable and start services
sudo systemctl daemon-reload
sudo systemctl enable apt-ostreed
sudo systemctl start apt-ostreed
```

### Verify Installation
```bash
# Check if apt-ostree is installed
apt-ostree --version

# Check daemon status
sudo systemctl status apt-ostreed

# Test daemon communication
apt-ostree daemon-ping
```

## Basic Usage

### Check System Status
```bash
# Show current system status
apt-ostree status

# Show status in JSON format
apt-ostree status --json

# Show verbose status
apt-ostree status --verbose
```

### Initialize System
```bash
# Initialize apt-ostree system
sudo apt-ostree init

# Initialize with specific branch
sudo apt-ostree init --branch debian/stable/x86_64
```

### Install Packages
```bash
# Install a single package
sudo apt-ostree install curl

# Install multiple packages
sudo apt-ostree install curl vim git

# Install with dry-run (preview changes)
sudo apt-ostree install --dry-run curl

# Install with automatic confirmation
sudo apt-ostree install --yes curl
```

### Upgrade System
```bash
# Upgrade system packages
sudo apt-ostree upgrade

# Upgrade with preview
sudo apt-ostree upgrade --preview

# Upgrade with check mode
sudo apt-ostree upgrade --check

# Upgrade with automatic reboot
sudo apt-ostree upgrade --reboot
```

### Rollback Changes
```bash
# Rollback to previous deployment
sudo apt-ostree rollback

# Rollback with dry-run
sudo apt-ostree rollback --dry-run

# Rollback with reboot
sudo apt-ostree rollback --reboot
```

### Search and Information
```bash
# Search for packages
apt-ostree search "web server"

# Search with JSON output
apt-ostree search --json "web server"

# Show package information
apt-ostree info nginx

# List installed packages
apt-ostree list
```

## Advanced Usage

### Package Management

#### Install Packages with Options
```bash
# Install packages with specific options
sudo apt-ostree install --allow-downgrade package1 package2

# Install packages with dry-run
sudo apt-ostree install --dry-run --verbose package1 package2
```

#### Remove Packages
```bash
# Remove packages
sudo apt-ostree remove package1 package2

# Remove with dry-run
sudo apt-ostree remove --dry-run package1
```

#### Override Packages
```bash
# Replace package in base
sudo apt-ostree override replace package1=version1

# Remove package from base
sudo apt-ostree override remove package1

# List current overrides
apt-ostree override list

# Reset all overrides
sudo apt-ostree override reset
```

### System Management

#### Deploy Different Branches
```bash
# Deploy to different branch
sudo apt-ostree deploy debian/testing/x86_64

# Deploy with reboot
sudo apt-ostree deploy --reboot debian/testing/x86_64
```

#### Rebase to Different Tree
```bash
# Rebase to different tree
sudo apt-ostree rebase debian/testing/x86_64

# Rebase with reboot
sudo apt-ostree rebase --reboot debian/testing/x86_64
```

#### Cleanup Old Deployments
```bash
# Cleanup old deployments
sudo apt-ostree cleanup

# Cleanup keeping specific number
sudo apt-ostree cleanup --keep 3
```

### Kernel and Boot Management

#### Manage Kernel Arguments
```bash
# Show 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=ttyS0,115200
```

#### Manage Initramfs
```bash
# Regenerate initramfs
sudo apt-ostree initramfs --regenerate

# Manage initramfs files
sudo apt-ostree initramfs-etc --track /etc/crypttab
sudo apt-ostree initramfs-etc --untrack /etc/crypttab
```

### Database Operations

#### Query Package Database
```bash
# Show package changes between commits
apt-ostree db diff commit1 commit2

# List packages in commit
apt-ostree db list commit1

# Show database version
apt-ostree db version
```

#### Refresh Metadata
```bash
# Refresh repository metadata
sudo apt-ostree refresh-md

# Reload configuration
sudo apt-ostree reload
```

## Configuration

### Environment Variables
```bash
# Set log level
export RUST_LOG=debug

# Set OSTree repository path
export OSTREE_REPO_PATH=/path/to/repo

# Set APT cache directory
export APT_CACHE_DIR=/path/to/cache
```

### Configuration Files
```bash
# Main configuration file
/etc/apt-ostree/config.toml

# Daemon configuration
/etc/apt-ostree/daemon.toml

# Repository configuration
/etc/apt-ostree/repos.d/
```

## Troubleshooting

### Common Issues

#### Permission Errors
```bash
# Check if running as root
sudo apt-ostree status

# Check file permissions
ls -la /var/lib/apt-ostree/
```

#### Daemon Issues
```bash
# Check daemon status
sudo systemctl status apt-ostreed

# Restart daemon
sudo systemctl restart apt-ostreed

# View daemon logs
sudo journalctl -u apt-ostreed -f
```

#### OSTree Issues
```bash
# Check OSTree status
ostree status

# Check OSTree repository
ostree log debian/stable/x86_64

# Repair OSTree repository
ostree fsck
```

#### Package Issues
```bash
# Update package lists
sudo apt update

# Check package availability
apt-ostree search package-name

# Check package dependencies
apt-ostree info package-name
```

### Debug Information
```bash
# Enable debug logging
RUST_LOG=debug apt-ostree status

# Show verbose output
apt-ostree status --verbose

# Show system information
apt-ostree status --json | jq '.system'
```

### Recovery Procedures

#### Rollback Failed Update
```bash
# Rollback to previous deployment
sudo apt-ostree rollback

# Rollback with reboot
sudo apt-ostree rollback --reboot
```

#### Reset System State
```bash
# Reset all user modifications
sudo apt-ostree reset

# Reset with reboot
sudo apt-ostree reset --reboot
```

#### Emergency Recovery
```bash
# Boot into emergency mode
# Edit bootloader to boot previous deployment

# Or use OSTree directly
ostree admin rollback
```

## Best Practices

### System Updates
1. **Always preview changes**: Use `--preview` or `--dry-run` before applying changes
2. **Keep multiple deployments**: Use `cleanup --keep 3` to maintain rollback options
3. **Test in staging**: Test updates in a staging environment before production
4. **Monitor system**: Check system status regularly with `apt-ostree status`

### Package Management
1. **Use atomic operations**: Install multiple packages in single transaction
2. **Verify packages**: Check package information before installation
3. **Manage dependencies**: Let apt-ostree handle dependency resolution
4. **Use overrides sparingly**: Only override packages when necessary

### Security
1. **Keep system updated**: Regular security updates
2. **Monitor logs**: Check system logs for issues
3. **Use sandboxing**: Scripts run in sandboxed environment
4. **Verify signatures**: Package signatures are verified automatically

### Performance
1. **Optimize storage**: Regular cleanup of old deployments
2. **Use caching**: APT cache is maintained for performance
3. **Monitor resources**: Check disk and memory usage
4. **Batch operations**: Combine multiple operations when possible

## Examples

### Basic System Setup
```bash
# Initialize system
sudo apt-ostree init

# Install essential packages
sudo apt-ostree install curl vim git

# Check status
apt-ostree status
```

### Development Environment
```bash
# Install development tools
sudo apt-ostree install build-essential git vim

# Install specific version
sudo apt-ostree override replace gcc=4:9.3.0-1ubuntu2

# Check overrides
apt-ostree override list
```

### Server Setup
```bash
# Install web server
sudo apt-ostree install nginx

# Configure kernel arguments
sudo apt-ostree kargs --append=console=ttyS0,115200

# Regenerate initramfs
sudo apt-ostree initramfs --regenerate

# Reboot to apply changes
sudo apt-ostree upgrade --reboot
```

### System Maintenance
```bash
# Check system status
apt-ostree status

# Update system
sudo apt-ostree upgrade --preview

# Apply updates
sudo apt-ostree upgrade

# Cleanup old deployments
sudo apt-ostree cleanup --keep 3
```

## Next Steps

### Learn More
- Read the [Architecture Documentation](architecture/overview.md)
- Explore [Advanced Usage](advanced-usage.md)
- Check [Troubleshooting Guide](troubleshooting.md)

### Get Help
- Check system logs: `sudo journalctl -u apt-ostreed`
- Enable debug logging: `RUST_LOG=debug apt-ostree status`
- Review documentation in `/usr/share/doc/apt-ostree/`

### Contribute
- Report bugs and issues
- Contribute code and documentation
- Help with testing and validation