From 97af892cc2f121839d89167919c1817177fe637a Mon Sep 17 00:00:00 2001 From: Gary Larizza Date: Tue, 9 Oct 2012 20:11:48 -0700 Subject: [PATCH] Update README Previously, documentation around creating modules and using site.pp was pretty slim. This commit adds more documentation and links to Puppet's documentation site. --- README.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7491ee5..6316c9a 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,46 @@ You can always check out the number of existing modules we already provide as optional installs under the [boxen organization](https://github.com/boxen). These modules are all tested to be compatible with Boxen. Use the `Puppetfile` to pull them -in dependencies automatically whenever `boxen` is run. You'll have to +in dependencies automatically whenever `boxen` is run. + +### Node Definitions ### + +Puppet has the concept of a ['node'](http://docs.puppetlabs.com/references/glossary.html#agent), which is essentially the machine on which Puppet is running. Puppet looks for [node definitions](http://docs.puppetlabs.com/learning/agent_master_basic.html#node-definitions) in the `manifests/site.pp` file in the Boxen repo. You'll see a default node declaration that looks like the following: + + node default { + # core modules, needed for most things + include dnsmasq + <...> + } + +All Puppet [class declarations](http://docs.puppetlabs.com/learning/modules1.html#classes) should be included in the default node definition. Theoretically, you _COULD_ declare every [Puppet resource](http://docs.puppetlabs.com/learning/ral.html) in the `manifests/site.pp` file, but that would quickly become unwieldy. Instead, it's easier to create [Puppet modules](http://docs.puppetlabs.com/learning/modules1.html#modules) inside the `modules` folder of the Boxen repo. Boxen is setup to discover any modules you create in the `modules` folder, and we've already created a `people` and `projects` module structure for you to start using. + +### Creating a personal module ### + +Using the `modules/people` folder that's been provided in the Boxen repo, start by creating a file in `modules/people/manifests` in the format of `your_last_name.pp` (Feel free to use the [Puppet module cheat sheet](http://docs.puppetlabs.com/module_cheat_sheet.pdf) if you need some extra help). If we were making a module for [Tim Sharpe](http://github.com/rodjek), we would create a file called `modules/people/manifests/sharpe.pp` that would look like the following: + + # modules/people/manifests/sharpe.pp + class people::sharpe { + # Resource Declarations go here + package { 'tree': + ensure => installed, + provider => homebrew, + } + } + +This class is installing the `tree` package out of +[Homebrew](https://github.com/mxcl/homebrew), but feel free to add whatever +resource declarations you'll need. Finally, add the following line in the +`manifests/site.pp` file within the default node definition: + + include people::sharpe + +Finally, run `boxen --noop` to [simulate, or +test](http://docs.puppetlabs.com/guides/tests_smoke.html#running-tests) what +changes your code would have made. If you're happy with how things look, you +can then run `boxen` to enforce the changes you've made + +You'll have to make sure your "node" (Puppet's term for your laptop, basically) includes or requires them. You can do this by either modifying `manifests/site.pp` for each module, _or_ we would generally recommend @@ -73,9 +112,13 @@ create an environment class in that. Then you need only adjust `manifests/site.pp` by doing `include github::environment` or what-have-you for your organization. -For organization projects (read: repositories that people will be working in), please see the documentation in the projects module template we provide. +### Creating a project module ### -For per-user configuration that doesn't need to be applied globally to everyone, please see the documentation in the people module template we provide. +The `modules/projects` folder is provided for organizational projects that +aren't specific to one person. You're free to create any number of modules in +the `modules` directory. As long as you follow Puppet's module naming patterns, +everything should be fine. For more information, see the documentation in the +projects module template that we provide. ## Binary packages -- 1.8.5.3