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

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

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

### Logs

Check the build logs for detailed error information:

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

## See Also

- [Debian Forge Documentation](../README.md)
- [Example Manifests](../test/data/manifests/debian/)
- [OSBuild Documentation](https://osbuild.org/)