From 97af892cc2f121839d89167919c1817177fe637a Mon Sep 17 00:00:00 2001 From: Gary Larizza Date: Tue, 9 Oct 2012 20:11:48 -0700 Subject: [PATCH 1/3] 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 From a970e15714f9b33194b069876bd63c0796110ac6 Mon Sep 17 00:00:00 2001 From: Gary Larizza Date: Tue, 9 Oct 2012 20:42:22 -0700 Subject: [PATCH 2/3] Update README.md according to style Previously, the README.md file was updated but didn't match existing Github style. This commit wraps near 80 columns (markdown links make that a bit harder) and eliminate unnecessary steps (linking to existing documentation and removing redundant declarations). --- README.md | 69 ++++++++++++++++++++++--------------------------------- 1 file changed, 28 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 6316c9a..08d95a6 100644 --- a/README.md +++ b/README.md @@ -66,9 +66,14 @@ provide as optional installs under the tested to be compatible with Boxen. Use the `Puppetfile` to pull them in dependencies automatically whenever `boxen` is run. -### Node Definitions ### +### 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: +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 @@ -76,49 +81,31 @@ Puppet has the concept of a ['node'](http://docs.puppetlabs.com/references/gloss <...> } -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. +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 ### +### 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: +See [the documentation in the +`modules/people`](https://github.com/boxen/our-boxen/blob/master/modules/people/README.md) +directory for creating per-user modules that don't need to be applied +globally to everyone. - # modules/people/manifests/sharpe.pp - class people::sharpe { - # Resource Declarations go here - package { 'tree': - ensure => installed, - provider => homebrew, - } - } +### Creating a project module -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 -you create a module for your organization (eg. `modules/github`) and -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. - -### Creating a project module ### - -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. +See [the documentation in the +`modules/projects`](https://github.com/boxen/our-boxen/blob/master/modules/projects/README.md) +directory for creating organization projects (read: repositories that people +will be working in). ## Binary packages From 1bd7053c2d5b7fc8256e02dd9787f9beca1b616e Mon Sep 17 00:00:00 2001 From: Gary Larizza Date: Sat, 13 Oct 2012 12:05:01 -0700 Subject: [PATCH 3/3] 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