Jianwei Han / my-boxen

Commit 1bd7053c2d5b7fc8256e02dd9787f9beca1b616e

Authored by Gary Larizza 2012-10-14 03:05:01 +0800

Update README.md for @wfarr's changes

Based on the feedback in the Pull request <https://github.com/boxen/our-boxen/pull/12>,
this commit implements changes to clarify how someone would customize
their Boxen setup.

Showing 1 changed file with 31 additions and 11 deletions Inline Diff

README.md

README.md

Diff comments View file @ 1bd7053

# 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	71	71	Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent),	72	72	['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for	73	73	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)	74	74	[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	75	75	in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following:	76	76	declaration that looks like the following:
	77	77
node default {	78	78	node default {
# core modules, needed for most things	79	79	# core modules, needed for most things
include dnsmasq	80	80	include dnsmasq
<...>	81	81	<...>
}	82	82	}
	83	83
All Puppet	84	84	### How Boxen interacts with Puppet
[class declarations](http://docs.puppetlabs.com/learning/modules1.html#classes)	85	85
should be included in the default node definition. Theoretically, you _COULD_	86	86	Boxen runs everything declared in `manifests/site.pp` by default.
declare every	87	87	But just like any other source code, throwing all your work into one massive
[Puppet resource](http://docs.puppetlabs.com/learning/ral.html) in the	88	88	file is going to be difficult to work with. Instead, we recommend you
`manifests/site.pp` file, but that would quickly become unwieldy. Instead,	89	89	use modules via the `Puppetfile` when you can and making new modules
it's easier to create	90	90	in the `modules/` directory when you can't. Then you just need to
[Puppet modules](http://docs.puppetlabs.com/learning/modules1.html#modules)	91	91	`include $modulename` those modules in `manifests/site.pp`. One pattern
inside the `modules` folder of the Boxen repo. Boxen is setup to discover any	92	92	that's very common is to create a module for your organization
modules you create in the `modules` folder, and we've already created a	93	93	(eg. `modules/github`) and put an environment class in that module
`people` and `projects` module structure for you to start using.	94	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)
	95	115
### Creating a personal module	96	116	### Creating a personal module
	97	117
See [the documentation in the	98	118	See [the documentation in the
`modules/people`](https://github.com/boxen/our-boxen/blob/master/modules/people/README.md)	99	119	`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	100	120	directory for creating per-user modules that don't need to be applied
globally to everyone.	101	121	globally to everyone.
	102	122
### Creating a project module	103	123	### Creating a project module
	104	124