Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 1c940a83519be777935d029b22ae6355d1527757

Authored by Will Farrington
2 parents 6e1bd53216 1bd7053c2d

Merge pull request #12 from glarizza/feature/master/documentation_update 

Update README

Showing 1 changed file Side-by-side Diff

... ... @@ -64,18 +64,68 @@
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
68   -make sure your "node" (Puppet's term for your laptop, basically)
69   -includes or requires them. You can do this by either modifying
70   -`manifests/site.pp` for each module, _or_ we would generally recommend
71   -you create a module for your organization (eg. `modules/github`) and
72   -create an environment class in that. Then you need only adjust
73   -`manifests/site.pp` by doing `include github::environment` or
74   -what-have-you for your organization.
  67 +in dependencies automatically whenever `boxen` is run.
75 68  
76   -For organization projects (read: repositories that people will be working in), please see the documentation in the projects module template we provide.
  69 +### Node definitions
77 70  
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.
  71 +Puppet has the concept of a
  72 +['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
  73 +which is essentially the machine on which Puppet is running. Puppet looks for
  74 +[node definitions](http://docs.puppetlabs.com/learning/agent_master_basic.html#node-definitions)
  75 +in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
  76 +declaration that looks like the following:
  77 +
  78 + node default {
  79 + # core modules, needed for most things
  80 + include dnsmasq
  81 + <...>
  82 + }
  83 +
  84 +### How Boxen interacts with Puppet
  85 +
  86 +Boxen runs everything declared in `manifests/site.pp` by default.
  87 +But just like any other source code, throwing all your work into one massive
  88 +file is going to be difficult to work with. Instead, we recommend you
  89 +use modules via the `Puppetfile` when you can and making new modules
  90 +in the `modules/` directory when you can't. Then you just need to
  91 +`include $modulename` those modules in `manifests/site.pp`. One pattern
  92 +that's very common is to create a module for your organization
  93 +(eg. `modules/github`) and put an environment class in that module
  94 +to include all of the modules your organization wants to install for
  95 +everyone by default. An example of this might look like so:
  96 +
  97 +```
  98 + class github::environment {
  99 + include github::apps::mac
  100 +
  101 + include ruby::1-8-7
  102 +
  103 + include projects::super-top-secret-project
  104 + }
  105 + ```
  106 +
  107 + If you'd like to read more about how Puppet works, we recommend
  108 + checking out [the official documentation](http://docs.puppetlabs.com/)
  109 + for:
  110 +
  111 + * [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules)
  112 + * [Classes](http://docs.puppetlabs.com/learning/modules1.html#classes)
  113 + * [Defined Types](http://docs.puppetlabs.com/learning/definedtypes.html)
  114 + * [Facts](http://docs.puppetlabs.com/guides/custom_facts.html)
  115 +
  116 +### Creating a personal module
  117 +
  118 +See [the documentation in the
  119 +`modules/people`](https://github.com/boxen/our-boxen/blob/master/modules/people/README.md)
  120 +directory for creating per-user modules that don't need to be applied
  121 +globally to everyone.
  122 +
  123 +### Creating a project module
  124 +
  125 +See [the documentation in the
  126 +`modules/projects`](https://github.com/boxen/our-boxen/blob/master/modules/projects/README.md)
  127 +directory for creating organization projects (read: repositories that people
  128 +will be working in).
79 129  
80 130 ## Binary packages
81 131