Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 08009e9b0718869d269d9b1c48383e6e145950db

Authored by Johan Haals
1 parent 3c1301dba0

Updates README 

Noticed that Boxen won't run people/manifests/user-name.pp if it
includes dash

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