Blame view

README.md 8.54 KB
9d3e514b9   John Barnette   Initial commit
1
  # Our Boxen
0dd5e5f37   Will Farrington   Update README wit...
2
3
4
  
  This is a template Boxen project designed for your organization to fork and
  modify appropriately.
38a27ec9c   Will Farrington   README tweaks
5
6
7
  The Boxen rubygem and the Boxen puppet modules are only a framework for getting
  things done.
  This repository template is just a basic example of _how_ to do things with them.
0dd5e5f37   Will Farrington   Update README wit...
8
9
  
  ## Getting Started
c3808d88b   Will Farrington   README overhaul
10
  To give you a brief overview, we're going to:
e977e27d4   Josh Parnham   Update README
11
  * Install dependencies (basically Xcode)
c3808d88b   Will Farrington   README overhaul
12
13
14
15
16
17
18
19
  * Bootstrap a boxen for your self/team/org/company
  * Then convert your local copy of that boxen to the post-bootstrapped version
  
  There are a few potential conflicts to keep in mind.
  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
  boxen on any machine (we do some checks before every Boxen run to try
  and detect most of these and tell you anyway):
e977e27d4   Josh Parnham   Update README
20
  * Boxen __requires__ at least the Xcode Command Line Tools installed.
c3808d88b   Will Farrington   README overhaul
21
  * Boxen __will not__ work with an existing rvm install.
08009e9b0   Johan Haals   Updates README
22
  * Boxen __may not__ play nice with a GitHub username that includes dash(-)
c3808d88b   Will Farrington   README overhaul
23
24
25
26
  * Boxen __may not__ play nice with an existing rbenv install.
  * Boxen __may not__ play nice with an existing chruby install.
  * Boxen __may not__ play nice with an existing homebrew install.
  * Boxen __may not__ play nice with an existing nvm install.
e977e27d4   Josh Parnham   Update README
27
  * Boxen __recommends__ installing the full Xcode.
c3808d88b   Will Farrington   README overhaul
28
29
  
  ### Dependencies
e977e27d4   Josh Parnham   Update README
30
  **Install the Xcode Command Lines Tools and/or full Xcode.**
c3808d88b   Will Farrington   README overhaul
31
32
33
34
  This will grant you the most predictable behavior in building apps like
  MacVim.
  
  How do you do it?
e977e27d4   Josh Parnham   Update README
35
36
  1. Install Xcode from the Mac App Store.
  1. Open Xcode.
c3808d88b   Will Farrington   README overhaul
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
  1. Open the Preferences window (`Cmd-,`).
  1. Go to the Downloads tab.
  1. Install the Command Line Tools.
  
  ### Bootstrapping
  
  Create a **new** git repository somewhere.
  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
  to get started.
  The reason for that is that you can't really make private forks of public
  repositories easily.
  
  Once you've done that, you can run the following to get bootstrap
  your boxen:
  
  ```
  sudo mkdir -p /opt/boxen
  sudo chown ${USER}:admin /opt/boxen
  git clone https://github.com/boxen/our-boxen /opt/boxen/repo
  cd /opt/boxen/repo
  git remote rm origin
  git remote add origin <the location of my new git repository>
  git push -u origin master
  ```
  
  ### Distributing
  
  That's enough to get your boxen into a usable state on other machines,
  usually.
  From there, we recommend setting up
  [boxen-web](https://github.com/boxen/boxen-web)
  as an easy way to automate letting other folks install your boxen.
  
  If you _don't_ want to use boxen-web, folks can get using your boxen like so:
16ae31636   Will Farrington   add docs about ho...
72
73
74
  
  ```
  sudo mkdir -p /opt/boxen
8d29c7b59   Robin Wenglewski   change $USER to $...
75
  sudo chown ${USER}:admin /opt/boxen
c3808d88b   Will Farrington   README overhaul
76
  git clone <location of my new git repository> /opt/boxen/repo
16ae31636   Will Farrington   add docs about ho...
77
78
  cd /opt/boxen/repo
  script/boxen
c3808d88b   Will Farrington   README overhaul
79
80
81
82
83
84
85
86
  ```
  
  It should run successfully, and should tell you to source a shell script
  in your environment.
  For users without a bash or zsh config or a `~/.profile` file,
  Boxen will create a shim for you that will work correctly.
  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_:
16ae31636   Will Farrington   add docs about ho...
87

c3808d88b   Will Farrington   README overhaul
88
89
  ``` sh
  [ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
16ae31636   Will Farrington   add docs about ho...
90
  ```
c3808d88b   Will Farrington   README overhaul
91
92
93
  Once your shell is ready, open a new tab/window in your Terminal
  and you should be able to successfully run `boxen --env`.
  If that runs cleanly, you're in good shape.
16ae31636   Will Farrington   add docs about ho...
94

70e99fcbf   Will Farrington   Add customization...
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
  ## What You Get
  
  This template project provides the following by default:
  
  * Homebrew
  * Git
  * Hub
  * DNSMasq w/ .dev resolver for localhost
  * NVM
  * RBenv
  * Full Disk Encryption requirement
  * NodeJS 0.4
  * NodeJS 0.6
  * NodeJS 0.8
  * Ruby 1.8.7
  * Ruby 1.9.2
  * Ruby 1.9.3
  * Ack
  * Findutils
  * GNU-Tar
  
  ## Customizing
a0281788e   Will Farrington   README tweaks
117
118
119
120
  You can always check out the number of existing modules we already
  provide as optional installs under the
  [boxen organization](https://github.com/boxen). These modules are all
  tested to be compatible with Boxen. Use the `Puppetfile` to pull them
c3808d88b   Will Farrington   README overhaul
121
  in dependencies automatically whenever `boxen` is run.
97af892cc   Gary Larizza   Update README
122

3e8aa6dbb   Kyle Prager   Update README.md ...
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
  ### Including boxen modules from github (boxen/puppet-<name>)
  
  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):
  
      # Core modules for a basic development environment. You can replace
      # some/most of these if you want, but it's not recommended.
  
      github "dnsmasq",  "1.0.0"
      github "gcc",      "1.0.0"
      github "git",      "1.0.0"
      github "homebrew", "1.0.0"
      github "hub",      "1.0.0"
      github "inifile",  "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
      github "nginx",    "1.0.0"
      github "nodejs",   "1.0.0"
      github "nvm",      "1.0.0"
      github "ruby",     "1.0.0"
      github "stdlib",   "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
      github "sudo",     "1.0.0"
c3808d88b   Will Farrington   README overhaul
143

3e8aa6dbb   Kyle Prager   Update README.md ...
144
145
      # Optional/custom modules. There are tons available at
      # https://github.com/boxen.
c3808d88b   Will Farrington   README overhaul
146

3e8aa6dbb   Kyle Prager   Update README.md ...
147
      github "java",     "1.0.5"
c3808d88b   Will Farrington   README overhaul
148
149
150
151
  
  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
  "boxen/puppet-java".  The function "github" is defined at the top of the Puppetfile
3e8aa6dbb   Kyle Prager   Update README.md ...
152
153
154
155
156
157
158
159
160
161
162
163
164
  and takes the name of the module, the version, and optional repo location:
  
      def github(name, version, options = nil)
        options ||= {}
        options[:repo] ||= "boxen/puppet-#{name}"
        mod name, version, :github_tarball => options[:repo]
      end
  
  Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
  
      # include the java module referenced in my Puppetfile with the line
      # github "java",     "1.0.5"
      include java
a970e1571   Gary Larizza   Update README.md ...
165
  ### Node definitions
97af892cc   Gary Larizza   Update README
166

c3808d88b   Will Farrington   README overhaul
167
168
169
170
171
  Puppet has the concept of a
  ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
  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)
  in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
a970e1571   Gary Larizza   Update README.md ...
172
  declaration that looks like the following:
97af892cc   Gary Larizza   Update README
173

78dd9c617   Will Farrington   README tweaks
174
175
176
177
178
179
180
181
  ``` puppet
  node default {
    # core modules, needed for most things
    include dnsmasq
  
    # more...
  }
  ```
97af892cc   Gary Larizza   Update README
182

1bd7053c2   Gary Larizza   Update README.md ...
183
  ### How Boxen interacts with Puppet
c3808d88b   Will Farrington   README overhaul
184
185
186
187
188
189
190
191
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
  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
  in the `modules/` directory when you can't. Then add `include $modulename`
  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
  (e.g., `modules/github`) and put an environment class in that module
  to include all of the modules your organization wants to install for
1bd7053c2   Gary Larizza   Update README.md ...
193
  everyone by default. An example of this might look like so:
78dd9c617   Will Farrington   README tweaks
194
195
  ``` puppet
  # modules/github/manifests/environment.pp
1bd7053c2   Gary Larizza   Update README.md ...
196
197
198
199
200
201
202
203
   class github::environment {
     include github::apps::mac
  
     include ruby::1-8-7
  
     include projects::super-top-secret-project
   }
   ```
c3808d88b   Will Farrington   README overhaul
204
205
   If you'd like to read more about how Puppet works, we recommend
   checking out [the official documentation](http://docs.puppetlabs.com/)
1bd7053c2   Gary Larizza   Update README.md ...
206
207
208
209
210
211
   for:
  
   * [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules)
   * [Classes](http://docs.puppetlabs.com/learning/modules1.html#classes)
   * [Defined Types](http://docs.puppetlabs.com/learning/definedtypes.html)
   * [Facts](http://docs.puppetlabs.com/guides/custom_facts.html)
a970e1571   Gary Larizza   Update README.md ...
212
213
  
  ### Creating a personal module
c3808d88b   Will Farrington   README overhaul
214
  See [the documentation in the
d0a019228   Yossef Mendelssohn   relativize docume...
215
  `modules/people`](modules/people/README.md)
a970e1571   Gary Larizza   Update README.md ...
216
217
218
219
220
221
  directory for creating per-user modules that don't need to be applied
  globally to everyone.
  
  ### Creating a project module
  
  See [the documentation in the
d0a019228   Yossef Mendelssohn   relativize docume...
222
  `modules/projects`](modules/projects/README.md)
b9eac9217   Kevin R. Barnes   minor cleanup
223
  directory for creating organization projects (i.e., repositories that people
a970e1571   Gary Larizza   Update README.md ...
224
  will be working in).
966c19f70   Will Farrington   Update for script...
225
226
227
228
229
  
  ## Binary packages
  
  We support binary packaging for everything in Homebrew, RBEnv, and NVM.
  See `config/boxen.rb` for the environment variables to define.
0b8282e36   Adam Ochonicki   halp!
230

75a9261cd   Will Farrington   Update README for...
231
232
233
  ## Sharing Boxen Modules
  
  If you've got a Boxen module you'd like to be grouped under the Boxen org,
320ad92e4   Kevin Suttle   Correct typo in R...
234
  (so it can easily be found by others), please file an issue on this
75a9261cd   Will Farrington   Update README for...
235
236
237
238
239
240
  repository with a link to your module.
  We'll review the code briefly, and if things look pretty all right,
  we'll fork it under the Boxen org and give you read+write access to our
  fork.
  You'll still be the maintainer, you'll still own the issues and PRs.
  It'll just be listed under the boxen org so folks can find it more easily.
0b8282e36   Adam Ochonicki   halp!
241
  ## Halp!
34dcce691   Jon Perl   initial faq
242
  See [FAQ](https://github.com/boxen/our-boxen/blob/master/docs/faq.md).
0b8282e36   Adam Ochonicki   halp!
243
  Use Issues or #boxen on irc.freenode.net.