debian-forge/docs/apt-stages.md

APT Stages for Debian Forge

This document describes the APT-related stages available in debian-forge, which provide comprehensive Debian/Ubuntu package management support.

Available Stages

1. org.osbuild.debootstrap

Creates a base Debian filesystem using debootstrap, similar to how OSBuild uses dnf for Fedora.

Options:

• suite (string, required): Debian suite to bootstrap (e.g., "trixie", "jammy", "sid")
• mirror (string, required): Debian mirror URL
• arch (string, optional): Target architecture (e.g., "amd64", "arm64")
• variant (string, optional): Debootstrap variant (e.g., "minbase", "buildd")
• extra_packages (array, optional): Additional packages to include in base filesystem
• apt_proxy (string, optional): apt-cacher-ng proxy URL

Example:

{
  "type": "org.osbuild.debootstrap",
  "options": {
    "suite": "trixie",
    "mirror": "http://deb.debian.org/debian",
    "arch": "amd64",
    "variant": "minbase",
    "extra_packages": ["apt", "systemd", "bash"]
  }
}

2. org.osbuild.apt.config

Configures APT package manager settings, including sources and preferences.

Options:

• sources (object, optional): Debian package sources configuration
• preferences (object, optional): Package preferences and pinning configuration
• apt_proxy (string, optional): apt-cacher-ng proxy URL

Example:

{
  "type": "org.osbuild.apt.config",
  "options": {
    "sources": {
      "debian": "deb http://deb.debian.org/debian trixie main\n"
    }
  }
}

3. org.osbuild.apt

Installs Debian packages using APT package manager.

Options:

• packages (array, required): List of packages to install
• recommends (boolean, optional): Install recommended packages (default: false)
• unauthenticated (boolean, optional): Allow unauthenticated packages (default: false)
• update (boolean, optional): Update package lists before installation (default: true)
• apt_proxy (string, optional): apt-cacher-ng proxy URL

Example:

{
  "type": "org.osbuild.apt",
  "options": {
    "packages": [
      "linux-image-amd64",
      "systemd",
      "openssh-server",
      "curl",
      "vim"
    ],
    "recommends": false,
    "update": true
  }
}

4. org.osbuild.debian.source

Downloads and manages Debian source packages.

Options:

• source_package (string, required): Source package to download
• suite (string, optional): Debian suite to download from (default: "bookworm")
• mirror (string, optional): Debian mirror URL
• apt_proxy (string, optional): apt-cacher-ng proxy URL

Example:

{
  "type": "org.osbuild.debian.source",
  "options": {
    "source_package": "linux",
    "suite": "trixie",
    "mirror": "http://deb.debian.org/debian"
  }
}

Complete Example

Here's a complete example manifest that creates a minimal Debian Trixie image:

{
  "version": "2",
  "pipelines": [
    {
      "runner": "org.osbuild.linux",
      "name": "build",
      "stages": [
        {
          "type": "org.osbuild.debootstrap",
          "options": {
            "suite": "trixie",
            "mirror": "http://deb.debian.org/debian",
            "arch": "amd64",
            "variant": "minbase",
            "extra_packages": ["apt", "systemd", "bash"]
          }
        },
        {
          "type": "org.osbuild.apt.config",
          "options": {
            "sources": {
              "debian": "deb http://deb.debian.org/debian trixie main\n"
            }
          }
        },
        {
          "type": "org.osbuild.apt",
          "options": {
            "packages": [
              "linux-image-amd64",
              "systemd",
              "openssh-server",
              "curl",
              "vim"
            ],
            "recommends": false,
            "update": true
          }
        }
      ]
    }
  ]
}

Features

Repository Management

• Support for multiple APT repositories
• Custom sources.list configuration
• GPG key handling for repository authentication
• Proxy support for apt-cacher-ng

Package Management

• Full APT package installation
• Dependency resolution using APT's solver
• Package recommendations control
• Unauthenticated package support

Cross-Architecture Support

• Support for amd64, arm64, and other architectures
• Architecture-specific package installation
• Multi-arch repository support

Performance Features

• APT caching and optimization
• Non-interactive operation (DEBIAN_FRONTEND=noninteractive)
• Package cache cleanup
• Proxy support for faster downloads

Troubleshooting

Common Issues

1. Package not found: Ensure the package name is correct and available in the specified suite
2. Repository errors: Check the mirror URL and suite name
3. Architecture issues: Verify the target architecture is supported
4. Network issues: Use apt-cacher-ng proxy for faster downloads

Debug Mode

Use the --break option to debug stage execution:

python3 -m osbuild manifest.json --break org.osbuild.apt

Logs

Check the build logs for detailed error information:

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

See Also

• Debian Forge Documentation
• Example Manifests
• OSBuild Documentation