Jianwei Han / my-boxen

Commit b9eac9217ad023309db1bb6d5d60ef567cd8fcc2

Authored by Kevin R. Barnes 2013-01-27 05:41:18 +0800

minor cleanup

Fix typos.
Clarify module includes in the Puppetfile.

Showing 1 changed file with 8 additions and 8 deletions Inline Diff

README.md

README.md

Diff comments View file @ b9eac92

# 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.
* If using full XCode, you'll need to agree to the license by running: `xcodebuild -license`	12	12	* If using full XCode, you'll need to agree to the license by running: `xcodebuild -license`
1. Create a new repository on GitHub as your user for your Boxen. (eg.	13	13	1. Create a new repository on GitHub as your user for your Boxen. (eg.
`wfarr/my-boxen`). Make sure it is a private repository!	14	14	`wfarr/my-boxen`). Make sure it is a private repository!
1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so:	15	15	1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so:
```	16	16	```
mkdir -p ~/src/my-boxen	17	17	mkdir -p ~/src/my-boxen
cd ~/src/my-boxen	18	18	cd ~/src/my-boxen
git init	19	19	git init
git remote add upstream https://github.com/boxen/our-boxen	20	20	git remote add upstream https://github.com/boxen/our-boxen
git fetch upstream	21	21	git fetch upstream
git checkout -b master upstream/master	22	22	git checkout -b master upstream/master
git remote add origin https://github.com/wfarr/my-boxen	23	23	git remote add origin https://github.com/wfarr/my-boxen
git push origin master	24	24	git push origin master
	25	25
script/boxen	26	26	script/boxen
```	27	27	```
1. Close and reopen your Terminal. If you have a shell config file	28	28	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:	29	29	(eg. `~/.bashrc`) you'll need to add this at the very end:
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload	30	30	`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
your shell.	31	31	your shell.
1. Confirm the Boxen env has loaded: `boxen --env`	32	32	1. Confirm the Boxen env has loaded: `boxen --env`
	33	33
Now you have your own my-boxen repo that you can hack on.	34	34	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.	35	35	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	36	36	This is because when our-boxen goes open source that'd have some
implications about your fork also potentially being public.	37	37	implications about your fork also potentially being public.
That's obviously quite bad, so that's why we strongly suggest you	38	38	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.	39	39	create an entirely separate repo and simply pull the code in, as shown above.
	40	40
## Getting your users started _after_ your "fork" exists	41	41	## Getting your users started _after_ your "fork" exists
	42	42
1. Install the XCode Command Line Tools (full XCode install optional).	43	43	1. Install the XCode Command Line Tools (full XCode install optional).
1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), OR have them run the following:	44	44	1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), OR have them run the following:
	45	45
```	46	46	```
sudo mkdir -p /opt/boxen	47	47	sudo mkdir -p /opt/boxen
sudo chown $USER:admin /opt/boxen	48	48	sudo chown $USER:admin /opt/boxen
git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo	49	49	git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
cd /opt/boxen/repo	50	50	cd /opt/boxen/repo
script/boxen	51	51	script/boxen
	52	52
# add boxen to your shell config, at the end, eg.	53	53	# add boxen to your shell config, at the end, eg.
echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'	54	54	echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
```	55	55	```
	56	56
Open a new terminal, `boxen --env` to confirm.	57	57	Open a new terminal, `boxen --env` to confirm.
	58	58
## What You Get	59	59	## What You Get
	60	60
This template project provides the following by default:	61	61	This template project provides the following by default:
	62	62
* Homebrew	63	63	* Homebrew
* Git	64	64	* Git
* Hub	65	65	* Hub
* DNSMasq w/ .dev resolver for localhost	66	66	* DNSMasq w/ .dev resolver for localhost
* NVM	67	67	* NVM
* RBenv	68	68	* RBenv
* Full Disk Encryption requirement	69	69	* Full Disk Encryption requirement
* NodeJS 0.4	70	70	* NodeJS 0.4
* NodeJS 0.6	71	71	* NodeJS 0.6
* NodeJS 0.8	72	72	* NodeJS 0.8
* Ruby 1.8.7	73	73	* Ruby 1.8.7
* Ruby 1.9.2	74	74	* Ruby 1.9.2
* Ruby 1.9.3	75	75	* Ruby 1.9.3
* Ack	76	76	* Ack
* Findutils	77	77	* Findutils
* GNU-Tar	78	78	* GNU-Tar
	79	79
## Customizing	80	80	## Customizing
	81	81
You can always check out the number of existing modules we already	82	82	You can always check out the number of existing modules we already
provide as optional installs under the	83	83	provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all	84	84	[boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them	85	85	tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run.	86	86	in dependencies automatically whenever `boxen` is run.
	87	87
### Node definitions	88	88	### Node definitions
	89	89
Puppet has the concept of a	90	90	Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent),	91	91	['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for	92	92	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)	93	93	[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	94	94	in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following:	95	95	declaration that looks like the following:
	96	96
``` puppet	97	97	``` puppet
node default {	98	98	node default {
# core modules, needed for most things	99	99	# core modules, needed for most things
include dnsmasq	100	100	include dnsmasq
	101	101
# more...	102	102	# more...
}	103	103	}
```	104	104	```
	105	105
### How Boxen interacts with Puppet	106	106	### How Boxen interacts with Puppet
	107	107
Boxen runs everything declared in `manifests/site.pp` by default.	108	108	Boxen runs everything declared in `manifests/site.pp` by default.
But just like any other source code, throwing all your work into one massive	109	109	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	110	110	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	111	111	use modules in the `Puppetfile` when you can and make new modules
in the `modules/` directory when you can't. Then you just need to	112	112	in the `modules/` directory when you can't. Then add `include $modulename`
`include $modulename` those modules in `manifests/site.pp`. One pattern	113	113	for each new module in `manifests/site.pp` to include them.
that's very common is to create a module for your organization	114	114	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	115	115	(e.g., `modules/github`) and put an environment class in that module
to include all of the modules your organization wants to install for	116	116	to include all of the modules your organization wants to install for
everyone by default. An example of this might look like so:	117	117	everyone by default. An example of this might look like so:
	118	118
``` puppet	119	119	``` puppet
# modules/github/manifests/environment.pp	120	120	# modules/github/manifests/environment.pp
	121	121
class github::environment {	122	122	class github::environment {
include github::apps::mac	123	123	include github::apps::mac
	124	124
include ruby::1-8-7	125	125	include ruby::1-8-7
	126	126
include projects::super-top-secret-project	127	127	include projects::super-top-secret-project
}	128	128	}
```	129	129	```
	130	130
If you'd like to read more about how Puppet works, we recommend	131	131	If you'd like to read more about how Puppet works, we recommend
checking out [the official documentation](http://docs.puppetlabs.com/)	132	132	checking out [the official documentation](http://docs.puppetlabs.com/)