particle-os/apt-ostree
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
apt-ostree/docs/user-guide/getting-started.md

9.5 KiB
Raw Blame History

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

# 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

# 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

# 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

# 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

# Initialize apt-ostree system
sudo apt-ostree init

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

Install Packages

# 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

# 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

# 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

# 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

# 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

# Remove packages
sudo apt-ostree remove package1 package2

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

Override Packages

# 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

# 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

# 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

# Cleanup old deployments
sudo apt-ostree cleanup

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

Kernel and Boot Management

Manage Kernel Arguments

# 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

# 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

# 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

# Refresh repository metadata
sudo apt-ostree refresh-md

# Reload configuration
sudo apt-ostree reload

Configuration

Environment Variables

# 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

# 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

# Check if running as root
sudo apt-ostree status

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

Daemon Issues

# 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

# Check OSTree status
ostree status

# Check OSTree repository
ostree log debian/stable/x86_64

# Repair OSTree repository
ostree fsck

Package Issues

# Update package lists
sudo apt update

# Check package availability
apt-ostree search package-name

# Check package dependencies
apt-ostree info package-name

Debug Information

# 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

# Rollback to previous deployment
sudo apt-ostree rollback

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

Reset System State

# Reset all user modifications
sudo apt-ostree reset

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

Emergency Recovery

# 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

# Initialize system
sudo apt-ostree init

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

# Check status
apt-ostree status

Development Environment

# 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

# 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

# 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

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