Jianwei Han / my-boxen

Download as
Browse Code ยป

Commit 75a9261cd309de425627bba79a9d6d2ba1112279

Authored by Will Farrington
1 parent 3a6e8ee440

Update README for Puppet Module sharing docs

Showing 1 changed file with 11 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
### Including boxen modules from github (boxen/puppet-<name>) 91 91 ### Including boxen modules from github (boxen/puppet-<name>)
92 92
You must add the github information for your added Puppet module into your Puppetfile at the root of your 93 93 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): 94 94 boxen repo (ex. /path/to/your-boxen/Puppetfile):
95 95
# Core modules for a basic development environment. You can replace 96 96 # Core modules for a basic development environment. You can replace
# some/most of these if you want, but it's not recommended. 97 97 # some/most of these if you want, but it's not recommended.
98 98
github "dnsmasq", "1.0.0" 99 99 github "dnsmasq", "1.0.0"
github "gcc", "1.0.0" 100 100 github "gcc", "1.0.0"
github "git", "1.0.0" 101 101 github "git", "1.0.0"
github "homebrew", "1.0.0" 102 102 github "homebrew", "1.0.0"
github "hub", "1.0.0" 103 103 github "hub", "1.0.0"
github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile" 104 104 github "inifile", "0.9.0", :repo => "cprice-puppet/puppetlabs-inifile"
github "nginx", "1.0.0" 105 105 github "nginx", "1.0.0"
github "nodejs", "1.0.0" 106 106 github "nodejs", "1.0.0"
github "nvm", "1.0.0" 107 107 github "nvm", "1.0.0"
github "ruby", "1.0.0" 108 108 github "ruby", "1.0.0"
github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib" 109 109 github "stdlib", "3.0.0", :repo => "puppetlabs/puppetlabs-stdlib"
github "sudo", "1.0.0" 110 110 github "sudo", "1.0.0"
111 111
# Optional/custom modules. There are tons available at 112 112 # Optional/custom modules. There are tons available at
# https://github.com/boxen. 113 113 # https://github.com/boxen.
114 114
github "java", "1.0.5" 115 115 github "java", "1.0.5"
116 116
In the above snippet of a customized Puppetfile, the bottom line 117 117 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 118 118 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 119 119 "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: 120 120 and takes the name of the module, the version, and optional repo location:
121 121
def github(name, version, options = nil) 122 122 def github(name, version, options = nil)
options ||= {} 123 123 options ||= {}
options[:repo] ||= "boxen/puppet-#{name}" 124 124 options[:repo] ||= "boxen/puppet-#{name}"
mod name, version, :github_tarball => options[:repo] 125 125 mod name, version, :github_tarball => options[:repo]
end 126 126 end
127 127
Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file: 128 128 Now Puppet knows where to download the module from when you include it in your site.pp or mypersonal.pp file:
129 129
# include the java module referenced in my Puppetfile with the line 130 130 # include the java module referenced in my Puppetfile with the line
# github "java", "1.0.5" 131 131 # github "java", "1.0.5"
include java 132 132 include java
133 133
### Node definitions 134 134 ### Node definitions
135 135
Puppet has the concept of a 136 136 Puppet has the concept of a
['node'](http://docs.puppetlabs.com/references/glossary.html#agent), 137 137 ['node'](http://docs.puppetlabs.com/references/glossary.html#agent),
which is essentially the machine on which Puppet is running. Puppet looks for 138 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) 139 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 140 140 in the `manifests/site.pp` file in the Boxen repo. You'll see a default node
declaration that looks like the following: 141 141 declaration that looks like the following:
142 142
``` puppet 143 143 ``` puppet
node default { 144 144 node default {
# core modules, needed for most things 145 145 # core modules, needed for most things
include dnsmasq 146 146 include dnsmasq
147 147
# more... 148 148 # more...
} 149 149 }
``` 150 150 ```
151 151
### How Boxen interacts with Puppet 152 152 ### How Boxen interacts with Puppet
153 153
Boxen runs everything declared in `manifests/site.pp` by default. 154 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 155 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 156 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 157 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` 158 158 in the `modules/` directory when you can't. Then add `include $modulename`
for each new module in `manifests/site.pp` to include them. 159 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 160 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 161 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 162 162 to include all of the modules your organization wants to install for
everyone by default. An example of this might look like so: 163 163 everyone by default. An example of this might look like so:
164 164
``` puppet 165 165 ``` puppet
# modules/github/manifests/environment.pp 166 166 # modules/github/manifests/environment.pp
167 167
class github::environment { 168 168 class github::environment {
include github::apps::mac 169 169 include github::apps::mac
170 170
include ruby::1-8-7 171 171 include ruby::1-8-7
172 172