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 Side-by-side Diff

... ... @@ -8,56 +8,94 @@
8 8  
9 9 ## Getting Started
10 10  
11   -1. Install Xcode Command Line Tools and/or full Xcode.
12   - * If using full Xcode, you'll need to agree to the license by running: `xcodebuild -license`
13   -1. Create a new repository on GitHub as your user for your Boxen. (eg.
14   -`wfarr/my-boxen`). **Make sure it is a private repository!**
15   -1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so:
16   - ```
17   - sudo mkdir -p /opt/boxen
18   - sudo chown ${USER}:admin /opt/boxen
19   - mkdir -p ~/src/my-boxen
20   - cd ~/src/my-boxen
21   - git init
22   - git remote add upstream https://github.com/boxen/our-boxen
23   - git fetch upstream
24   - git checkout -b master upstream/master
25   - git remote add origin https://github.com/wfarr/my-boxen
26   - git push origin master
27   -
28   - script/boxen
29   - ```
30   -
31   -1. Close and reopen your Terminal. If you have a shell config file
32   -(eg. `~/.bashrc`) you'll need to add this at the very end:
33   -`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
34   -your shell.
35   -1. Confirm the Boxen env has loaded: `boxen --env`
  11 +To give you a brief overview, we're going to:
36 12  
37   -Now you have your own my-boxen repo that you can hack on.
38   -You may have noticed we didn't ask you to fork the repo.
39   -This is because when our-boxen goes open source that'd have some
40   -implications about your fork also potentially being public.
41   -That's obviously quite bad, so that's why we strongly suggest you
42   -create an entirely separate repo and simply pull the code in, as shown above.
  13 +* Install dependencies (basically XCode)
  14 +* Bootstrap a boxen for your self/team/org/company
  15 +* Then convert your local copy of that boxen to the post-bootstrapped version
43 16  
44   -## Getting your users started _after_ your "fork" exists
  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  
46   -1. Install the Xcode Command Line Tools (full Xcode install optional).
47   -1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), **OR** have them run the following:
  23 +* Boxen __requires__ at least the XCode Command Line Tools installed.
  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 ```
50 58 sudo mkdir -p /opt/boxen
51 59 sudo chown ${USER}:admin /opt/boxen
52   -git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
  60 +git clone https://github.com/boxen/our-boxen /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
54 82 script/boxen
  83 +```
55 84  
56   -# add boxen to your shell config, at the end, eg.
57   -echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
  85 +It should run successfully, and should tell you to source a shell script
  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  
60   -Open a new terminal, `boxen --env` to confirm.
  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  
62 100 ## What You Get
63 101  
... ... @@ -86,7 +124,7 @@
86 124 provide as optional installs under the
87 125 [boxen organization](https://github.com/boxen). These modules are all
88 126 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
89   -in dependencies automatically whenever `boxen` is run.
  127 +in dependencies automatically whenever `boxen` is run.
90 128  
91 129 ### Including boxen modules from github (boxen/puppet-<name>)
92 130  
93 131  
94 132  
... ... @@ -108,15 +146,15 @@
108 146 github "ruby", "1.0.0"
109 147 github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
110 148 github "sudo", "1.0.0"
111   -
  149 +
112 150 # Optional/custom modules. There are tons available at
113 151 # https://github.com/boxen.
114   -
  152 +
115 153 github "java", "1.0.5"
116   -
117   -In the above snippet of a customized Puppetfile, the bottom line
118   -includes the Java module from Github using the tag "1.0.5" from the github repository
119   -"boxen/puppet-java". The function "github" is defined at the top of the Puppetfile
  154 +
  155 +In the above snippet of a customized Puppetfile, the bottom line
  156 +includes the Java module from Github using the tag "1.0.5" from the github repository
  157 +"boxen/puppet-java". The function "github" is defined at the top of the Puppetfile
120 158 and takes the name of the module, the version, and optional repo location:
121 159  
122 160 def github(name, version, options = nil)
... ... @@ -133,11 +171,11 @@
133 171  
134 172 ### Node definitions
135 173  
136   -Puppet has the concept of a
137   -['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
138   -which is essentially the machine on which Puppet is running. Puppet looks for
139   -[node definitions](http://docs.puppetlabs.com/learning/agent_master_basic.html#node-definitions)
140   -in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
  174 +Puppet has the concept of a
  175 +['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
  176 +which is essentially the machine on which Puppet is running. Puppet looks for
  177 +[node definitions](http://docs.puppetlabs.com/learning/agent_master_basic.html#node-definitions)
  178 +in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
141 179 declaration that looks like the following:
142 180  
143 181 ``` puppet
... ... @@ -151,15 +189,15 @@
151 189  
152 190 ### How Boxen interacts with Puppet
153 191  
154   -Boxen runs everything declared in `manifests/site.pp` by default.
155   -But just like any other source code, throwing all your work into one massive
156   -file is going to be difficult to work with. Instead, we recommend you
157   -use modules in the `Puppetfile` when you can and make new modules
158   -in the `modules/` directory when you can't. Then add `include $modulename`
159   -for each new module in `manifests/site.pp` to include them.
160   -One pattern that's very common is to create a module for your organization
161   -(e.g., `modules/github`) and put an environment class in that module
162   -to include all of the modules your organization wants to install for
  192 +Boxen runs everything declared in `manifests/site.pp` by default.
  193 +But just like any other source code, throwing all your work into one massive
  194 +file is going to be difficult to work with. Instead, we recommend you
  195 +use modules in the `Puppetfile` when you can and make new modules
  196 +in the `modules/` directory when you can't. Then add `include $modulename`
  197 +for each new module in `manifests/site.pp` to include them.
  198 +One pattern that's very common is to create a module for your organization
  199 +(e.g., `modules/github`) and put an environment class in that module
  200 +to include all of the modules your organization wants to install for
163 201 everyone by default. An example of this might look like so:
164 202  
165 203 ``` puppet
... ... @@ -174,8 +212,8 @@
174 212 }
175 213 ```
176 214  
177   - If you'd like to read more about how Puppet works, we recommend
178   - checking out [the official documentation](http://docs.puppetlabs.com/)
  215 + If you'd like to read more about how Puppet works, we recommend
  216 + checking out [the official documentation](http://docs.puppetlabs.com/)
179 217 for:
180 218  
181 219 * [Modules](http://docs.puppetlabs.com/learning/modules1.html#modules)
... ... @@ -185,7 +223,7 @@
185 223  
186 224 ### Creating a personal module
187 225  
188   -See [the documentation in the
  226 +See [the documentation in the
189 227 `modules/people`](modules/people/README.md)
190 228 directory for creating per-user modules that don't need to be applied
191 229 globally to everyone.