APTLY(1)

NAME
aptly - Debian repository management tool

SYNOPSIS
Common command format:

aptly [global options...] command subcommand [options...] arguments

aptly has integrated help that matches contents of this manual page, to get help, prepend help to command name:

aptly help mirror create

DESCRIPTION
aptly is a tool to create partial and full mirrors of remote repositories, manage local repositories, filter them, merge, upgrade individual packages, take snapshots and publish them back as Debian repositories.

aptly goal is to establish repeatiblity and controlled changes in package environment. aptly allows to fix set of packages in repository, so that package installation and upgrade becomes deterministic. At the same time aptly allows to perform controlled, fine-grained changes in repository contents to transition your package environment to new version.

CONFIGURATION
aptly looks for configuration file in /etc/aptly.conf and ~/.aptly.conf, if no config file found, new one is created. If -config= flag is specified, aptly would use config file at specified location. Also aptly needs root directory for database, package and published repository storage. If not specified, directory defaults to ~/.aptly, it will be created if missing.

Configuration file is stored in JSON format (default values shown below):

    {
      "rootDir": "$HOME/.aptly",
      "downloadConcurrency": 4,
      "architectures": [],
      "dependencyFollowSuggests": false,
      "dependencyFollowRecommends": false
      "dependencyFollowAllVariants": false,
      "dependencyFollowSource": false,
      "gpgDisableSign": false,
      "gpgDisableVerify": false,
      "downloadSourcePackages": false,
      "ppaDistributorID": "ubuntu",
      "ppaCodename": ""
    }

Options:

rootDir
    is root of directory storage to store database (rootDir/db), downloaded packages (rootDir/pool) and published repositories (rootDir/public)

downloadConcurrency
    is a number of parallel download threads to use when downloading packages

architectures
    is a list of architectures to process; if left empty defaults to all available architectures; could be overridden with option -architectures

dependencyFollowSuggests
    follow contents of Suggests: field when processing dependencies for the package

dependencyFollowRecommends
    follow contents of Recommends: field when processing dependencies for the package

dependencyFollowAllVariants
    when dependency looks like package-a | package-b, follow both variants always

dependencyFollowSource
    follow dependency from binary package to source package

gpgDisableSign
    don't sign published repositories with gpg(1), also can be disabled on per-repo basis using -skip-signing flag when publishing

gpgDisableVerify
    don't verify remote mirrors with gpg(1), also can be disabled on per-mirror basis using -ignore-signatures flag when creating and updating mirrors

downloadSourcePackages
    if enabled, all mirrors created would have flag set to download source packages; this setting could be controlled on per-mirror basis with -with-sources flag

ppaDistributorID, ppaCodename
    specifies paramaters for short PPA url expansion, if left blank they default to output of lsb_release command

PACKAGE SPEC
Some commands accept package specs to identify list of packages to process. Package spec is a list of following search conditions:

direct package reference
    reference to exaclty one package. Format is identical to the way aptly lists packages in show commands with -with-packages flag: name_version_arch, e.g.: libmysqlclient18_5.5.35-rel33.0-611.squeeze_amd64

dependency condition
    syntax follows Debian dependency specification: package_name followed by optional version specification and architecture limit.

Examples:

mysql-client
    matches package mysql-client of any version and architecture (including source)

mysql-client (>= 3.6)
    matches package mysql-client with version greater or equal to 3.6. Valid operators for version are: >=, <=, =, >> (strictly greater), << (strictly less).

mysql-client {i386}
    matches package mysql-client on architecture i386, architecture all matches all architectures but source.

mysql-client (>= 3.6) {i386}
    version and architecture conditions combined.

When specified on command line, condition may have to be quoted according to shell rules, so that it stays single argument:

aptly repo import percona stable 'mysql-client (>= 3.6)'

GLOBAL OPTIONS

-architectures=
    list of architectures to consider during (comma-separated), default to all available

-config=
    location of configuration file (default locations are /etc/aptly.conf, ~/.aptly.conf)

-cpuprofile=
    write cpu profile to file

-dep-follow-all-variants=false
    when processing dependencies, follow a & b if depdency is 'a|b'

-dep-follow-recommends=false
    when processing dependencies, follow Recommends

-dep-follow-source=false
    when processing dependencies, follow from binary to Source packages

-dep-follow-suggests=false
    when processing dependencies, follow Suggests

-meminterval=100ms
    memory stats dump interval

-memprofile=
    write memory profile to this file

-memstats=
    write memory stats periodically to this file

CREATE NEW MIRROR
aptly mirror create name archive url distribution [component1 ...]

Creates mirror name of remote repository, aptly supports both regular and flat Debian repositories exported via HTTP. aptly would try download Release file from remote repository and verify its signature.

PPA urls could specified in short format:

$ aptly mirror create name ppa:user/project

Example:

$ aptly mirror create wheezy-main http://mirror.yandex.ru/debian/ wheezy main

Options:

-ignore-signatures=false
    disable verification of Release file signatures

-keyring=
    gpg keyring to use when verifying Release file (could be specified multiple times)

-with-sources=false
    download source packages in addition to binary packages

LIST MIRRORS
aptly mirror list

List shows full list of remote repository mirrors.

Example:

$ aptly mirror list

SHOW DETAILS ABOUT MIRROR
aptly mirror show name

Shows detailed information about mirror.

Example:

$ aptly mirror show wheezy-main

Options:

-with-packages=false
    show detailed list of packages and versions stored in the mirror

DELETE MIRROR
aptly mirror drop name

Drop deletes information about remote repository mirror name. Package data is not deleted (it could be still used by other mirrors or snapshots). If mirror is used as source to create a snapshot, aptly would refuse to delete such mirror, use flag -force to override.

Example:

$ aptly mirror drop wheezy-main

Options:

-force=false
    force mirror deletion even if used by snapshots

UPDATE MIRROR
aptly mirror update name

Updates remote mirror (downloads package files and meta information). When mirror is created, this command should be run for the first time to fetch mirror contents. This command could be run many times to get updated repository contents. If interrupted, command could be restarted safely.

Example:

$ aptly mirror update wheezy-main

Options:

-ignore-checksums=false
    ignore checksum mismatches while downloading package files and metadata

-ignore-signatures=false
    disable verification of Release file signatures

-keyring=
    gpg keyring to use when verifying Release file (could be specified multiple times)

ADD PACKAGES TO LOCAL REPOSITORY
aptly repo add name

Command adds packages to local repository from .deb (binary packages) and .dsc (source packages) files. When importing from directory aptly would do recursive scan looking for all files matching .deb or.dsc patterns. Every file discovered would be analyzed to extract metadata, package would be created and added to database. Files would be imported to internal package pool. For source packages, all required files are added as well automatically. Extra files for source package should be in the same directory as *.dsc file.

Example:

$ aptly repo add testing myapp-0.1.2.deb incoming/

Options:

-remove-files=false
    remove files that have been imported successfully into repository

COPY PACKAGES BETWEEN LOCAL REPOSITORIES
aptly repo copy src-name dst-name package-spec ...

Command copy copies packages matching package-spec from local repo src-name to local repo dst-name.

Example:

$ aptly repo copy testing stable 'myapp (=0.1.12)'

Options:

-dry-run=false
    don't copy, just show what would be copied

-with-deps=false
    follow dependencies when processing package-spec

CREATE LOCAL REPOSITORY
aptly repo create name

Create local package repository. Repository would be empty when created, packages could be added from files, copied or moved from another local repository or imported from the mirror.

Example:

$ aptly repo create testing

Options:

-comment=
    any text that would be used to described local repository

DELETE LOCAL REPOSITORY
aptly repo drop name

Drop deletes information about local repo. Package data is not deleted (it could be still used by other mirrors or snapshots).

Example:

$ aptly repo drop local-repo

Options:

-force=false
    force local repo deletion even if used by snapshots

IMPORT PACKAGES FROM MIRROR TO LOCAL REPOSITORY
aptly repo import src-mirror dst-repo package-spec ...

Command import looks up packages matching package-spec in mirror src-mirror and copies them to local repo dst-repo.

Example:

$ aptly repo import wheezy-main testing nginx

Options:

-dry-run=false
    don't import, just show what would be imported

-with-deps=false
    follow dependencies when processing package-spec

LIST LOCAL REPOSITORIES
aptly repo list

List shows full list of local package repositories.

Example:

$ aptly repo list

MOVE PACKAGES BETWEEN LOCAL REPOSITORIES
aptly repo move src-name dst-name package-spec ...

Command move moves packages matching package-spec from local repo src-name to local repo dst-name.

Example:

$ aptly repo move testing stable 'myapp (=0.1.12)'

Options:

-dry-run=false
    don't move, just show what would be moved

-with-deps=false
    follow dependencies when processing package-spec

REMOVE PACKAGES FROM LOCAL REPOSITORY
aptly repo remove name package-spec ...

Commands removes packages matching package-spec from local repository name. If removed packages are not referenced by other repos or snapshots, they can be removed completely (including files) by running 'aptly db cleanup'.

Example:

$ aptly repo remove testing 'myapp (=0.1.12)'

Options:

-dry-run=false
    don't remove, just show what would be removed

SHOW DETAILS ABOUT LOCAL REPOSITORY
aptly repo show name

Show shows full information about local package repository.

ex: $ aptly repo show testing

Options:

-with-packages=false
    show list of packages

CREATES SNAPSHOT OF MIRROR (LOCAL REPOSITORY) CONTENTS
aptly snapshot create name from mirror mirror-name | from repo repo-name | empty

Command create name from mirror makes persistent immutable snapshot of remote repository mirror. Snapshot could be published or further modified using merge, pull and other aptly features.

Command create name from repo makes persistent immutable snapshot of local repository. Snapshot could be processed as mirror snapshots, and mixed with snapshots of remote mirrors.

Command create name empty creates empty snapshot that could be used as a basis for snapshot pull operations, for example. As snapshots are immutable, creating one empty snapshot should be enough.

Example:

$ aptly snapshot create wheezy-main-today from mirror wheezy-main

LIST SNAPSHOTS
aptly snapshot list

Command list shows full list of snapshots created.

Example:

$ aptly snapshot list

SHOWS DETAILS ABOUT SNAPSHOT
aptly snapshot show name

Command show displays full information about snapshot.

Example:

    $ aptly snapshot show wheezy-main

Options:

-with-packages=false
    show list of packages

VERIFY DEPENDENCIES IN SNAPSHOT
aptly snapshot verify name [source ...]

Verify does depenency resolution in snapshot name, possibly using additional snapshots source as dependency sources. All unsatisfied dependencies are printed.

Example:

    $ aptly snapshot verify wheezy-main wheezy-contrib wheezy-non-free

PULL PACKAGES FROM ANOTHER SNAPSHOT
aptly snapshot pull name source destination package-name ...

Command pull pulls new packages along with its dependencies to snapshot name from snapshot source. Pull can upgrade package version in name with versions from source following dependencies. New snapshot destination is created as result of this process. Packages could be specified simply as 'package-name' or as dependency 'package-name (>= version)'.

Example:

    $ aptly snapshot pull wheezy-main wheezy-backports wheezy-new-xorg xorg-server-server

Options:

-dry-run=false
    don't create destination snapshot, just show what would be pulled

-no-deps=false
    don't process dependencies, just pull listed packages

-no-remove=false
    don't remove other package versions when pulling package

DIFFERENCE BETWEEN TWO SNAPSHOTS
aptly snapshot diff name-a name-b

Displays difference in packages between two snapshots. Snapshot is a list of packages, so difference between snapshots is a difference between package lists. Package could be either completely missing in one snapshot, or package is present in both snapshots with different versions.

Example:

    $ aptly snapshot diff -only-matching wheezy-main wheezy-backports

Options:

-only-matching=false
    display diff only for matching packages (don't display missing packages)

MERGES SNAPSHOTS
aptly snapshot merge destination source [source...]

Merge merges several source snapshots into one destination snapshot. Merge happens from left to right. Packages with the same name-architecture pair are replaced during merge (package from latest snapshot on the list wins). If run with only one source snapshot, merge copies source into destination.

Example:

    $ aptly snapshot merge wheezy-w-backports wheezy-main wheezy-backports

DELETE SNAPSHOT
aptly snapshot drop name

Drop removes information about snapshot. If snapshot is published, it can't be dropped.

Example:

    $ aptly snapshot drop wheezy-main

Options:

-force=false
    remove snapshot even if it was used as source for other snapshots

PUBLISH SNAPSHOT
aptly publish snapshot name [prefix]

Command publish publishes snapshot as Debian repository ready to be consumed by apt tools. Published repostiories appear under rootDir/public directory. Valid GPG key is required for publishing.

Example:

    $ aptly publish snapshot wheezy-main

Options:

-component=
    component name to publish

-distribution=
    distribution name to publish

-gpg-key=
    GPG key ID to use when signing the release

-keyring=
    GPG keyring to use (instead of default)

-secret-keyring=
    GPG secret keyring to use (instead of default)

-skip-signing=false
    don't sign Release files with GPG

LIST OF PUBLISHED REPOSITORIES
aptly publish list

Display list of currently published snapshots.

Example:

    $ aptly publish list

REMOVE PUBLISHED REPOSITORY
aptly publish drop distribution [prefix]

Command removes whatever has been published under specified prefix and distribution name.

Example:

    $ aptly publish drop wheezy

CLEANUP DB AND PACKAGE POOL
aptly db cleanup

Database cleanup removes information about unreferenced packages and removes files in the package pool that aren't used by packages anymore

Example:

$ aptly db cleanup

HTTP SERVE PUBLISHED REPOSITORIES
aptly serve

Command serve starts embedded HTTP server (not suitable for real production usage) to serve contents of public/ subdirectory of aptly's root that contains published repositories.

Example:

$ aptly serve -listen=:8080

Options:

-listen=:8080
    host:port for HTTP listening

RENDER GRAPH OF RELATIONSHIPS
aptly graph

Command graph displays relationship between mirrors, local repositories, snapshots and published repositories using graphviz package to render graph as image.

Example:

$ aptly graph

ENVIRONMENT
If environment variable HTTP_PROXY is set aptly would use its value to proxy all HTTP requests.

RETURN VALUES
aptly exists with 0 on success and with 1 on failure.

AUTHORS
Andrey Smirnov (me@smira.ru)