Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit c3808d88b6242ce39a17a758473838c375099837

Authored by Will Farrington
1 parent 766f9c4894

README overhaul

Showing 1 changed file with 103 additions and 65 deletions 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
1. Install Xcode Command Line Tools and/or full Xcode. 11 11 To give you a brief overview, we're going to:
* If using full Xcode, you'll need to agree to the license by running: `xcodebuild -license` 12
1. Create a new repository on GitHub as your user for your Boxen. (eg. 13
`wfarr/my-boxen`). **Make sure it is a private repository!** 14
1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so: 15
``` 16
sudo mkdir -p /opt/boxen 17
sudo chown ${USER}:admin /opt/boxen 18
mkdir -p ~/src/my-boxen 19
cd ~/src/my-boxen 20
git init 21
git remote add upstream https://github.com/boxen/our-boxen 22
git fetch upstream 23
git checkout -b master upstream/master 24
git remote add origin https://github.com/wfarr/my-boxen 25
git push origin master 26
27
script/boxen 28
``` 29
30
1. Close and reopen your Terminal. If you have a shell config file 31
(eg. `~/.bashrc`) you'll need to add this at the very end: 32
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload 33
your shell. 34
1. Confirm the Boxen env has loaded: `boxen --env` 35
36 12
Now you have your own my-boxen repo that you can hack on. 37 13 * Install dependencies (basically XCode)
You may have noticed we didn't ask you to fork the repo. 38 14 * Bootstrap a boxen for your self/team/org/company
This is because when our-boxen goes open source that'd have some 39 15 * Then convert your local copy of that boxen to the post-bootstrapped version
implications about your fork also potentially being public. 40
That's obviously quite bad, so that's why we strongly suggest you 41
create an entirely separate repo and simply pull the code in, as shown above. 42
43 16
## Getting your users started _after_ your "fork" exists 44 17 There are a few potential conflicts to keep in mind.
18 Boxen does its best not to get in the way of a dirty system,
19 but you should check into the following before attempting to install your
20 boxen on any machine (we do some checks before every Boxen run to try
21 and detect most of these and tell you anyway):
45 22
1. Install the Xcode Command Line Tools (full Xcode install optional). 46 23 * Boxen __requires__ at least the XCode Command Line Tools installed.
1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), **OR** have them run the following: 47 24 * Boxen __will not__ work with an existing rvm install.
25 * Boxen __may not__ play nice with an existing rbenv install.
26 * Boxen __may not__ play nice with an existing chruby install.
27 * Boxen __may not__ play nice with an existing homebrew install.
28 * Boxen __may not__ play nice with an existing nvm install.
29 * Boxen __recommends__ installing the full XCode.
48 30
31 ### Dependencies
32
33 **Install the XCode Command Lines Tools and/or full XCode.**
34 This will grant you the most predictable behavior in building apps like
35 MacVim.
36
37 How do you do it?
38
39 1. Install XCode from the Mac App Store.
40 1. Open XCode.
41 1. Open the Preferences window (`Cmd-,`).
42 1. Go to the Downloads tab.
43 1. Install the Command Line Tools.
44
45 ### Bootstrapping
46
47 Create a **new** git repository somewhere.
48 It can be private or public -- it really doesn't matter.
49 If you're making a repository on GitHub, you _may not_ want to fork this repo
50 to get started.
51 The reason for that is that you can't really make private forks of public
52 repositories easily.
53
54 Once you've done that, you can run the following to get bootstrap
55 your boxen:
56
``` 49 57 ```
sudo mkdir -p /opt/boxen 50 58 sudo mkdir -p /opt/boxen
sudo chown ${USER}:admin /opt/boxen 51 59 sudo chown ${USER}:admin /opt/boxen
git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo 52 60 git clone https://github.com/boxen/our-boxen /opt/boxen/repo
cd /opt/boxen/repo 53 61 cd /opt/boxen/repo
62 git remote rm origin
63 git remote add origin <the location of my new git repository>
64 git push -u origin master
65 ```
66
67 ### Distributing
68
69 That's enough to get your boxen into a usable state on other machines,
70 usually.
71 From there, we recommend setting up
72 [boxen-web](https://github.com/boxen/boxen-web)
73 as an easy way to automate letting other folks install your boxen.
74
75 If you _don't_ want to use boxen-web, folks can get using your boxen like so:
76
77 ```
78 sudo mkdir -p /opt/boxen
79 sudo chown ${USER}:admin /opt/boxen
80 git clone <location of my new git repository> /opt/boxen/repo
81 cd /opt/boxen/repo
script/boxen 54 82 script/boxen
83 ```
55 84
# add boxen to your shell config, at the end, eg. 56 85 It should run successfully, and should tell you to source a shell script
echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh' 57 86 in your environment.
87 For users without a bash or zsh config or a `~/.profile` file,
88 Boxen will create a shim for you that will work correctly.
89 If you do have a `~/.bashrc` or `~/.zshrc`, your shell will not use
90 `~/.profile` so you'll need to add a line like so at _the end of your config_:
91
92 ``` sh
93 [ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
``` 58 94 ```
59 95
Open a new terminal, `boxen --env` to confirm. 60 96 Once your shell is ready, open a new tab/window in your Terminal
97 and you should be able to successfully run `boxen --env`.
98 If that runs cleanly, you're in good shape.
61 99
## What You Get 62 100 ## What You Get
63 101
This template project provides the following by default: 64 102 This template project provides the following by default:
65 103
* Homebrew 66 104 * Homebrew
* Git 67 105 * Git
* Hub 68 106 * Hub
* DNSMasq w/ .dev resolver for localhost 69 107 * DNSMasq w/ .dev resolver for localhost
* NVM 70 108 * NVM
* RBenv 71 109 * RBenv
* Full Disk Encryption requirement 72 110 * Full Disk Encryption requirement
* NodeJS 0.4 73 111 * NodeJS 0.4
* NodeJS 0.6 74 112 * NodeJS 0.6
* NodeJS 0.8 75 113 * NodeJS 0.8
* Ruby 1.8.7 76 114 * Ruby 1.8.7
* Ruby 1.9.2 77 115 * Ruby 1.9.2
* Ruby 1.9.3 78 116 * Ruby 1.9.3
* Ack 79 117 * Ack
* Findutils 80 118 * Findutils
* GNU-Tar 81 119 * GNU-Tar
82 120
## Customizing 83 121 ## Customizing
84 122
You can always check out the number of existing modules we already 85 123 You can always check out the number of existing modules we already
provide as optional installs under the 86 124 provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all 87 125 [boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them 88 126 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run. 89 127 in dependencies automatically whenever `boxen` is run.
90 128
### Including boxen modules from github (boxen/puppet-<name>) 91 129 ### Including boxen modules from github (boxen/puppet-<name>)
92 130
You must add the github information for your added Puppet module into your Puppetfile at the root of your 93 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): 94 132 boxen repo (ex. /path/to/your-boxen/Puppetfile):
95 133
# Core modules for a basic development environment. You can replace 96 134 # Core modules for a basic development environment. You can replace
# some/most of these if you want, but it's not recommended. 97 135 # some/most of these if you want, but it's not recommended.
98 136
github "dnsmasq", "1.0.0" 99 137 github "dnsmasq", "1.0.0"
github "gcc", "1.0.0" 100 138 github "gcc", "1.0.0"
github "git", "1.0.0" 101 139 github "git", "1.0.0"
github "homebrew", "1.0.0" 102 140 github "homebrew", "1.0.0"
github "hub", "1.0.0" 103 141 github "hub", "1.0.0"
github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile" 104 142 github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
github "nginx", "1.0.0" 105 143 github "nginx", "1.0.0"
github "nodejs", "1.0.0" 106 144 github "nodejs", "1.0.0"
github "nvm", "1.0.0" 107 145 github "nvm", "1.0.0"
github "ruby", "1.0.0" 108 146 github "ruby", "1.0.0"
github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib" 109 147 github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
github "sudo", "1.0.0" 110 148 github "sudo", "1.0.0"
111 149
# Optional/custom modules. There are tons available at 112 150 # Optional/custom modules. There are tons available at
# https://github.com/boxen. 113 151 # https://github.com/boxen.
114 152
github "java", "1.0.5" 115 153 github "java", "1.0.5"
116 154
In the above snippet of a customized Puppetfile, the bottom line 117 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 118 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 119 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: 120 158 and takes the name of the module, the version, and optional repo location:
121 159
def github(name, version, options = nil) 122 160 def github(name, version, options = nil)
options ||= {} 123 161 options ||= {}
options[:repo] ||= "boxen/puppet-#{name}" 124 162 options[:repo] ||= "boxen/puppet-#{name}"
mod name, version, :github_tarball => options[:repo] 125 163 mod name, version, :github_tarball => options[:repo]
end 126 164 end
127 165
Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file: 128 166 Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
129 167
# include the java module referenced in my Puppetfile with the line 130 168 # include the java module referenced in my Puppetfile with the line
# github "java", "1.0.5" 131 169 # github "java", "1.0.5"
include java 132 170 include java
133 171
### Node definitions 134 172 ### Node definitions
135 173
Puppet has the concept of a 136 174 Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent), 137 175 ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for 138 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) 139 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 140 178 in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following: 141 179 declaration that looks like the following:
142 180
``` puppet 143 181 ``` puppet
node default { 144 182 node default {
# core modules, needed for most things 145 183 # core modules, needed for most things
include dnsmasq 146 184 include dnsmasq
147 185
# more... 148 186 # more...
} 149 187 }
``` 150 188 ```
151 189
### How Boxen interacts with Puppet 152 190 ### How Boxen interacts with Puppet
153 191
Boxen runs everything declared in `manifests/site.pp` by default. 154 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 155 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 156 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 157 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` 158 196 in the `modules/` directory when you can't. Then add `include $modulename`
for each new module in `manifests/site.pp` to include them. 159 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 160 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 161 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 162 200 to include all of the modules your organization wants to install for
everyone by default. An example of this might look like so: 163 201 everyone by default. An example of this might look like so:
164 202
``` puppet 165 203 ``` puppet
# modules/github/manifests/environment.pp 166 204 # modules/github/manifests/environment.pp
167 205
class github::environment { 168 206 class github::environment {
include github::apps::mac 169 207 include github::apps::mac
170 208
include ruby::1-8-7 171 209 include ruby::1-8-7
172 210
include projects::super-top-secret-project 173 211 include projects::super-top-secret-project
} 174 212 }
``` 175 213 ```
176 214
If you'd like to read more about how Puppet works, we recommend 177 215 If you'd like to read more about how Puppet works, we recommend
checking out [the official documentation](http://docs.puppetlabs.com/) 178 216 checking out [the official documentation](http://docs.puppetlabs.com/)
for: 179 217 for:
180 218
* [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules) 181 219 * [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules)
* [Classes](http://docs.puppetlabs.com/learning/modules1.html#classes) 182 220 * [Classes](http://docs.puppetlabs.com/learning/modules1.html#classes)
* [Defined Types](http://docs.puppetlabs.com/learning/definedtypes.html) 183 221 * [Defined Types](http://docs.puppetlabs.com/learning/definedtypes.html)
* [Facts](http://docs.puppetlabs.com/guides/custom_facts.html) 184 222 * [Facts](http://docs.puppetlabs.com/guides/custom_facts.html)
185 223
### Creating a personal module 186 224 ### Creating a personal module
187 225
See [the documentation in the 188 226 See [the documentation in the
`modules/people`](modules/people/README.md) 189 227 `modules/people`](modules/people/README.md)
directory for creating per-user modules that don't need to be applied 190 228 directory for creating per-user modules that don't need to be applied
globally to everyone. 191 229 globally to everyone.
192 230
### Creating a project module 193 231 ### Creating a project module
194 232
See [the documentation in the 195 233 See [the documentation in the
`modules/projects`](modules/projects/README.md) 196 234 `modules/projects`](modules/projects/README.md)
directory for creating organization projects (i.e., repositories that people 197 235 directory for creating organization projects (i.e., repositories that people
will be working in). 198 236 will be working in).
199 237
## Binary packages 200 238 ## Binary packages
201 239
We support binary packaging for everything in Homebrew, RBEnv, and NVM. 202 240 We support binary packaging for everything in Homebrew, RBEnv, and NVM.
See `config/boxen.rb` for the environment variables to define. 203 241 See `config/boxen.rb` for the environment variables to define.
204 242
## Sharing Boxen Modules 205 243 ## Sharing Boxen Modules