Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 3e8aa6dbbf8c427341d0a8d86d788537d141008c

Authored by Kyle Prager
1 parent eb6290f4b8

Update README.md including module documentation 

The README.md has more detailed instructions on how to include modules from Github by editing your Puppetfile and site.pp files.

Showing 1 changed file with 43 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.
* If using full Xcode, you'll need to agree to the license by running: `xcodebuild -license` 12 12 * If using full Xcode, you'll need to agree to the license by running: `xcodebuild -license`
1. Create a new repository on GitHub as your user for your Boxen. (eg. 13 13 1. Create a new repository on GitHub as your user for your Boxen. (eg.
`wfarr/my-boxen`). **Make sure it is a private repository!** 14 14 `wfarr/my-boxen`). **Make sure it is a private repository!**
1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so: 15 15 1. Use your install of [boxen-web](https://github.com/boxen/boxen-web) or get running manually like so:
``` 16 16 ```
sudo mkdir -p /opt/boxen 17 17 sudo mkdir -p /opt/boxen
sudo chown $USER:admin /opt/boxen 18 18 sudo chown $USER:admin /opt/boxen
mkdir -p ~/src/my-boxen 19 19 mkdir -p ~/src/my-boxen
cd ~/src/my-boxen 20 20 cd ~/src/my-boxen
git init 21 21 git init
git remote add upstream https://github.com/boxen/our-boxen 22 22 git remote add upstream https://github.com/boxen/our-boxen
git fetch upstream 23 23 git fetch upstream
git checkout -b master upstream/master 24 24 git checkout -b master upstream/master
git remote add origin https://github.com/wfarr/my-boxen 25 25 git remote add origin https://github.com/wfarr/my-boxen
git push origin master 26 26 git push origin master
27 27
script/boxen 28 28 script/boxen
``` 29 29 ```
30 30
1. Close and reopen your Terminal. If you have a shell config file 31 31 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: 32 32 (eg. `~/.bashrc`) you'll need to add this at the very end:
`[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload 33 33 `[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh`, and reload
your shell. 34 34 your shell.
1. Confirm the Boxen env has loaded: `boxen --env` 35 35 1. Confirm the Boxen env has loaded: `boxen --env`
36 36
Now you have your own my-boxen repo that you can hack on. 37 37 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. 38 38 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 39 39 This is because when our-boxen goes open source that'd have some
implications about your fork also potentially being public. 40 40 implications about your fork also potentially being public.
That's obviously quite bad, so that's why we strongly suggest you 41 41 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. 42 42 create an entirely separate repo and simply pull the code in, as shown above.
43 43
## Getting your users started _after_ your "fork" exists 44 44 ## Getting your users started _after_ your "fork" exists
45 45
1. Install the Xcode Command Line Tools (full Xcode install optional). 46 46 1. Install the Xcode Command Line Tools (full Xcode install optional).
1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), **OR** have them run the following: 47 47 1. Point them at your private install of [boxen-web](https://github.com/boxen/boxen-web), **OR** have them run the following:
48 48
``` 49 49 ```
sudo mkdir -p /opt/boxen 50 50 sudo mkdir -p /opt/boxen
sudo chown $USER:admin /opt/boxen 51 51 sudo chown $USER:admin /opt/boxen
git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo 52 52 git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
cd /opt/boxen/repo 53 53 cd /opt/boxen/repo
script/boxen 54 54 script/boxen
55 55
# add boxen to your shell config, at the end, eg. 56 56 # add boxen to your shell config, at the end, eg.
echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh' 57 57 echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
``` 58 58 ```
59 59
Open a new terminal, `boxen --env` to confirm. 60 60 Open a new terminal, `boxen --env` to confirm.
61 61
## What You Get 62 62 ## What You Get
63 63
This template project provides the following by default: 64 64 This template project provides the following by default:
65 65
* Homebrew 66 66 * Homebrew
* Git 67 67 * Git
* Hub 68 68 * Hub
* DNSMasq w/ .dev resolver for localhost 69 69 * DNSMasq w/ .dev resolver for localhost
* NVM 70 70 * NVM
* RBenv 71 71 * RBenv
* Full Disk Encryption requirement 72 72 * Full Disk Encryption requirement
* NodeJS 0.4 73 73 * NodeJS 0.4
* NodeJS 0.6 74 74 * NodeJS 0.6
* NodeJS 0.8 75 75 * NodeJS 0.8
* Ruby 1.8.7 76 76 * Ruby 1.8.7
* Ruby 1.9.2 77 77 * Ruby 1.9.2
* Ruby 1.9.3 78 78 * Ruby 1.9.3
* Ack 79 79 * Ack
* Findutils 80 80 * Findutils
* GNU-Tar 81 81 * GNU-Tar
82 82
## Customizing 83 83 ## Customizing
84 84
You can always check out the number of existing modules we already 85 85 You can always check out the number of existing modules we already
provide as optional installs under the 86 86 provide as optional installs under the
[boxen organization](https://github.com/boxen). These modules are all 87 87 [boxen organization](https://github.com/boxen). These modules are all
tested to be compatible with Boxen. Use the `Puppetfile` to pull them 88 88 tested to be compatible with Boxen. Use the `Puppetfile` to pull them
in dependencies automatically whenever `boxen` is run. 89 89 in dependencies automatically whenever `boxen` is run.
90 90
91 ### Including boxen modules from github (boxen/puppet-<name>)
92
93 You must add the github information for your added Puppet module into your Puppetfile at the root of your
94 boxen repo (ex. /path/to/your-boxen/Puppetfile):
95
96 # Core modules for a basic development environment. You can replace
97 # some/most of these if you want, but it's not recommended.
98
99 github "dnsmasq", "1.0.0"
100 github "gcc", "1.0.0"
101 github "git", "1.0.0"
102 github "homebrew", "1.0.0"
103 github "hub", "1.0.0"
104 github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
105 github "nginx", "1.0.0"
106 github "nodejs", "1.0.0"
107 github "nvm", "1.0.0"
108 github "ruby", "1.0.0"
109 github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
110 github "sudo", "1.0.0"
111
112 # Optional/custom modules. There are tons available at
113 # https://github.com/boxen.
114
115 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
120 and takes the name of the module, the version, and optional repo location:
121
122 def github(name, version, options = nil)
123 options ||= {}
124 options[:repo] ||= "boxen/puppet-#{name}"
125 mod name, version, :github_tarball => options[:repo]
126 end
127
128 Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
129
130 # include the java module referenced in my Puppetfile with the line
131 # github "java", "1.0.5"
132 include java
133
### Node definitions 91 134 ### Node definitions
92 135
Puppet has the concept of a 93 136 Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent), 94 137 ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for 95 138 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) 96 139 [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 97 140 in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following: 98 141 declaration that looks like the following:
99 142
``` puppet 100 143 ``` puppet
node default { 101 144 node default {
# core modules, needed for most things 102 145 # core modules, needed for most things
include dnsmasq 103 146 include dnsmasq
104 147
# more... 105 148 # more...
} 106 149 }
``` 107 150 ```
108 151
### How Boxen interacts with Puppet 109 152 ### How Boxen interacts with Puppet
110 153
Boxen runs everything declared in `manifests/site.pp` by default. 111 154 Boxen runs everything declared in `manifests/site.pp` by default.
But just like any other source code, throwing all your work into one massive 112 155 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 113 156 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 114 157 use modules in the `Puppetfile` when you can and make new modules
in the `modules/` directory when you can't. Then add `include $modulename` 115 158 in the `modules/` directory when you can't. Then add `include $modulename`
for each new module in `manifests/site.pp` to include them. 116 159 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 117 160 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 118 161 (e.g., `modules/github`) and put an environment class in that module
to include all of the modules your organization wants to install for 119 162 to include all of the modules your organization wants to install for
everyone by default. An example of this might look like so: 120 163 everyone by default. An example of this might look like so:
121 164
``` puppet 122 165 ``` puppet
# modules/github/manifests/environment.pp 123 166 # modules/github/manifests/environment.pp
124 167
class github::environment { 125 168 class github::environment {
include github::apps::mac 126 169 include github::apps::mac