1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with aptly
   • What aptly affects
   • Setup requirements
   • Beginning with aptly
4. Usage - Configuration options and additional functionality
   • Basic example
   • Enable aptly API endpoint
   • Create an apt mirror
   • Create and drop apt repositories
   • Create an aptly snapshot
5. Reference - An under-the-hood peek at what the module is doing and how

• Public classes and defines
• Private classes
• Providers and types
• Parameters

5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

This module installs the aptly Debian packages repository manager and configures it.

Need help of want a new feature? File an issue on our github repository: https://github.com/tubemogul/puppet-aptly/issues

What is this module capable of doing?

• Installing the aptly package in a specific version (or just the latest available)
• Managing a specific user and group (with their corresponding fixed uid/gid) dedicated to the service
• Configuring a specific debian repository (optional) where to find the package
• Managing the /etc/aptly.conf file
• Enabling/starting or disabling the service
• Enabling/starting or disabling the API
• Managing the init.d service file
• Managing apt mirrors, repositories, snapshots and publications

The aptly service will listen on port you configure (example: 8080) on every interfaces (configurable) using the aptly serve -listen=":8080" command.

If you want to make the repository being served by an apache, nginx or whatever else, just disable the service and setup the http server you want for the HTTP(S) layer in addition to this module.

Files managed by the module:

• /etc/aptly.conf
• /etc/apt/sources.list.d/aptly.list (optional)
• /etc/init.d/aptly

The module requires:

• Puppetlabs stdlib
• Puppetlab's APT module at least version 2.0.x

The module can be used out of the box directly, it just requires puppetlabs' apt module and its stdlib to be in your modulepath.

To install:

puppet module install TubeMogul/aptly

Puppet will install the dependencies automatically, but if you want to install the dependencies 1 by 1, you can use this before:

puppet module install puppetlabs/stdlib
puppet module install puppetlabs/apt

WARNING: the aptly service won't start as long as nothing has been published in it. It is a totally expected behavior coming from aptly itself.

Those examples include the puppet-only configuration, and the corresponding configuration for those who use hiera (I find it more convenient for copy/paste of a full configuration when you have both - yes, I'm lazy ;-) ).

The default values are normally sane enough to do as few parameters overwrites as possible.

But let's say you want:

• Aptly to store its data in /data (that you created before hand)
• to only have the architectures i386 and amd64
• to have your ppa codename to be foo

Then you just do:

class { 'aptly':
  root_dir      => '/data',
  architectures => ['i386', 'amd64'],
  ppa_codename  => 'foo',
}

Or using hiera:

---
aptly::root_dir: /data
aptly::architectures:
  - i386
  - amd64
aptly::ppa_codename: foo

NOTE: this will also install the official aptly repo in your sources.list.d.

To:

• enable the aptly API management
• make the API listen on port 42000
• have the API listen on the private interface of your server (let's say this interface's IP is 10.0.0.123)
• have the API configured in no-lock mode as you are doing both cli and API calls

Then you can do:

class { 'aptly':
  enable_api => true,
  api_port   => 42000,
  api_bind   => '10.0.0.123',
  api_nolock => true,
}

Or using hiera:

---
aptly::enable_api: true
aptly::api_port: 42000
aptly::api_bind: 10.0.0.123
aptly::api_nolock: true

Warning: after creating the mirror, the update of the mirror from its source is initiated. This can take a significant amount of time.

To create an APT repository:

• of the Debian US repo
• of the stable distribution
• only taking the main component
• only for the amd64 architecture

Use:

aptly::mirror { 'debian_stable':
  location      => 'http://ftp.us.debian.org/debian/',
  distribution  => 'stable',
  components    => [ 'main' ],
  architectures => ['amd64'],
}

Note: This module does not manage the gpg keys directly, so if you don't take care of adding the gpg file of your target repository, you'll end up with the following error:

Error: /Stage[main]/Main/Aptly::Mirror[debian_stable]/Aptly_mirror[debian_stable]/ensure: change from absent to present failed: Execution of 'aptly -architectures=amd64 -with-sources=false -with-udebs=false mirror create debian_stable http://ftp.us.debian.org/debian/ stable main' returned 1: Looks like your keyring with trusted keys is empty. You might consider importing some keys.
If you're running Debian or Ubuntu, it's a good idea to import current archive keys by running:

  gpg --no-default-keyring --keyring /usr/share/keyrings/debian-archive-keyring.gpg --export | gpg --no-default-keyring --keyring trustedkeys.gpg --import

(for Ubuntu, use /usr/share/keyrings/ubuntu-archive-keyring.gpg)

Downloading http://ftp.us.debian.org/debian/dists/stable/InRelease...
Downloading http://ftp.us.debian.org/debian/dists/stable/Release...
Downloading http://ftp.us.debian.org/debian/dists/stable/Release.gpg...
gpgv: Signature made Sat Jun  4 08:26:51 2016 GMT+5 using RSA key ID 46925553
gpgv: Can't check signature: public key not found
gpgv: Signature made Sat Jun  4 08:26:51 2016 GMT+5 using RSA key ID 2B90D010
gpgv: Can't check signature: public key not found
gpgv: Signature made Sat Jun  4 08:36:26 2016 GMT+5 using RSA key ID 518E17E1
gpgv: Can't check signature: public key not found

Looks like some keys are missing in your trusted keyring, you may consider importing them from keyserver:

gpg --no-default-keyring --keyring trustedkeys.gpg --keyserver keys.gnupg.net --recv-keys 8B48AD6246925553 7638D0442B90D010 CBF8D6FD518E17E1

Sometimes keys are stored in repository root in file named Release.key, to import such key:

wget -O - https://some.repo/repository/Release.key | gpg --no-default-keyring --keyring trustedkeys.gpg --import

ERROR: unable to fetch mirror: verification of detached signature failed: exit status 2

Here's a full example of how you can manage your gpg keys along with the mirror:

aptly::mirror { 'debian_stable':
  location      => 'http://ftp.us.debian.org/debian/',
  distribution  => 'stable',
  components    => [ 'main'] ,
  architectures => ['amd64'],
}

exec { 'debian_stable_key_8B48AD6246925553':
  command => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --keyserver keys.gnupg.net --recv-key 8B48AD6246925553',
  unless  => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --list-key 8B48AD6246925553 > /dev/null 2>&1',
}

exec { 'debian_stable_key_7638D0442B90D010':
  command => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --keyserver keys.gnupg.net --recv-key 7638D0442B90D010',
  unless  => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --list-key 7638D0442B90D010 > /dev/null 2>&1',
}

exec { 'debian_stable_key_CBF8D6FD518E17E1':
  command => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --keyserver keys.gnupg.net --recv-key CBF8D6FD518E17E1',
  unless  => '/usr/bin/gpg --no-default-keyring --keyring trustedkeys.gpg --list-key CBF8D6FD518E17E1 > /dev/null 2>&1',
}


Exec['debian_stable_key_8B48AD6246925553']->
Exec['debian_stable_key_7638D0442B90D010']->
Exec['debian_stable_key_CBF8D6FD518E17E1']->
Aptly::Mirror['debian_stable']

Using the aptly::repo is really simple. In this example, we will:

• drop the my_custom_repo repository
• create the tubemogul_apps repository (with "stable" as default component for publishing)

Use:

# Dropping the 'my_custom_repo' repo
aptly::repo {'my_custom_repo':
  ensure => absent,
}

# Making sure that the 'tubemogul_apps' exists with the expected parameters
aptly::repo {'tubemogul_apps':
  default_component => 'stable',
}

Once you've done that, you can add packages using the aptly repo add tubemogul_apps my_package.deb or using the API.

Once you've created your repo and added packages to it, you might want to take a snapshot of a stable stack or a coherent ensemble to publish it later.

This example creates a snapshot named nightly_20160823 based on the repository tubemogul_apps that we created in the previous example:

aptly::snapshot { 'nightly_20160823':
  source_type => 'repository',
  source_name => 'tubemogul_apps',
}

• aptly: Installs and configures the aptly server.
• aptly::mirror: Manages an aptly mirror.
• aptly::repo: Manages an aptly repository.
• aptly::snapshot: Manages an aptly snapshot.
• aptly::publish: Manages an aptly publication.

• aptly::install: Installs the aptly server.
• aptly::config: Configures the aptly server.
• aptly::service: Manages the aptly server and the API services.

To manage the aptly resources, this modules embeds the following custom types and corresponding providers (to be accessed via the public defines):

• aptly_mirror to manage an aptly mirror
• aptly_repo to manage an aptly repository
• aptly_snapshot to manage an aptly snapshot
• aptly_publish to manage an aptly publication

Aptly version to ensure to install. You can use a version number to force a version or just use installed or latest to benefit from the usual Puppet behavior.

Default: installed

Boolean to manage whether or not you want to have a sources.list repo managed by the module.

Default: true

Location of the remote repo to manage when using install_repo to true.

Default: http://repo.aptly.info

Release of the repo to use when using install_repo to true.

Default: squeeze

Repo name to use in the repo when using install_repo to true.

Default: main

Key server to use to retreive the key of the repo when using install_repo to true.

Default: keys.gnupg.net

Key used by the signed repo when using install_repo to true.

Default: DF32BC15E2145B3FA151AED19E3E53F19C7DE460

Boolean to enable or disable the service.

Default: true (service enabled)

Port for the Aptly webserver

Default : 8080

IP address of the Aptly webserver (0.0.0.0 or empty string meaning that you listen on all interfaces).

Default: 0.0.0.0

Path of the configuration file to be used by the aptly service.

Default: /etc/aptly.conf

Whethere should this module manage aptly user or not

Default: true

OS user which will run the service.

Default: aptly

UID of the OS user which will run the service.

Default: 450

Group of the OS user which will run the service.

Default: aptly

GID of the group of the OS user which will run the service.

Default: 450

Root directory to use for storing the repo data.

Default: /var/aptly

Architectures managed by the repo.

Default: ["amd64"]

Distribution code of the ppa to serve.

Default: ubuntu

Codename of the ppa to serve.

Default: ''

Hash containing the optional properties of the aptly.conf. The key is the property name and the value is its value!

Default:

{
  'downloadConcurrency'         => 4,
  'downloadSpeedLimit'          => 0,
  'dependencyFollowSuggests'    => false,
  'dependencyFollowRecommends'  => false,
  'dependencyFollowAllVariants' => false,
  'dependencyFollowSource'      => false,
  'gpgDisableSign'              => false,
  'gpgDisableVerify'            => false,
  'downloadSourcePackages'      => false,
}

Hash to describe the s3PublishEndpoints property of the aptly.conf.

Default: {}

Hash to describe the SwiftPublishEndpoints property of the aptly.conf.

Default: {}

Enable Aptly API by starting the service

Default : false

Port for the Aptly API service.

Default : 8081

Binding address for the Aptly API service.

Default : 0.0.0.0

If true, the API service will not lock the database (for situations where you heavily use both the API and the cli for example).

Default : false

Boolean to enable or disable installation of the xz-utils package (required dependency for aptly).

Default : true

Ensures if the mirror must be present (should exist) or absent (or be destroyed).

Default: present

UID of the OS user which will run the cli

Default: 450

GID of the OS user which will run the cli

Default: 450

Location of the repository to mirror.

Default: undef

Distribution to mirror.

Default: $::lsbdistcodename

Architectures to mirror.

Default: []

Components to mirror.

Default: []

Mirror the sources packages or not.

Default: false

Download the .udeb packages.

Default: false

Ensures if the repository must be present (should exist) or absent (or be destroyed).

Default: present

UID of the OS user which will run the cli

Default: 450

GID of the OS user which will run the cli

Default: 450

Default distribution (used only when publishing).

Default: $::lsbdistcodename

Default component (used only when publishing).

Default: main

Ensures if the snapshot must be present (should exist) or absent (or be destroyed).

Default: present

UID of the OS user which will run the cli

Default: 450

GID of the OS user which will run the cli

Default: 450

Type of source to snapshot. Correct values are:

• mirror
• repo
• empty

Default: undef

Name of the source to create snapshot from.

Default: undef

Ensures that the publication is present (should exist) or absent (or should be destroyed).

Default: present

UID of the OS user which will run the cli

Default: 450

GID of the OS user which will run the cli

Default: 450

Type of source to publish. Supported values are:

• repo
• snapshot

Default: undef

Distribution name to publish.

Default: "${::lsbdistcodename}-${name}"

This module has been tested against Puppet 3.8 with Ubuntu clients.

The spec tests work on Puppet 3.7+ and 4.x.

To work on Debian OS family servers, it requires the apt module from Puppetlabs to be installed if you want to have this module manage your aptly repository (optionnal).

The implementation for the installation on other operating systems has not been done yet but should be pretty straightforward to do. Just ask which one you want and we'll add it or submit a pull request on our github page and we'll integrate it.

We're actually nice people and we rarely bite, so you're more than welcome to contribute to our repos via the usual GitHub PR and issues.

What we ask generally is that when you push a change or a new functionnality, you add the corresponding tests at the same time. You'll find a lot of tests examples in this repository.

See the CONTRIBUTING.md file for more detailed guidelines.