Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit d512c2e31020f5e9d61e2cb3922ec1593d5ccf82

Authored by Johan Haals
2 parents 72517b2a12 e977e27d49

Merge pull request #199 from josh-/master 

Update README

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