debian-forge/docs/performance-optimization.md

Performance Optimization Guide

This guide covers performance optimization techniques for debian-forge builds.

APT Caching

Using apt-cacher-ng

The most effective way to speed up builds is using apt-cacher-ng as a local proxy:

# Install apt-cacher-ng
sudo apt install apt-cacher-ng

# Start the service
sudo systemctl start apt-cacher-ng

# Configure in your manifest
{
  "type": "org.osbuild.apt",
  "options": {
    "packages": ["linux-image-amd64"],
    "apt_proxy": "http://localhost:3142"
  }
}

Benefits

• 2-3x faster builds for repeated packages
• Reduced bandwidth usage
• Offline capability for cached packages
• Consistent builds across different environments

Build Optimization

1. Minimal Base Images

Use minbase variant for faster debootstrap:

{
  "type": "org.osbuild.debootstrap",
  "options": {
    "variant": "minbase",
    "extra_packages": ["apt", "systemd", "bash"]
  }
}

2. Package Selection

• Use recommends: false to avoid unnecessary packages
• Install only essential packages
• Use extra_packages in debootstrap for core packages

3. Repository Configuration

• Use local mirrors when available
• Configure sources explicitly
• Use HTTPS for security without significant performance impact

Parallel Builds

Multi-Architecture Builds

Build multiple architectures in parallel:

# Build amd64 and arm64 simultaneously
python3 -m osbuild debian-amd64.json --libdir . &
python3 -m osbuild debian-arm64.json --libdir . &
wait

CI/CD Optimization

Use parallel jobs in CI/CD:

strategy:
  matrix:
    arch: [amd64, arm64]
    suite: [trixie, jammy]
  max-parallel: 4

Memory Optimization

1. Build Environment

• Use sufficient RAM (8GB+ recommended)
• Enable swap if needed
• Monitor memory usage during builds

2. Package Cache

• Clean package cache regularly
• Use apt-get clean in manifests
• Monitor disk space usage

Network Optimization

1. Mirror Selection

Choose geographically close mirrors:

{
  "type": "org.osbuild.debootstrap",
  "options": {
    "mirror": "http://deb.debian.org/debian"  # Automatic mirror selection
  }
}

2. Proxy Configuration

Use corporate proxies when available:

{
  "type": "org.osbuild.apt",
  "options": {
    "apt_proxy": "http://proxy.company.com:3142"
  }
}

Build Time Benchmarks

Typical Build Times

Image Type	Base Time	With apt-cacher-ng	Improvement
Minimal Debian	5-10 min	2-3 min	60-70%
Server Image	10-15 min	4-6 min	60-70%
Ubuntu Image	8-12 min	3-5 min	60-70%
ARM64 Build	15-20 min	6-8 min	60-70%

Factors Affecting Build Time

1. Network speed - Primary factor
2. Package count - Linear relationship
3. Architecture - ARM64 typically slower
4. Base image size - Minimal images faster
5. Caching - Significant improvement with apt-cacher-ng

Monitoring and Profiling

Build Logs

Enable detailed logging:

python3 -m osbuild manifest.json --json | jq '.log'

Stage Timing

Monitor individual stage performance:

python3 -m osbuild manifest.json --monitor timing

Resource Usage

Monitor system resources during builds:

# Monitor CPU and memory
htop

# Monitor disk I/O
iotop

# Monitor network
nethogs

Troubleshooting Performance Issues

Slow Package Downloads

1. Check network connectivity
2. Use apt-cacher-ng
3. Try different mirrors
4. Check for network throttling

High Memory Usage

1. Increase available RAM
2. Enable swap
3. Reduce package count
4. Use minimal base images

Disk Space Issues

1. Clean package cache
2. Remove old build artifacts
3. Use external storage for builds
4. Monitor disk usage

Best Practices

1. Development Workflow

• Use apt-cacher-ng for all builds
• Keep manifests minimal and focused
• Test with different architectures
• Monitor build performance regularly

2. CI/CD Optimization

• Use parallel builds when possible
• Cache APT packages between builds
• Use minimal base images
• Monitor build times and resources

3. Production Builds

• Use dedicated build servers
• Implement proper caching
• Monitor and alert on performance
• Regular cleanup of build artifacts

Advanced Techniques

Custom APT Configuration

Optimize APT settings for your environment:

{
  "type": "org.osbuild.apt.config",
  "options": {
    "config": {
      "Acquire": {
        "http": {
          "Pipeline-Depth": "5"
        }
      }
    }
  }
}

Build Caching

Implement build artifact caching:

# Cache build artifacts
python3 -m osbuild manifest.json --cache ./build-cache

# Reuse cached artifacts
python3 -m osbuild manifest.json --cache ./build-cache --checkpoint build

Incremental Builds

Use checkpoints for incremental builds:

# Build up to specific stage
python3 -m osbuild manifest.json --checkpoint org.osbuild.apt

# Continue from checkpoint
python3 -m osbuild manifest.json --checkpoint org.osbuild.apt

See Also

• APT Stages Reference
• Debian Image Building Tutorial
• Troubleshooting Guide