Jianwei Han / my-boxen

Commit 1c940a83519be777935d029b22ae6355d1527757

Authored by Will Farrington 2012-10-15 22:41:48 +0800

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

Update README

Showing 1 changed file Inline Diff

README.md

README.md

Diff comments View file @ 1c940a8

# 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. You'll have to	67	67	in dependencies automatically whenever `boxen` is run.
make sure your "node" (Puppet's term for your laptop, basically)	68
includes or requires them. You can do this by either modifying	69
`manifests/site.pp` for each module, _or_ we would generally recommend	70
you create a module for your organization (eg. `modules/github`) and	71
create an environment class in that. Then you need only adjust	72
`manifests/site.pp` by doing `include github::environment` or	73
what-have-you for your organization.	74
	75	68
For organization projects (read: repositories that people will be working in), please see the documentation in the projects module template we provide.	76	69	### Node definitions
	77	70
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.	78	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