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:

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

```json
{
  "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:

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

```yaml
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:

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

### 2. Proxy Configuration

Use corporate proxies when available:

```json
{
  "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:

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

### Stage Timing

Monitor individual stage performance:

```bash
python3 -m osbuild manifest.json --monitor timing
```

### Resource Usage

Monitor system resources during builds:

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

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

### Build Caching

Implement build artifact caching:

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

```bash
# 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](apt-stages.md)
- [Debian Image Building Tutorial](debian-image-building-tutorial.md)
- [Troubleshooting Guide](troubleshooting.md)