Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit a970e15714f9b33194b069876bd63c0796110ac6

Authored by Gary Larizza
1 parent 97af892cc2

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).

Showing 1 changed file with 32 additions and 45 deletions Inline Diff

# Our Boxen 1 1 # Our Boxen
2 2
This is a template Boxen project designed for your organization to fork and 3 3 This is a template Boxen project designed for your organization to fork and
modify appropriately. 4 4 modify appropriately.
The Boxen rubygem and the Boxen puppet modules are only a framework for getting 5 5 The Boxen rubygem and the Boxen puppet modules are only a framework for getting
things done. 6 6 things done.
This repository template is just a basic example of _how_ to do things with them. 7 7 This repository template is just a basic example of _how_ to do things with them.
8 8
## Getting Started 9 9 ## Getting Started
10 10
1. Install XCode Command Line Tools and/or full XCode. 11 11 1. Install XCode Command Line Tools and/or full XCode.
1. Create a new repository on GitHub as your user for your Boxen. (eg. 12 12 1. Create a new repository on GitHub as your user for your Boxen. (eg.
`wfarr/my-boxen`). **Make sure it is a private repository!** 13 13 `wfarr/my-boxen`). **Make sure it is a private repository!**
1. Get running like so: 14 14 1. Get running like so:
``` 15 15 ```
mkdir -p ~/src/my-boxen 16 16 mkdir -p ~/src/my-boxen
cd ~/src/my-boxen 17 17 cd ~/src/my-boxen
git init 18 18 git init
git remote add upstream https://github.com/boxen/our-boxen 19 19 git remote add upstream https://github.com/boxen/our-boxen
git fetch upstream 20 20 git fetch upstream
git co -b master upstream/master 21 21 git co -b master upstream/master
git remote add origin https://github.com/wfarr/my-boxen 22 22 git remote add origin https://github.com/wfarr/my-boxen
git push origin master 23 23 git push origin master
24 24
script/boxen 25 25 script/boxen
``` 26 26 ```
1. Close and reopen your Terminal. If you have a shell config file 27 27 1. Close and reopen your Terminal. If you have a shell config file
(eg. `~/.bashrc`) you'll need to add this at the very end: 28 28 (eg. `~/.bashrc`) you'll need to add this at the very end:
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload 29 29 `[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
your shell. 30 30 your shell.
1. Confirm the Boxen env has loaded: `boxen --env` 31 31 1. Confirm the Boxen env has loaded: `boxen --env`
32 32
Now you have your own my-boxen repo that you can hack on. 33 33 Now you have your own my-boxen repo that you can hack on.
You may have noticed we didn't ask you to fork the repo. 34 34 You may have noticed we didn't ask you to fork the repo.
This is because when our-boxen goes open source that'd have some 35 35 This is because when our-boxen goes open source that'd have some
implications about your fork also potentially being public. 36 36 implications about your fork also potentially being public.
That's obviously quite bad, so that's why we strongly suggest you 37 37 That's obviously quite bad, so that's why we strongly suggest you
create an entirely separate repo and simply pull the code in, as shown above. 38 38 create an entirely separate repo and simply pull the code in, as shown above.
39 39
## What You Get 40 40 ## What You Get
41 41
This template project provides the following by default: 42 42 This template project provides the following by default:
43 43
* Homebrew 44 44 * Homebrew
* Git 45 45 * Git
* Hub 46 46 * Hub
* DNSMasq w/ .dev resolver for localhost 47 47 * DNSMasq w/ .dev resolver for localhost
* NVM 48 48 * NVM
* RBenv 49 49 * RBenv
* Full Disk Encryption requirement 50 50 * Full Disk Encryption requirement
* NodeJS 0.4 51 51 * NodeJS 0.4
* NodeJS 0.6 52 52 * NodeJS 0.6
* NodeJS 0.8 53 53 * NodeJS 0.8
* Ruby 1.8.7 54 54 * Ruby 1.8.7
* Ruby 1.9.2 55 55 * Ruby 1.9.2
* Ruby 1.9.3 56 56 * Ruby 1.9.3
* Ack 57 57 * Ack
* Findutils 58 58 * Findutils
* GNU-Tar 59 59 * GNU-Tar
60 60
## Customizing 61 61 ## Customizing
62 62
You can always check out the number of existing modules we already 63 63 You can always check out the number of existing modules we already
provide as optional installs under the 64 64 provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all 65 65 [boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them 66 66 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run. 67 67 in dependencies automatically whenever `boxen` is run.
68 68
### Node Definitions ### 69 69 ### Node definitions
70 70
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: 71 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:
72 77
node default { 73 78 node default {
# core modules, needed for most things 74 79 # core modules, needed for most things
include dnsmasq 75 80 include dnsmasq
<...> 76 81 <...>
} 77 82 }
78 83
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. 79 84 All Puppet
85 [class declarations](http://docs.puppetlabs.com/learning/modules1.html#classes)
86 should be included in the default node definition. Theoretically, you _COULD_
87 declare every
88 [Puppet resource](http://docs.puppetlabs.com/learning/ral.html) in the
89 `manifests/site.pp` file, but that would quickly become unwieldy. Instead,
90 it's easier to create
91 [Puppet modules](http://docs.puppetlabs.com/learning/modules1.html#modules)
92 inside the `modules` folder of the Boxen repo. Boxen is setup to discover any
93 modules you create in the `modules` folder, and we've already created a
94 `people` and `projects` module structure for you to start using.
80 95
### Creating a personal module ### 81 96 ### Creating a personal module
82 97
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: 83 98 See [the documentation in the
99 `modules/people`](https://github.com/boxen/our-boxen/blob/master/modules/people/README.md)
100 directory for creating per-user modules that don't need to be applied
101 globally to everyone.
84 102
# modules/people/manifests/sharpe.pp 85 103 ### Creating a project module
class people::sharpe { 86
# Resource Declarations go here 87
package { 'tree': 88
ensure => installed, 89
provider => homebrew, 90
} 91
} 92
93 104
This class is installing the `tree` package out of 94 105 See [the documentation in the
[Homebrew](https://github.com/mxcl/homebrew), but feel free to add whatever 95 106 `modules/projects`](https://github.com/boxen/our-boxen/blob/master/modules/projects/README.md)
resource declarations you'll need. Finally, add the following line in the 96 107 directory for creating organization projects (read: repositories that people
`manifests/site.pp` file within the default node definition: 97 108 will be working in).
98
include people::sharpe 99
100
Finally, run `boxen --noop` to [simulate, or 101
test](http://docs.puppetlabs.com/guides/tests_smoke.html#running-tests) what 102
changes your code would have made. If you're happy with how things look, you 103
can then run `boxen` to enforce the changes you've made 104
105
You'll have to 106
make sure your "node" (Puppet's term for your laptop, basically) 107
includes or requires them. You can do this by either modifying 108
`manifests/site.pp` for each module, _or_ we would generally recommend 109
you create a module for your organization (eg. `modules/github`) and 110
create an environment class in that. Then you need only adjust 111