Jianwei Han / my-boxen

Commit 7f9e2dbebcc25386ca9aa90277d4c75cfd989e29

Authored by Matt Bridges 2013-04-16 01:15:46 +0800

No hard drive encryption

Some users may not want to encrypt their hard drive, so make
sure they know the option exists to not have to encrypt their
hard drive.

Showing 1 changed file with 7 additions and 0 deletions Inline Diff

README.md

README.md

Diff comments View file @ 7f9e2db

# 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
To give you a brief overview, we're going to:	11	11	To give you a brief overview, we're going to:
	12	12
* Install dependencies (basically Xcode)	13	13	* Install dependencies (basically Xcode)
* Bootstrap a boxen for your self/team/org/company	14	14	* Bootstrap a boxen for your self/team/org/company
* Then convert your local copy of that boxen to the post-bootstrapped version	15	15	* Then convert your local copy of that boxen to the post-bootstrapped version
	16	16
There are a few potential conflicts to keep in mind.	17	17	There are a few potential conflicts to keep in mind.
Boxen does its best not to get in the way of a dirty system,	18	18	Boxen does its best not to get in the way of a dirty system,
but you should check into the following before attempting to install your	19	19	but you should check into the following before attempting to install your
boxen on any machine (we do some checks before every Boxen run to try	20	20	boxen on any machine (we do some checks before every Boxen run to try
and detect most of these and tell you anyway):	21	21	and detect most of these and tell you anyway):
	22	22
* Boxen __requires__ at least the Xcode Command Line Tools installed.	23	23	* Boxen __requires__ at least the Xcode Command Line Tools installed.
* Boxen __will not__ work with an existing rvm install.	24	24	* Boxen __will not__ work with an existing rvm install.
* Boxen __may not__ play nice with a GitHub username that includes dash(-)	25	25	* Boxen __may not__ play nice with a GitHub username that includes dash(-)
* Boxen __may not__ play nice with an existing rbenv install.	26	26	* Boxen __may not__ play nice with an existing rbenv install.
* Boxen __may not__ play nice with an existing chruby install.	27	27	* Boxen __may not__ play nice with an existing chruby install.
* Boxen __may not__ play nice with an existing homebrew install.	28	28	* Boxen __may not__ play nice with an existing homebrew install.
* Boxen __may not__ play nice with an existing nvm install.	29	29	* Boxen __may not__ play nice with an existing nvm install.
* Boxen __recommends__ installing the full Xcode.	30	30	* Boxen __recommends__ installing the full Xcode.
	31	31
### Dependencies	32	32	### Dependencies
	33	33
Install the Xcode Command Lines Tools and/or full Xcode.	34	34	Install the Xcode Command Lines Tools and/or full Xcode.
This will grant you the most predictable behavior in building apps like	35	35	This will grant you the most predictable behavior in building apps like
MacVim.	36	36	MacVim.
	37	37
How do you do it?	38	38	How do you do it?
	39	39
1. Install Xcode from the Mac App Store.	40	40	1. Install Xcode from the Mac App Store.
1. Open Xcode.	41	41	1. Open Xcode.
1. Open the Preferences window (`Cmd-,`).	42	42	1. Open the Preferences window (`Cmd-,`).
1. Go to the Downloads tab.	43	43	1. Go to the Downloads tab.
1. Install the Command Line Tools.	44	44	1. Install the Command Line Tools.
	45	45
### Bootstrapping	46	46	### Bootstrapping
	47	47
Create a new git repository somewhere.	48	48	Create a new git repository somewhere.
It can be private or public -- it really doesn't matter.	49	49	It can be private or public -- it really doesn't matter.
If you're making a repository on GitHub, you _may not_ want to fork this repo	50	50	If you're making a repository on GitHub, you _may not_ want to fork this repo
to get started.	51	51	to get started.
The reason for that is that you can't really make private forks of public	52	52	The reason for that is that you can't really make private forks of public
repositories easily.	53	53	repositories easily.
	54	54
Once you've done that, you can run the following to get bootstrap	55	55	Once you've done that, you can run the following to get bootstrap
your boxen:	56	56	your boxen:
	57	57
```	58	58	```
sudo mkdir -p /opt/boxen	59	59	sudo mkdir -p /opt/boxen
sudo chown ${USER}:admin /opt/boxen	60	60	sudo chown ${USER}:admin /opt/boxen
git clone https://github.com/boxen/our-boxen /opt/boxen/repo	61	61	git clone https://github.com/boxen/our-boxen /opt/boxen/repo
cd /opt/boxen/repo	62	62	cd /opt/boxen/repo
git remote rm origin	63	63	git remote rm origin
git remote add origin <the location of my new git repository>	64	64	git remote add origin <the location of my new git repository>
git push -u origin master	65	65	git push -u origin master
```	66	66	```
	67	67
### Distributing	68	68	### Distributing
	69	69
That's enough to get your boxen into a usable state on other machines,	70	70	That's enough to get your boxen into a usable state on other machines,
usually.	71	71	usually.
From there, we recommend setting up	72	72	From there, we recommend setting up
[boxen-web](https://github.com/boxen/boxen-web)	73	73	[boxen-web](https://github.com/boxen/boxen-web)
as an easy way to automate letting other folks install your boxen.	74	74	as an easy way to automate letting other folks install your boxen.
	75	75
If you _don't_ want to use boxen-web, folks can get using your boxen like so:	76	76	If you _don't_ want to use boxen-web, folks can get using your boxen like so:
	77	77
```	78	78	```
sudo mkdir -p /opt/boxen	79	79	sudo mkdir -p /opt/boxen
sudo chown ${USER}:admin /opt/boxen	80	80	sudo chown ${USER}:admin /opt/boxen
git clone <location of my new git repository> /opt/boxen/repo	81	81	git clone <location of my new git repository> /opt/boxen/repo
cd /opt/boxen/repo	82	82	cd /opt/boxen/repo
script/boxen	83	83	script/boxen
```	84	84	```
	85	85
		86	Keep in mind this requires you to encrypt your hard drive by default.
		87	If you do not want to do encrypt your hard drive, you can use the `--no-fde`.
		88
		89	```
		90	script/boxen --no-fde
		91	```
		92
It should run successfully, and should tell you to source a shell script	86	93	It should run successfully, and should tell you to source a shell script
in your environment.	87	94	in your environment.
For users without a bash or zsh config or a `~/.profile` file,	88	95	For users without a bash or zsh config or a `~/.profile` file,
Boxen will create a shim for you that will work correctly.	89	96	Boxen will create a shim for you that will work correctly.
If you do have a `~/.bashrc` or `~/.zshrc`, your shell will not use	90	97	If you do have a `~/.bashrc` or `~/.zshrc`, your shell will not use
`~/.profile` so you'll need to add a line like so at _the end of your config_:	91	98	`~/.profile` so you'll need to add a line like so at _the end of your config_:
	92	99
``` sh	93	100	``` sh
[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh	94	101	[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
```	95	102	```
	96	103
Once your shell is ready, open a new tab/window in your Terminal	97	104	Once your shell is ready, open a new tab/window in your Terminal
and you should be able to successfully run `boxen --env`.	98	105	and you should be able to successfully run `boxen --env`.
If that runs cleanly, you're in good shape.	99	106	If that runs cleanly, you're in good shape.
	100	107
## What You Get	101	108	## What You Get
	102	109
This template project provides the following by default:	103	110	This template project provides the following by default:
	104	111
* Homebrew	105	112	* Homebrew
* Git	106	113	* Git
* Hub	107	114	* Hub
* DNSMasq w/ .dev resolver for localhost	108	115	* DNSMasq w/ .dev resolver for localhost
* NVM	109	116	* NVM
* RBenv	110	117	* RBenv
* Full Disk Encryption requirement	111	118	* Full Disk Encryption requirement
* NodeJS 0.4	112	119	* NodeJS 0.4
* NodeJS 0.6	113	120	* NodeJS 0.6
* NodeJS 0.8	114	121	* NodeJS 0.8
* Ruby 1.8.7	115	122	* Ruby 1.8.7
* Ruby 1.9.2	116	123	* Ruby 1.9.2
* Ruby 1.9.3	117	124	* Ruby 1.9.3
* Ack	118	125	* Ack
* Findutils	119	126	* Findutils
* GNU-Tar	120	127	* GNU-Tar
	121	128
## Customizing	122	129	## Customizing
	123	130
You can always check out the number of existing modules we already	124	131	You can always check out the number of existing modules we already
provide as optional installs under the	125	132	provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all	126	133	[boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them	127	134	tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run.	128	135	in dependencies automatically whenever `boxen` is run.
	129	136
### Including boxen modules from github (boxen/puppet-<name>)	130	137	### Including boxen modules from github (boxen/puppet-<name>)
	131	138
You must add the github information for your added Puppet module into your Puppetfile at the root of your	132	139	You must add the github information for your added Puppet module into your Puppetfile at the root of your
boxen repo (ex. /path/to/your-boxen/Puppetfile):	133	140	boxen repo (ex. /path/to/your-boxen/Puppetfile):
	134	141
# Core modules for a basic development environment. You can replace	135	142	# Core modules for a basic development environment. You can replace
# some/most of these if you want, but it's not recommended.	136	143	# some/most of these if you want, but it's not recommended.
	137	144
github "dnsmasq", "1.0.0"	138	145	github "dnsmasq", "1.0.0"
github "gcc", "1.0.0"	139	146	github "gcc", "1.0.0"
github "git", "1.0.0"	140	147	github "git", "1.0.0"
github "homebrew", "1.0.0"	141	148	github "homebrew", "1.0.0"
github "hub", "1.0.0"	142	149	github "hub", "1.0.0"
github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"	143	150	github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
github "nginx", "1.0.0"	144	151	github "nginx", "1.0.0"
github "nodejs", "1.0.0"	145	152	github "nodejs", "1.0.0"
github "nvm", "1.0.0"	146	153	github "nvm", "1.0.0"
github "ruby", "1.0.0"	147	154	github "ruby", "1.0.0"
github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"	148	155	github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
github "sudo", "1.0.0"	149	156	github "sudo", "1.0.0"
	150	157
# Optional/custom modules. There are tons available at	151	158	# Optional/custom modules. There are tons available at
# https://github.com/boxen.	152	159	# https://github.com/boxen.
	153	160
github "java", "1.0.5"	154	161	github "java", "1.0.5"
	155	162
In the above snippet of a customized Puppetfile, the bottom line	156	163	In the above snippet of a customized Puppetfile, the bottom line
includes the Java module from Github using the tag "1.0.5" from the github repository	157	164	includes the Java module from Github using the tag "1.0.5" from the github repository
"boxen/puppet-java". The function "github" is defined at the top of the Puppetfile	158	165	"boxen/puppet-java". The function "github" is defined at the top of the Puppetfile
and takes the name of the module, the version, and optional repo location:	159	166	and takes the name of the module, the version, and optional repo location:
	160	167
def github(name, version, options = nil)	161	168	def github(name, version, options = nil)
options \|\|= {}	162	169	options \|\|= {}
options[:repo] \|\|= "boxen/puppet-#{name}"	163	170	options[:repo] \|\|= "boxen/puppet-#{name}"
mod name, version, :github_tarball => options[:repo]	164	171	mod name, version, :github_tarball => options[:repo]
end	165	172	end
	166	173
Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:	167	174	Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
	168	175
# include the java module referenced in my Puppetfile with the line	169	176	# include the java module referenced in my Puppetfile with the line
# github "java", "1.0.5"	170	177	# github "java", "1.0.5"
include java	171	178	include java
	172	179
### Node definitions	173	180	### Node definitions
	174	181
Puppet has the concept of a	175	182	Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent),	176	183	['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for	177	184	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)	178	185	[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	179	186	in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following:	180	187	declaration that looks like the following:
	181	188
``` puppet	182	189	``` puppet
node default {	183	190	node default {
# core modules, needed for most things	184	191	# core modules, needed for most things
include dnsmasq	185	192	include dnsmasq
	186	193
# more...	187	194	# more...
}	188	195	}
```	189	196	```
	190	197
### How Boxen interacts with Puppet	191	198	### How Boxen interacts with Puppet
	192	199
Boxen runs everything declared in `manifests/site.pp` by default.	193	200	Boxen runs everything declared in `manifests/site.pp` by default.
But just like any other source code, throwing all your work into one massive	194	201	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	195	202	file is going to be difficult to work with. Instead, we recommend you
use modules in the `Puppetfile` when you can and make new modules	196	203	use modules in the `Puppetfile` when you can and make new modules
in the `modules/` directory when you can't. Then add `include $modulename`	197	204	in the `modules/` directory when you can't. Then add `include $modulename`
for each new module in `manifests/site.pp` to include them.	198	205	for each new module in `manifests/site.pp` to include them.
One pattern that's very common is to create a module for your organization	199	206	One pattern that's very common is to create a module for your organization
(e.g., `modules/github`) and put an environment class in that module	200	207	(e.g., `modules/github`) and put an environment class in that module