aptly: Debian repository management from mirror to published snapshot

What aptly does that a plain apt mirror does not

A normal Debian mirror is a moving target. Files appear and disappear as upstream pushes updates, so two machines that run apt-get update an hour apart can see different package sets. aptly separates the two halves of that problem. On one side it mirrors a remote Debian or Ubuntu repository, optionally limiting which components and architectures it pulls. On the other side it publishes a repository that apt clients can consume. Between the two sits the snapshot, which fixes the state of a mirror at a point in time.

The audience is anyone who has to answer the question "which exact package versions did we ship last month". Internal build farms that need a stable package set for reproducible images, teams that want to promote packages through environments the way they promote application code, and anyone maintaining a private apt repository that mixes upstream packages with their own. The README describes the tool as "a swiss army knife for Debian repository management", which is a fair description of the surface area: mirroring, snapshotting, merging, filtering, publishing, and a REST API.

Snapshots, published repositories and the local database

The pipeline is mirror, snapshot, publish. A mirror is a local record of a remote repository. A snapshot is a copy of that record frozen at a moment. A published repository is a snapshot (or a merge of several snapshots) laid out on disk or pushed to a storage backend so that apt can fetch it.

Snapshots are not file copies. They are metadata plus references into the package pool, which is why merging two snapshots or filtering one by a search query is cheap compared to re-downloading packages. The README lists filtering a repository by search query with dependency pulling as a feature, and that is the operation that makes partial mirrors practical: you can take a snapshot and then narrow it to a package and everything it depends on.

The state lives in a local database. go.mod lists github.com/syndtr/goleveldb, a LevelDB binding, and the repository has a top-level database/ directory. That tells you the working model: aptly is a stateful local process, not a stateless proxy. The database directory is the thing you back up, and a snapshot is only as durable as that directory. The README does not document rollback of a database migration, so treat version upgrades of the binary as a checkpoint operation.

Publishing targets are visible in the repository layout. There are top-level directories named s3/, swift/, gcs/, azure/ and jfrog/, so the same published repository can be written to local files or to object storage. Configuration for those backends is not spelled out in the README; it lives in the documentation site and the man pages under _man/ and man/.

Installing aptly on Debian or Ubuntu

The README gives two routes. The simplest is the distribution package. aptly is available in the official Debian and Ubuntu archives, and the README names three binary packages: aptly for the CLI, man pages and shell completions, aptly-api for a systemd service exposing the REST API against /etc/aptly.conf, and aptly-dbg for debug symbols.

apt-get update
apt-get install aptly
apt-get install aptly-api  # REST API systemd service

If you need a version newer than your distribution ships, the README describes adding an upstream apt source. First fetch the signing key as root, then add a source line pointing at repo.aptly.info/release with the codename for your distribution.

wget -O /etc/apt/keyrings/aptly.asc https://www.aptly.info/pubkey.txt

deb [signed-by=/etc/apt/keyrings/aptly.asc] http://repo.aptly.info/release DIST main

The README lists DIST as one of bullseye, bookworm, trixie, focal, jammy or noble. There is a parallel CI source at repo.aptly.info/ci built from master, which the README explicitly flags as possibly unstable, and it uses the same signing key. For macOS, FreeBSD and generic Linux, the README points at prebuilt binaries on GitHub Releases rather than a package manager.

The README lists the features as mirroring, snapshotting, publishing, controlled updates from upstream, merging snapshots, filtering by search query, publishing self-made packages, and a REST API. It does not print a full worked example, so the operational sequence is documented on the project's documentation site rather than in the README.

Where aptly is the wrong tool

aptly assumes you are managing a repository whose contents come from somewhere else, or from your own build output that you want to publish as an apt source. If your actual need is to serve ten hand-built .deb files to a handful of machines over HTTPS, the snapshot and mirror machinery is weight you will never use, and you will still have to operate a local database directory.

The stateful design is the sharpest limitation. Because mirrors, snapshots and published repositories live in a LevelDB database on one host, aptly is not something you can run as two interchangeable replicas behind a load balancer. Concurrent writes to the same database directory are not a supported pattern, and the README does not describe a multi-writer mode. Plan for a single writer and a backup of the database directory, not for horizontal scaling.

The second limitation is documentation coverage in the README itself. It covers installation thoroughly and lists features, but the operational detail (storage backend configuration, publishing endpoints, GPG signing setup) is deferred to the documentation site and the man pages. If you are evaluating aptly from the README alone, you will not find the answers to how signing keys are configured or how the S3 backend is parameterised. That is not a defect in the tool, but it does mean the README is a starting point rather than a reference.

aptly compared with reprepro

reprepro is the older answer to the same problem, and the difference is architectural. reprepro works directly on a directory tree of packages and generates the Packages and Release files in place. There is no separate mirror object and no snapshot object; the repository directory is the state. That makes it easy to reason about and easy to back up with rsync, and it is a good fit when all your packages are built by you.

aptly inserts a database between you and the published tree. The payoff is that mirroring a remote repository, freezing it, merging two frozen sets, and filtering by dependency query all become first-class operations. The cost is that the published tree is an output, not the source of truth, and the source of truth is a LevelDB directory you cannot inspect with ls.

If your workflow is "we build packages, we sign them, we serve them", reprepro's model maps directly onto it. If your workflow involves tracking upstream Debian or Ubuntu repositories and controlling exactly when your machines see a change, aptly's snapshot layer is the reason to pick it. Jenny, listed in the README's integrations, occupies similar ground for Debian-like distributions and is described there as currently only in French, which is a practical constraint if your team does not read French.

Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-09-17. Releases are not rapid: v1.6.3 is dated 2026-06-25, v1.6.2 is dated 2025-06-09, and v1.6.1 is dated 2025-02-15. That cadence suggests a project that ships when there is something to ship rather than on a schedule, and it means a bug you hit may sit until the next minor release.

Upgrade cost depends on which install route you chose. If you use the distribution package, upgrades arrive with your normal apt workflow, but the version you get is whatever Debian or Ubuntu packaged. If you use the upstream source, you control the version and take on the responsibility of testing it. The README's separate aptly-api package means the REST service has its own upgrade path and its own systemd unit, so a CLI upgrade and an API upgrade are two operations, not one.

The licence is MIT. That is permissive: it permits use, modification and redistribution with the licence text preserved, and it imposes no copyleft obligation on your own packages. It says nothing about the licences of the Debian packages you mirror or publish through aptly, which are governed by their own copyright files. This is a description of the licence identifier, not legal advice; if you are redistributing a repository to third parties, the package-level licences are the ones that matter.

Editorial conclusion

Adopt aptly if you need to freeze a set of Debian packages at a moment in time and serve that frozen set to your own machines, and if you are willing to run and back up a LevelDB state directory. Do not adopt it if you only need to serve a handful of hand-built .deb files, where a static directory plus reprepro is less machinery. Before committing, verify that your target distributions are among the codenames the upstream package repository lists, and check whether you need the REST API service, since that is a separate package with its own systemd unit.

Frequently asked questions

Official sources

1. aptly-dev/aptly on GitHub
2. License: MIT
3. Project website
4. README
5. Releases