Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 16ae3163667af64c1dd7fd0cd21c78c322934ac0

Authored by Will Farrington
1 parent 78dd9c6176

add docs about how to have members of your org set things up

Showing 1 changed file with 18 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
1. Install XCode Command Line Tools and/or full XCode. 11 11 1. Install XCode Command Line Tools and/or full XCode.
1. Create a new repository on GitHub as your user for your Boxen. (eg. 12 12 1. Create a new repository on GitHub as your user for your Boxen. (eg.
`wfarr/my-boxen`). **Make sure it is a private repository!** 13 13 `wfarr/my-boxen`). **Make sure it is a private repository!**
1. Get running like so: 14 14 1. Get running like so:
``` 15 15 ```
mkdir -p ~/src/my-boxen 16 16 mkdir -p ~/src/my-boxen
cd ~/src/my-boxen 17 17 cd ~/src/my-boxen
git init 18 18 git init
git remote add upstream https://github.com/boxen/our-boxen 19 19 git remote add upstream https://github.com/boxen/our-boxen
git fetch upstream 20 20 git fetch upstream
git co -b master upstream/master 21 21 git co -b master upstream/master
git remote add origin https://github.com/wfarr/my-boxen 22 22 git remote add origin https://github.com/wfarr/my-boxen
git push origin master 23 23 git push origin master
24 24
script/boxen 25 25 script/boxen
``` 26 26 ```
1. Close and reopen your Terminal. If you have a shell config file 27 27 1. Close and reopen your Terminal. If you have a shell config file
(eg. `~/.bashrc`) you'll need to add this at the very end: 28 28 (eg. `~/.bashrc`) you'll need to add this at the very end:
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload 29 29 `[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
your shell. 30 30 your shell.
1. Confirm the Boxen env has loaded: `boxen --env` 31 31 1. Confirm the Boxen env has loaded: `boxen --env`
32 32
Now you have your own my-boxen repo that you can hack on. 33 33 Now you have your own my-boxen repo that you can hack on.
You may have noticed we didn't ask you to fork the repo. 34 34 You may have noticed we didn't ask you to fork the repo.
This is because when our-boxen goes open source that'd have some 35 35 This is because when our-boxen goes open source that'd have some
implications about your fork also potentially being public. 36 36 implications about your fork also potentially being public.
That's obviously quite bad, so that's why we strongly suggest you 37 37 That's obviously quite bad, so that's why we strongly suggest you
create an entirely separate repo and simply pull the code in, as shown above. 38 38 create an entirely separate repo and simply pull the code in, as shown above.
39 39
40 ## Getting your users started _after_ your "fork" exists
41
42 1. Install the XCode Command Line Tools (full XCode install optional).
43 1. Run the following:
44
45 ```
46 sudo mkdir -p /opt/boxen
47 sudo chown $USER:admin /opt/boxen
48 git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
49 cd /opt/boxen/repo
50 script/boxen
51
52 # add boxen to your shell config, at the end, eg.
53 echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
54 ```
55
56 Open a new terminal, `boxen --env` to confirm.
57
## What You Get 40 58 ## What You Get
41 59
This template project provides the following by default: 42 60 This template project provides the following by default:
43 61
* Homebrew 44 62 * Homebrew
* Git 45 63 * Git
* Hub 46 64 * Hub
* DNSMasq w/ .dev resolver for localhost 47 65 * DNSMasq w/ .dev resolver for localhost
* NVM 48 66 * NVM
* RBenv 49 67 * RBenv
* Full Disk Encryption requirement 50 68 * Full Disk Encryption requirement
* NodeJS 0.4 51 69 * NodeJS 0.4
* NodeJS 0.6 52 70 * NodeJS 0.6
* NodeJS 0.8 53 71 * NodeJS 0.8
* Ruby 1.8.7 54 72 * Ruby 1.8.7
* Ruby 1.9.2 55 73 * Ruby 1.9.2
* Ruby 1.9.3 56 74 * Ruby 1.9.3
* Ack 57 75 * Ack
* Findutils 58 76 * Findutils
* GNU-Tar 59 77 * GNU-Tar
60 78
## Customizing 61 79 ## Customizing
62 80
You can always check out the number of existing modules we already 63 81 You can always check out the number of existing modules we already
provide as optional installs under the 64 82 provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all 65 83 [boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them 66 84 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run. 67 85 in dependencies automatically whenever `boxen` is run.
68 86
### Node definitions 69 87 ### Node definitions
70 88
Puppet has the concept of a 71 89 Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent), 72 90 ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for 73 91 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) 74 92 [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 75 93 in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following: 76 94 declaration that looks like the following:
77 95
``` puppet 78 96 ``` puppet
node default { 79 97 node default {
# core modules, needed for most things 80 98 # core modules, needed for most things
include dnsmasq 81 99 include dnsmasq
82 100
# more... 83 101 # more...
} 84 102 }
``` 85 103 ```
86 104
### How Boxen interacts with Puppet 87 105 ### How Boxen interacts with Puppet
88 106
Boxen runs everything declared in `manifests/site.pp` by default. 89 107 Boxen runs everything declared in `manifests/site.pp` by default.
But just like any other source code, throwing all your work into one massive 90 108 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 91 109 file is going to be difficult to work with. Instead, we recommend you
use modules via the `Puppetfile` when you can and making new modules 92 110 use modules via the `Puppetfile` when you can and making new modules
in the `modules/` directory when you can't. Then you just need to 93 111 in the `modules/` directory when you can't. Then you just need to
`include $modulename` those modules in `manifests/site.pp`. One pattern 94 112 `include $modulename` those modules in `manifests/site.pp`. One pattern
that's very common is to create a module for your organization 95 113 that's very common is to create a module for your organization
(eg. `modules/github`) and put an environment class in that module 96 114 (eg. `modules/github`) and put an environment class in that module
to include all of the modules your organization wants to install for 97 115 to include all of the modules your organization wants to install for
everyone by default. An example of this might look like so: 98 116 everyone by default. An example of this might look like so:
99 117
``` puppet 100 118 ``` puppet
# modules/github/manifests/environment.pp 101 119 # modules/github/manifests/environment.pp
102 120
class github::environment { 103 121 class github::environment {
include github::apps::mac 104 122 include github::apps::mac
105 123
include ruby::1-8-7 106 124 include ruby::1-8-7
107 125
include projects::super-top-secret-project 108 126 include projects::super-top-secret-project
} 109 127 }
``` 110 128 ```