aptly Documentation

Aptly is a tool for Debian repository management. Key capabilities include:

• Mirroring: Create mirrors of remote Debian/Ubuntu repositories with component and architecture limits.
• Snapshots: Take snapshots of mirrors to fix the state of a repository at a specific moment.
• Publishing: Publish snapshots as Debian repositories consumable by apt.
• Controlled Updates: Update specific packages in a snapshot from an upstream mirror while tracking dependencies.
• Merging: Merge multiple snapshots into one.
• Filtering: Filter repositories by search query and pull required dependencies.
• Self-made Packages: Publish your own packages as Debian repositories.
• REST API: Remote access via a REST API.

Aptly allows you to manage mirrors of remote Debian repositories. It supports protocols such as http, https, and ftp.

Supported mirroring tasks include:

• Mirroring flat Debian repositories.
• Mirroring source packages.
• Mirroring Debian installers.

Aptly operations can be performed using a REST API. To enable the API, run the following command:

aptly api serve

Security Warning: The REST API does not include built-in authentication or protection. It should not be exposed directly to the internet. It is highly recommended to use an HTTP proxy (such as nginx) to provide HTTPS and implement authentication layers.

To enable zsh command completion for the aptly CLI, you must place the _aptly file into a directory included in your $fpath.

Follow these steps to create a dedicated functions directory and add it to your path:

1. Create a directory for your custom functions.
2. Add that directory to your fpath in your .zshrc (or equivalent configuration).
3. Place the _aptly file into that directory.

Note: For best results with help messages and completions, ensure your zsh configuration is properly set up (tested with grml-zsh).

mkdir -p ~/.zsh/functions
fpath=(~/.zsh/functions $fpath)
editor ~/.zsh/functions/_aptly

You can create snapshots of Local Repositories and Mirrors in aptly to capture an immutable state of your package collections. Once a snapshot is created, you can perform the following operations:

• Merge: Combine multiple snapshots.
• Filter: Create new snapshots based on specific criteria.
• Verify: Check snapshots for missing dependencies.
• Publish: Turn a snapshot into an APT source that can be used by clients.

Certain API operations in aptly can be executed asynchronously as background tasks. When an operation is run this way, the API returns a Task object containing a unique ID and a State. You can use this ID to query the task's progress.

Important: To prevent memory overflows, you must manually delete tasks once they are no longer in progress.

Binary executables (depending primarily on libc) are available via GitHub Releases for:

• macOS / darwin (amd64, arm64)
• FreeBSD (amd64, arm64, 386, arm)
• Generic Linux (amd64, arm64, 386, arm)

To add Debian package files to a local repository, you must follow a two-step process:

1. Upload to a temporary directory: Files are first uploaded to a temporary directory located under <rootDir>/upload/<tempdir>.
2. Add to repository: Once uploaded, you add the directory (or a specific file within it) to the repository.

Important Notes:

• Cleanup: By default, the temporary directory or files are removed automatically after they have been added to a repository.
• Concurrency: If performing concurrent uploads from CI/CD pipelines, ensure that each process uses a unique <tempdir> to avoid collisions.

A GPG key is required to sign any published repository. You can define multiple signing keys to facilitate key rotation.

To use multiple keys, you can:

1. Define them in aptly.conf using the gpgKeys array.
2. Pass them via the CLI using multiple --gpg-key flags.
3. Provide a comma-separated list of key IDs via the REST API gpgKey parameter.

Note: CLI flags and REST API parameters take precedence over the aptly.conf configuration. When multiple keys are provided, aptly signs all Release files (both clearsigned and detached signatures) with each key.

// In aptly.conf
"gpgKeys": [
    "KEY_ID_x",
    "KEY_ID_y"
]