Puppet Library

A private Puppet Forge. Compatible with librarian-puppet.

Puppet Library serves Puppet modules in the same format as the Puppet Forge. This allows you to create a private Puppet Forge and manage all the modules you use completely within your infrastructure.

Plugins can be created to serve modules from arbitrary sources. Puppet Library contains built-in support for:

• serving packaged (.tar.gz) modules from a directory (or directories) of your choosing
• proxying a remote forge (or forges)
• caching proxied forges to disk
• serving modules from source on disk
• serving modules from Git repositories using tags as version numbers!

Demo

Puppet Library has a web UI to browse the modules. A demo is available here.

Installation

Install the server as a Gem:

$ gem install puppet-library

Or, to get the latest, you can install from source

$ git clone https://github.com/drrb/puppet-library.git
$ cd puppet-library
$ rake install

Getting Started

Create a module directory and add the modules to it

$ mkdir modules
$ wget -P modules/ forge.puppetlabs.com/system/releases/p/puppetlabs/puppetlabs-apache-0.9.0.tar.gz
$ wget -P modules/ forge.puppetlabs.com/system/releases/p/puppetlabs/puppetlabs-concat-1.0.0.tar.gz
$ wget -P modules/ forge.puppetlabs.com/system/releases/p/puppetlabs/puppetlabs-stdlib-2.4.0.tar.gz

Start the server

$ puppet-library --port 9292 --module-dir ./modules

Point librarian-puppet to the server

$ cat > Puppetfile <<EOF
forge 'http://localhost:9292'

mod 'puppetlabs/apache', '0.9.0'
EOF

Resolve and download the modules

$ librarian-puppet install

Usage

Run the server (proxies the Puppet Forge by default)

$ puppet-library

Serve modules from a specific directory

$ puppet-library --module-dir /var/puppet-modules

Serve modules from a remote forge as a proxy

$ puppet-library --proxy http://forge.puppetlabs.com

Proxy a remote forge, caching downloaded modules on disk

$ puppet-library --proxy http://forge.puppetlabs.com --cache-basedir

Serve a module from source

$ puppet-library --source-dir ~/code/puppetlabs-apache

Serve modules on a specific port

$ puppet-library --port 8888

See all options

$ puppet-library --help

Back-Ends

Puppet Library contains built-in support for:

• serving packaged (.tar.gz) modules from a directory (or directories) of your choosing
• proxying a remote forge (or forges)
• serving modules from source on disk
• serving modules from Git repositories using tags as version numbers!
• serving modules from a combination of the above

Compatibility with other tools

Dependency Resolution/Installation

Puppet Library currently supports:

• search with Puppet (puppet module search apache)
• dependency resolution and installation with Puppet (puppet module install puppetlabs/apache)
• dependency resolution and installation with librarian-puppet
• installation with r10k

Ruby

Puppet Library is tested against Ruby versions:

• 1.8.7
• 1.9.3
• 2.0.0
• 2.1.0

Puppet

Puppet Library implements version 1 of the Forge API, and supports reading module metadata from modules' Modulefiles. This means that Puppet Library can currently only work with Puppet < 3.6, which uses the new Forge API (v3) and has switched to using metadata.json instead of Modulefile. Progress can be tracked here.

Config file (EXPERIMENTAL)

Instead of specifying command-line options, you can configure Puppet Library with a configuration file. To use a configuration file, point to it on the command line:

puppet-library --config-file my-puppet-library-config.yml

A configuration file looks like this:

port: 4567
hostname: example.com
server: thin
daemonize: true
pidfile: /var/run/puppetlibrary.pid
forges:
    - Directory: /var/lib/modules
    - Directory: /var/lib/other-modules
    - Source: /var/code/puppetlabs-apache
    - Proxy: http://forge.puppetlabs.com

Running with Phusion Passenger (EXPERIMENTAL)

To run Puppet Library with Phusion Passenger:

# Install Puppet Library
sudo gem install puppet-library

# Create a Passenger-compatible directory structure
mkdir -p /webapps/puppet-library/{public,tmp}

# Create a Rack config file to point Puppet Library to your modules
cat > /webapps/puppet-library/config.ru <<EOF
require "rubygems"
require "puppet_library"

# NB: this config API is not yet stable, and may change without notice.
# The format shown is valid from Puppet Library v0.11.0. See below for
# all valid config items
server = PuppetLibrary::Server.configure do
    # Proxy the Puppet Forge
    forge :proxy do
        url "http://forge.puppetlabs.com"
    end
end

run server
EOF

# Create an Apache virtual host pointing at Puppet Library
cat > /etc/httpd/conf.d/puppetlibrary.conf <<EOF
<VirtualHost *:80>
    ServerName privateforge.example.com
    DocumentRoot /webapps/puppet-library/public
    <Directory /webapps/puppet-library/public>
        Allow from all
        Options -MultiViews
    </Directory>
</VirtualHost>
EOF

The following config items will currently work with the Rack config format (see above):

# NB: this config API is not yet stable, and may change without notice.
# The format shown is valid from Puppet Library v0.11.0
server = PuppetLibrary::Server.configure do
    # Serve modules from a directory on disk
    forge :directory do
        path "/var/lib/modules"
    end

    # Serve module versions from a Git repository
    forge :git_repository do
        source "http://github.com/example/puppetlabs-apache-fork.git"
        include_tags /[0-9.]+/
    end

    # Proxy a remote forge
    forge :proxy do
        url "http://forge.example.com"
    end

    # Proxy a remote forge, caching modules to disk
    forge :cache do
        url "http://forge.puppetlabs.com"
        path "/var/puppet/modules/cache"
    end
end

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Make your changes, and add tests for them
4. Test your changes (rake)
5. Commit your changes (git commit -am 'Add some feature')
6. Push to the branch (git push origin my-new-feature)
7. Create new Pull Request

Acknowledgements

This project was inspired by dalen/simple-puppet-forge.

License

Puppet Library Copyright (C) 2014 drrb

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.