particle-os-tools/docs/apt-layer/apt.md

APT Integration in apt-layer

TLDR - Quick Reference

Basic apt-get Usage

Traditional chroot-based installation:

apt-layer base-image new-image package1 package2

Container-based installation:

apt-layer --container base-image new-image package1 package2

Live system installation:

apt-layer --live-install package1 package2

Direct apt-get commands in apt-layer:

# Update package lists
chroot /path/to/chroot apt-get update

# Install packages
chroot /path/to/chroot apt-get install -y package1 package2

# Clean package cache
chroot /path/to/chroot apt-get clean

# Remove unused packages
chroot /path/to/chroot apt-get autoremove -y

---

Overview

apt-layer uses apt-get as the primary package management tool for Debian/Ubuntu systems, providing a high-level interface for package installation, dependency resolution, and system updates. apt-layer integrates apt-get into its atomic layering system to create immutable, versioned system layers.

Key Role: apt-get serves as the package manager in apt-layer for:

• Package installation and dependency resolution
• Package list updates and cache management
• System upgrades and maintenance
• Package removal and cleanup

Integration Strategy: apt-layer uses apt-get in isolated environments (chroot, containers, overlays) to ensure atomic operations and prevent system corruption.

---

Package Structure

Debian/Ubuntu Package Management

apt-get Package Manager:

• Purpose: High-level package management for Debian/Ubuntu systems
• Contains:
  • /usr/bin/apt-get - Main package management tool
  • /usr/bin/apt-cache - Package cache querying
  • /usr/bin/apt-config - Configuration management
  • /etc/apt/ - Configuration directory

Key Features:

• Automatic dependency resolution
• Package repository management
• Transaction-based operations
• Cache management and optimization

Installation

Debian/Ubuntu:

# apt-get is included by default in Debian/Ubuntu systems
# Additional tools can be installed:
sudo apt install -y apt-utils apt-transport-https

Fedora/RHEL:

# Not applicable - apt-get is Debian/Ubuntu specific
# Fedora/RHEL uses dnf/yum instead

---

apt-get Usage in apt-layer

1. Traditional Chroot-based Installation

Standard layer creation workflow:

# apt-layer command
apt-layer base-image new-image package1 package2

# Underlying apt-get operations
chroot /path/to/chroot apt-get update
chroot /path/to/chroot apt-get install -y package1 package2
chroot /path/to/chroot apt-get clean
chroot /path/to/chroot apt-get autoremove -y

Process:

1. Mount base ComposeFS image to temporary directory
2. Set up chroot environment with necessary mounts (proc, sys, dev)
3. Update package lists with apt-get update
4. Install packages with apt-get install -y
5. Clean package cache and remove unused packages
6. Create new ComposeFS layer from changes
7. Perform atomic swap of layer directories

2. Container-based Installation

Container isolation workflow:

# apt-layer command
apt-layer --container base-image new-image package1 package2

# Underlying apt-get operations in container
podman exec container_name apt-get update
podman exec container_name apt-get install -y package1 package2
podman exec container_name apt-get clean

Process:

1. Create container from base image (ComposeFS or standard Ubuntu)
2. Mount base filesystem and output directory
3. Run apt-get commands inside container
4. Export container filesystem changes
5. Create ComposeFS layer from exported changes

3. Live System Installation

Live overlay workflow:

# apt-layer command
apt-layer --live-install package1 package2

# Underlying apt-get operations in overlay
chroot /overlay/mount apt-get update
chroot /overlay/mount apt-get install -y package1 package2
chroot /overlay/mount apt-get clean

Process:

1. Start live overlay on running system
2. Mount overlay filesystem for temporary changes
3. Run apt-get commands in overlay chroot
4. Apply changes immediately to running system
5. Allow commit or rollback of changes

4. Dry Run and Validation

Conflict detection:

# Perform dry run to check for conflicts
chroot /path/to/chroot apt-get install -s package1 package2

# Check package dependencies
chroot /path/to/chroot apt-cache depends package1

# Validate package availability
chroot /path/to/chroot apt-cache policy package1

Validation process:

1. Use apt-get install -s for simulation mode
2. Check dependency resolution without installing
3. Validate package availability in repositories
4. Detect conflicts before actual installation

5. Package Cache Management

Cache operations:

# Update package lists
chroot /path/to/chroot apt-get update

# Clean package cache
chroot /path/to/chroot apt-get clean

# Remove unused packages
chroot /path/to/chroot apt-get autoremove -y

# Remove configuration files
chroot /path/to/chroot apt-get purge package1

Cache strategy:

• Update package lists before installation
• Clean cache after installation to reduce layer size
• Remove unused packages to minimize footprint
• Preserve configuration files unless explicitly purged

6. Repository Management

Repository configuration:

# Add repository
chroot /path/to/chroot apt-add-repository ppa:user/repo

# Update after adding repository
chroot /path/to/chroot apt-get update

# Install packages from specific repository
chroot /path/to/chroot apt-get install -t repository package1

Repository handling:

• Support for additional repositories (PPAs, third-party)
• Automatic repository key management
• Repository priority and pinning support
• Secure repository validation

---

apt-get vs Other Package Managers

apt-get (Debian/Ubuntu)

Use Cases:

• High-level package management
• Automatic dependency resolution
• Repository management
• System upgrades and maintenance

Advantages:

• Mature and stable package manager
• Excellent dependency resolution
• Rich ecosystem of packages
• Strong security model

Integration:

• Primary package manager for apt-layer
• Used in all installation methods (chroot, container, overlay)
• Provides foundation for atomic operations

dpkg (Low-level Package Manager)

Use Cases:

• Direct package installation
• Package verification and integrity checks
• Low-level package operations
• Offline package installation

Integration:

• Used by apt-get for actual package installation
• Direct dpkg installation available in apt-layer for performance
• Package integrity verification and validation

Comparison with rpm-ostree

apt-layer (apt-get):

• Uses apt-get for package management
• Creates ComposeFS layers for atomic operations
• Supports chroot, container, and overlay installation
• Debian/Ubuntu package ecosystem

rpm-ostree (dnf):

• Uses dnf for package management
• Creates OSTree commits for atomic operations
• Supports container and overlay installation
• Red Hat/Fedora package ecosystem

---

Integration with apt-layer Features

1. Atomic Layer Creation

# Create atomic layer with apt-get
apt-layer base-image new-image package1 package2

# Process:
# 1. apt-get update (update package lists)
# 2. apt-get install -y package1 package2 (install packages)
# 3. apt-get clean (clean cache)
# 4. apt-get autoremove -y (remove unused packages)
# 5. Create ComposeFS layer (atomic operation)

2. Live System Management

# Install packages on running system
apt-layer --live-install package1 package2

# Process:
# 1. Start overlay on running system
# 2. apt-get update (in overlay)
# 3. apt-get install -y package1 package2 (in overlay)
# 4. Apply changes immediately
# 5. Allow commit or rollback

3. Container-based Isolation

# Install packages in container
apt-layer --container base-image new-image package1 package2

# Process:
# 1. Create container from base image
# 2. apt-get update (in container)
# 3. apt-get install -y package1 package2 (in container)
# 4. Export container changes
# 5. Create ComposeFS layer

4. OSTree Atomic Workflow

# Atomic package management (rpm-ostree style)
apt-layer ostree compose install package1 package2

# Process:
# 1. apt-get update (in OSTree environment)
# 2. apt-get install -y package1 package2 (in OSTree environment)
# 3. Create OSTree commit
# 4. Deploy atomically

---

Error Handling and Validation

1. Package Conflict Detection

# Dry run to detect conflicts
if ! chroot "$chroot_dir" apt-get install -s "${packages[@]}" >/dev/null 2>&1; then
    log_error "Package conflicts detected during dry run" "apt-layer"
    return 1
fi

2. Dependency Resolution

# Install packages with dependency resolution
if ! chroot "$chroot_dir" apt-get install -y "${packages[@]}"; then
    log_error "Failed to install packages" "apt-layer"
    return 1
fi

3. Repository Issues

# Check repository availability
if ! chroot "$chroot_dir" apt-get update >/dev/null 2>&1; then
    log_error "Failed to update package lists" "apt-layer"
    return 1
fi

4. Network Connectivity

# Test network connectivity
if ! chroot "$chroot_dir" apt-get update --dry-run >/dev/null 2>&1; then
    log_error "Network connectivity issues detected" "apt-layer"
    return 1
fi

---

Configuration and Customization

1. apt Configuration

Default configuration:

# Set non-interactive mode
export DEBIAN_FRONTEND=noninteractive

# Configure apt sources
echo "deb http://archive.ubuntu.com/ubuntu/ jammy main" > /etc/apt/sources.list

# Configure apt preferences
cat > /etc/apt/preferences.d/99apt-layer <<EOF
Package: *
Pin: release a=jammy
Pin-Priority: 500
EOF

2. Repository Management

Adding repositories:

# Add PPA repository
chroot "$chroot_dir" apt-add-repository ppa:user/repo

# Add third-party repository
echo "deb [arch=amd64] https://repo.example.com/ jammy main" | \
    chroot "$chroot_dir" tee -a /etc/apt/sources.list.d/example.list

# Add repository key
chroot "$chroot_dir" apt-key adv --keyserver keyserver.ubuntu.com --recv-keys KEY_ID

3. Package Selection

Package filtering:

# Install specific version
chroot "$chroot_dir" apt-get install -y package=version

# Install from specific repository
chroot "$chroot_dir" apt-get install -y -t repository package

# Hold package version
chroot "$chroot_dir" apt-mark hold package

---

Performance Optimization

1. Cache Management

# Clean cache after installation
chroot "$chroot_dir" apt-get clean

# Remove unused packages
chroot "$chroot_dir" apt-get autoremove -y

# Remove configuration files
chroot "$chroot_dir" apt-get purge package

2. Parallel Downloads

# Configure parallel downloads
cat > /etc/apt/apt.conf.d/99parallel <<EOF
Acquire::http::Pipeline-Depth "5";
Acquire::http::No-Cache=True;
Acquire::BrokenProxy=true;
EOF

3. Repository Optimization

# Use local mirror
echo "deb http://local-mirror/ubuntu/ jammy main" > /etc/apt/sources.list

# Use CDN for faster downloads
echo "deb http://archive.ubuntu.com/ubuntu/ jammy main" > /etc/apt/sources.list

---

Troubleshooting

1. Common Issues

Package not found:

# Update package lists
apt-get update

# Search for package
apt-cache search package-name

# Check package availability
apt-cache policy package-name

Dependency conflicts:

# Check dependencies
apt-cache depends package-name

# Resolve conflicts
apt-get install -f

# Check broken packages
apt-get check

Repository issues:

# Check repository status
apt-get update

# Check repository keys
apt-key list

# Fix repository issues
apt-get update --fix-missing

2. Debugging

Verbose output:

# Enable verbose apt-get output
chroot "$chroot_dir" apt-get install -y -V package1 package2

# Show dependency information
chroot "$chroot_dir" apt-cache show package-name

# Show package policy
chroot "$chroot_dir" apt-cache policy package-name

Log analysis:

# Check apt logs
tail -f /var/log/apt/history.log

# Check dpkg logs
tail -f /var/log/dpkg.log

---

Best Practices

1. Package Installation

• Always update package lists before installation
• Use -y flag for non-interactive installation
• Clean package cache after installation
• Remove unused packages to minimize layer size

2. Repository Management

• Use official repositories when possible
• Verify repository keys and signatures
• Keep repository lists minimal and focused
• Use local mirrors for better performance

3. Error Handling

• Always perform dry runs for complex installations
• Check for package conflicts before installation
• Validate repository connectivity
• Handle dependency resolution failures gracefully

4. Performance

• Clean package cache regularly
• Remove unused packages and configuration files
• Use parallel downloads when possible
• Optimize repository sources for your location

---

References

Official Documentation

• apt-get man page
• apt-cache man page
• apt.conf man page

Related Tools

• dpkg: Low-level package manager used by apt-get
• apt-cache: Package cache querying tool
• apt-config: Configuration management tool
• apt-mark: Package state management tool

Integration Notes

• apt-layer uses apt-get as the primary package manager
• All package operations are performed in isolated environments
• Atomic operations ensure system consistency
• Integration with ComposeFS provides immutable layering