Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 09873beebad4745eedd7ab1a3fac44c9bad9e55f

Authored by Eugene Vilensky
1 parent 08009e9b07

Minor grammatical edit 

I think in this case "bootstrap" is already a verb.

Showing 1 changed file with 1 additions and 1 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
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 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
It should run successfully, and should tell you to source a shell script 86 86 It should run successfully, and should tell you to source a shell script
in your environment. 87 87 in your environment.
For users without a bash or zsh config or a `~/.profile` file, 88 88 For users without a bash or zsh config or a `~/.profile` file,
Boxen will create a shim for you that will work correctly. 89 89 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 90 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 91 `~/.profile` so you'll need to add a line like so at _the end of your config_:
92 92
``` sh 93 93 ``` sh
[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh 94 94 [ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
``` 95 95 ```
96 96
Once your shell is ready, open a new tab/window in your Terminal 97 97 Once your shell is ready, open a new tab/window in your Terminal
and you should be able to successfully run `boxen --env`. 98 98 and you should be able to successfully run `boxen --env`.
If that runs cleanly, you're in good shape. 99 99 If that runs cleanly, you're in good shape.
100 100
## What You Get 101 101 ## What You Get
102 102
This template project provides the following by default: 103 103 This template project provides the following by default:
104 104
* Homebrew 105 105 * Homebrew
* Git 106 106 * Git
* Hub 107 107 * Hub
* DNSMasq w/ .dev resolver for localhost 108 108 * DNSMasq w/ .dev resolver for localhost
* NVM 109 109 * NVM
* RBenv 110 110 * RBenv
* Full Disk Encryption requirement 111 111 * Full Disk Encryption requirement
* NodeJS 0.4 112 112 * NodeJS 0.4
* NodeJS 0.6 113 113 * NodeJS 0.6
* NodeJS 0.8 114 114 * NodeJS 0.8
* Ruby 1.8.7 115 115 * Ruby 1.8.7
* Ruby 1.9.2 116 116 * Ruby 1.9.2
* Ruby 1.9.3 117 117 * Ruby 1.9.3
* Ack 118 118 * Ack
* Findutils 119 119 * Findutils
* GNU-Tar 120 120 * GNU-Tar
121 121
## Customizing 122 122 ## Customizing
123 123
You can always check out the number of existing modules we already 124 124 You can always check out the number of existing modules we already
provide as optional installs under the 125 125 provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all 126 126 [boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them 127 127 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run. 128 128 in dependencies automatically whenever `boxen` is run.
129 129
### Including boxen modules from github (boxen/puppet-<name>) 130 130 ### Including boxen modules from github (boxen/puppet-<name>)
131 131
You must add the github information for your added Puppet module into your Puppetfile at the root of your 132 132 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 133 boxen repo (ex. /path/to/your-boxen/Puppetfile):
134 134
# Core modules for a basic development environment. You can replace 135 135 # Core modules for a basic development environment. You can replace
# some/most of these if you want, but it's not recommended. 136 136 # some/most of these if you want, but it's not recommended.
137 137
github "dnsmasq", "1.0.0" 138 138 github "dnsmasq", "1.0.0"
github "gcc", "1.0.0" 139 139 github "gcc", "1.0.0"
github "git", "1.0.0" 140 140 github "git", "1.0.0"
github "homebrew", "1.0.0" 141 141 github "homebrew", "1.0.0"
github "hub", "1.0.0" 142 142 github "hub", "1.0.0"
github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile" 143 143 github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
github "nginx", "1.0.0" 144 144 github "nginx", "1.0.0"
github "nodejs", "1.0.0" 145 145 github "nodejs", "1.0.0"
github "nvm", "1.0.0" 146 146 github "nvm", "1.0.0"
github "ruby", "1.0.0" 147 147 github "ruby", "1.0.0"
github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib" 148 148 github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
github "sudo", "1.0.0" 149 149 github "sudo", "1.0.0"
150 150
# Optional/custom modules. There are tons available at 151 151 # Optional/custom modules. There are tons available at
# https://github.com/boxen. 152 152 # https://github.com/boxen.
153 153
github "java", "1.0.5" 154 154 github "java", "1.0.5"
155 155
In the above snippet of a customized Puppetfile, the bottom line 156 156 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 157 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 158 "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 159 and takes the name of the module, the version, and optional repo location:
160 160
def github(name, version, options = nil) 161 161 def github(name, version, options = nil)
options ||= {} 162 162 options ||= {}
options[:repo] ||= "boxen/puppet-#{name}" 163 163 options[:repo] ||= "boxen/puppet-#{name}"
mod name, version, :github_tarball => options[:repo] 164 164 mod name, version, :github_tarball => options[:repo]
end 165 165 end
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 Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
168 168
# include the java module referenced in my Puppetfile with the line 169 169 # include the java module referenced in my Puppetfile with the line
# github "java", "1.0.5" 170 170 # github "java", "1.0.5"
include java 171 171 include java
172 172
### Node definitions 173 173 ### Node definitions
174 174
Puppet has the concept of a 175 175 Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent), 176 176 ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for 177 177 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 178 [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 179 in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following: 180 180 declaration that looks like the following:
181 181
``` puppet 182 182 ``` puppet
node default { 183 183 node default {
# core modules, needed for most things 184 184 # core modules, needed for most things
include dnsmasq 185 185 include dnsmasq
186 186
# more... 187 187 # more...
} 188 188 }
``` 189 189 ```
190 190
### How Boxen interacts with Puppet 191 191 ### How Boxen interacts with Puppet
192 192
Boxen runs everything declared in `manifests/site.pp` by default. 193 193 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 194 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 195 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 196 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 197 in the `modules/` directory when you can't. Then add `include $modulename`
for each new module in `manifests/site.pp` to include them. 198 198 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 199 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 200 (e.g., `modules/github`) and put an environment class in that module
to include all of the modules your organization wants to install for 201 201 to include all of the modules your organization wants to install for