From 1bd7053c2d5b7fc8256e02dd9787f9beca1b616e Mon Sep 17 00:00:00 2001 From: Gary Larizza Date: Sat, 13 Oct 2012 12:05:01 -0700 Subject: [PATCH] Update README.md for @wfarr's changes Based on the feedback in the Pull request , this commit implements changes to clarify how someone would customize their Boxen setup. --- README.md | 42 +++++++++++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 08d95a6..62f92a0 100644 --- a/README.md +++ b/README.md @@ -81,17 +81,37 @@ declaration that looks like the following: <...> } -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. +### How Boxen interacts with Puppet + +Boxen runs everything declared in `manifests/site.pp` by default. +But just like any other source code, throwing all your work into one massive +file is going to be difficult to work with. Instead, we recommend you +use modules via the `Puppetfile` when you can and making new modules +in the `modules/` directory when you can't. Then you just need to +`include $modulename` those modules in `manifests/site.pp`. One pattern +that's very common is to create a module for your organization +(eg. `modules/github`) and put an environment class in that module +to include all of the modules your organization wants to install for +everyone by default. An example of this might look like so: + +``` + class github::environment { + include github::apps::mac + + include ruby::1-8-7 + + include projects::super-top-secret-project + } + ``` + + If you'd like to read more about how Puppet works, we recommend + checking out [the official documentation](http://docs.puppetlabs.com/) + for: + + * [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules) + * [Classes](http://docs.puppetlabs.com/learning/modules1.html#classes) + * [Defined Types](http://docs.puppetlabs.com/learning/definedtypes.html) + * [Facts](http://docs.puppetlabs.com/guides/custom_facts.html) ### Creating a personal module -- 1.8.5.3