README.md 6.34 KB
Newer Older
1 2 3 4
# Librarian-puppet

## Introduction

Tim Sharpe's avatar
Tim Sharpe committed
5 6 7 8 9 10 11 12 13
Librarian-puppet is a bundler for your puppet infrastructure.  You can use
librarian-puppet to manage the puppet modules your infrastructure depends on.
It is based on [Librarian](https://github.com/applicationsonline/librarian), a
framework for writing bundlers, which are tools that resolve, fetch, install,
and isolate a project's dependencies.

Librarian-puppet manages your `modules/` directory for you based on your
`Puppetfile`.  Your `Puppetfile` becomes the authoritative source for what
modules you require and at what version, tag or branch.
14

Tim Sharpe's avatar
Tim Sharpe committed
15 16 17
Once using Librarian-puppet you should not modify the contents of your `modules`
directory.  The individual modules' repos should be updated, tagged with a new
release and the version bumped in your Puppetfile.
18 19 20

## The Puppetfile

Tim Sharpe's avatar
Tim Sharpe committed
21 22 23
Every Puppet repository that uses Librarian-puppet will have a file named
`Puppetfile` in the root directory of that repository.  The full specification
for which modules your puppet infrastructure repository  depends goes in here.
24 25 26

### Example Puppetfile

Tim Sharpe's avatar
Tim Sharpe committed
27 28 29 30 31
    forge "http://forge.puppetlabs.com"

    mod "puppetlabs/razor"
    mod "puppetlabs/ntp", "0.0.3"

32 33 34 35 36 37
    mod "apt",
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git"

    mod "stdlib",
      :git => "git://github.com/puppetlabs/puppetlabs-stdlib.git"

Tim Sharpe's avatar
Tim Sharpe committed
38 39
*See [jenkins-appliance](https://github.com/aussielunix/jenkins-appliance) for
a puppet repo already setup to use librarian-puppet.*
40 41 42

### Puppetfile Breakdown

Tim Sharpe's avatar
Tim Sharpe committed
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
    forge "http://forge.puppetlabs.com"

This declares that we want to use the official Puppet Labs Forge as our default
source when pulling down modules.  If you run your own local forge, you may
want to change this.

    mod "puppetlabs/razor"

Pull in the latest version of the Puppet Labs Razor module from the default
source.

    mod "puppetlabs/ntp", "0.0.3"

Pull in version 0.0.3 of the Puppet Labs NTP module from the default source.

58 59 60
    mod "apt",
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git"

Tim Sharpe's avatar
Tim Sharpe committed
61 62
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out the `master` branch.
63 64

    mod "apt",
65
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git",
66 67
      :ref => '0.0.3'

Tim Sharpe's avatar
Tim Sharpe committed
68 69
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out a tag of `0.0.3`.
70 71

    mod "apt",
72
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git",
73 74
      :ref => 'feature/master/dans_refactor'

Tim Sharpe's avatar
Tim Sharpe committed
75 76
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out the `dans_refactor` branch.
77

Tim Sharpe's avatar
Tim Sharpe committed
78 79
When using a Git source, we do not have to use a `:ref =>`.
If we do not, then librarian-puppet will assume we meant the `master` branch.
80

Tim Sharpe's avatar
Tim Sharpe committed
81 82
If we use a `:ref =>`, we can use anything that Git will recognize as a ref.
This includes any branch name, tag name, SHA, or SHA unique prefix. If we use a
Joshua Johnson's avatar
Joshua Johnson committed
83
branch, we can later ask Librarian-puppet to update the module by fetching the
Tim Sharpe's avatar
Tim Sharpe committed
84
most recent version of the module from that same branch.
85

Tim Sharpe's avatar
Tim Sharpe committed
86 87 88 89 90 91
The Git source also supports a `:path =>` option. If we use the path option,
Librarian-puppet will navigate down into the Git repository and only use the
specified subdirectory. Some people have the habit of having a single repository
with many modules in it. If we need a module from such a repository, we can
use the `:path =>` option here to help Librarian-puppet drill down and find the
module subdirectory.
92 93

    mod "apt",
94
      :git => "git://github.com/fake/puppet-modules.git",
95 96
      :path => "modules/apt"

Tim Sharpe's avatar
Tim Sharpe committed
97 98
Our puppet infrastructure repository depends on the `apt` module, which we have
stored as a directory under our `puppet-modules` git repos.
99 100 101

## How to Use

Tim Sharpe's avatar
Tim Sharpe committed
102
Install librarian-puppet:
103

Tom De Vylder's avatar
Tom De Vylder committed
104
    $ gem install librarian-puppet
105 106 107 108 109

Prepare your puppet infrastructure repository:

    $ cd ~/path/to/puppet-inf-repos
    $ (git) rm -rf modules
Tim Sharpe's avatar
Tim Sharpe committed
110
    $ librarian-puppet init
111

Tim Sharpe's avatar
Tim Sharpe committed
112 113 114 115
Librarian-puppet takes over your `modules/` directory, and will always
reinstall (if missing) the modules listed the `Puppetfile.lock` into your
`modules/` directory, therefore you do not need your `modules/` directory to be
tracked in Git.
116

Tim Sharpe's avatar
Tim Sharpe committed
117 118
Librarian-puppet uses a `.tmp/` directory for tempfiles and caches. You should
not track this directory in Git.
119

Tim Sharpe's avatar
Tim Sharpe committed
120 121
Running `librarian-puppet init` will create a skeleton Puppetfile for you as
well as adding `tmp/` and `modules/` to your `.gitignore`.
122 123 124

    $ librarian-puppet install [--clean] [--verbose]

Tim Sharpe's avatar
Tim Sharpe committed
125 126 127 128
This command looks at each `mod` declaration and fetches the module from the
source specified.  This command writes the complete resolution into
`Puppetfile.lock` and then copies all of the fetched modules into your
`modules/` directory, overwriting whatever was there before.
129

Tim Sharpe's avatar
Tim Sharpe committed
130
Get an overview of your `Puppetfile.lock` with:
131 132 133

    $ librarian-puppet show

Tim Sharpe's avatar
Tim Sharpe committed
134
Inspect the details of specific resolved dependencies with:
135 136 137

    $ librarian-puppet show NAME1 [NAME2, ...]

Tim Sharpe's avatar
Tim Sharpe committed
138
Find out which dependencies are outdated and may be updated:
139 140 141

    $ librarian-puppet outdated [--verbose]

Tim Sharpe's avatar
Tim Sharpe committed
142
Update the version of a dependency:
143 144 145 146 147 148 149 150

    $ librarian-puppet update apt [--verbose]
    $ git diff Puppetfile.lock
    $ git add Puppetfile.lock
    $ git commit -m "bumped the version of apt up to 0.0.4."

## How to Contribute

Tim Sharpe's avatar
Tim Sharpe committed
151 152
 * Pull requests please.
 * Bonus points for feature branches.
153 154 155

## Reporting Issues

Tim Sharpe's avatar
Tim Sharpe committed
156 157
Bug reports to the github issue tracker please.
Please include:
158

Joshua Johnson's avatar
Joshua Johnson committed
159 160
 * Relevant `Puppetfile` and `Puppetfile.lock` files
 * Version of ruby, librarian-puppet
Tim Sharpe's avatar
Tim Sharpe committed
161 162 163
 * What distro
 * Please run the `librarian-puppet` commands in verbose mode by using the
  `--verbose` flag, and include the verbose output in the bug report as well.
164

Tim Sharpe's avatar
Tim Sharpe committed
165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184
## Changelog

### 0.9.0

 * Initial release

### 0.9.1

 * Proper error message when a module that is sourced from the forge does not
   exist.
 * Added support for annotated tags as git references.
 * `librarian-puppet init` adds `.tmp/` to gitignore instead of `tmp/`.
 * Fixed syntax error in the template Puppetfile created by `librarian-puppet
   init`.
 * Checks for `lib/puppet` as well as `manifests/` when checking if the git
   repository is a valid module.
 * When a user specifies `<foo>/<bar>` as the name of a module sources from a
   git repository, assume the module name is actually `<bar>`.
 * Fixed gem description and summary in gemspec.

185
## License
Tim Sharpe's avatar
Tim Sharpe committed
186 187
Please see the [LICENSE](https://github.com/rodjek/librarian-puppet/blob/master/LICENSE)
file.