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.

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.
Gary Larizza
1 parent 807e012150
Showing 1 changed file with 46 additions and 3 deletions Side-by-side Diff
README.md
@@ -64,7 +64,46 @@
 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 @@
 `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
...	...	@@ -64,7 +64,46 @@
64	64	provide as optional installs under the
65	65	[boxen organization](https://github.com/boxen). These modules are all
66	66	tested to be compatible with Boxen. Use the `Puppetfile` to pull them
67		-in dependencies automatically whenever `boxen` is run. You'll have to
	67	+in dependencies automatically whenever `boxen` is run.
	68	+
	69	+### Node Definitions ###
	70	+
	71	+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:
	72	+
	73	+ node default {
	74	+ # core modules, needed for most things
	75	+ include dnsmasq
	76	+ <...>
	77	+ }
	78	+
	79	+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.
	80	+
	81	+### Creating a personal module ###
	82	+
	83	+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:
	84	+
	85	+ # modules/people/manifests/sharpe.pp
	86	+ class people::sharpe {
	87	+ # Resource Declarations go here
	88	+ package { 'tree':
	89	+ ensure => installed,
	90	+ provider => homebrew,
	91	+ }
	92	+ }
	93	+
	94	+This class is installing the `tree` package out of
	95	+[Homebrew](https://github.com/mxcl/homebrew), but feel free to add whatever
	96	+resource declarations you'll need. Finally, add the following line in the
	97	+`manifests/site.pp` file within the default node definition:
	98	+
	99	+ include people::sharpe
	100	+
	101	+Finally, run `boxen --noop` to [simulate, or
	102	+test](http://docs.puppetlabs.com/guides/tests_smoke.html#running-tests) what
	103	+changes your code would have made. If you're happy with how things look, you
	104	+can then run `boxen` to enforce the changes you've made
	105	+
	106	+You'll have to
68	107	make sure your "node" (Puppet's term for your laptop, basically)
69	108	includes or requires them. You can do this by either modifying
70	109	`manifests/site.pp` for each module, _or_ we would generally recommend
71	110
...	...	@@ -73,9 +112,13 @@
73	112	`manifests/site.pp` by doing `include github::environment` or
74	113	what-have-you for your organization.
75	114
76		-For organization projects (read: repositories that people will be working in), please see the documentation in the projects module template we provide.
	115	+### Creating a project module ###
77	116
78		-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.
	117	+The `modules/projects` folder is provided for organizational projects that
	118	+aren't specific to one person. You're free to create any number of modules in
	119	+the `modules` directory. As long as you follow Puppet's module naming patterns,
	120	+everything should be fine. For more information, see the documentation in the
	121	+projects module template that we provide.
79	122
80	123	## Binary packages
81	124