This is a template Boxen project designed for your organization to fork and modify appropriately. 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.
- 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
- Create a new repository on GitHub as your user for your Boxen. (eg.
wfarr/my-boxen
). Make sure it is a private repository! - Use your install of boxen-web or get running manually like so:
sudo mkdir -p /opt/boxen
sudo chown $USER:admin /opt/boxen
mkdir -p ~/src/my-boxen
cd ~/src/my-boxen
git init
git remote add upstream https://github.com/boxen/our-boxen
git fetch upstream
git checkout -b master upstream/master
git remote add origin https://github.com/wfarr/my-boxen
git push origin master
script/boxen
- Close and reopen your Terminal. If you have a shell config file
(eg.
~/.bashrc
) you'll need to add this at the very end:[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh
, and reload your shell. - Confirm the Boxen env has loaded:
boxen --env
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. This is because when our-boxen goes open source that'd have some implications about your fork also potentially being public. 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.
- Install the Xcode Command Line Tools (full Xcode install optional).
- Point them at your private install of boxen-web, OR have them run the following:
sudo mkdir -p /opt/boxen
sudo chown $USER:admin /opt/boxen
git clone https://github.com/yourorg/yourreponame.git /opt/boxen/repo
cd /opt/boxen/repo
script/boxen
# add boxen to your shell config, at the end, eg.
echo '[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh'
Open a new terminal, boxen --env
to confirm.
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
You can always check out the number of existing modules we already
provide as optional installs under the
boxen organization. These modules are all
tested to be compatible with Boxen. Use the Puppetfile
to pull them
in dependencies automatically whenever boxen
is run.
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"
# Optional/custom modules. There are tons available at
# https://github.com/boxen.
github "java", "1.0.5"
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 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
Puppet has the concept of a
'node',
which is essentially the machine on which Puppet is running. Puppet looks for
node definitions
in the manifests/site.pp
file in the Boxen repo. You'll see a default node
declaration that looks like the following:
node default {
# core modules, needed for most things
include dnsmasq
# more...
}
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
everyone by default. An example of this might look like so:
# modules/github/manifests/environment.pp
class github::environment {
include github::apps::mac
include ruby::1-8-7
include projects::super-top-secret-project
}
If you'd like to read more about how Puppet works, we recommend checking out the official documentation for:
See the documentation in the
modules/people
directory for creating per-user modules that don't need to be applied
globally to everyone.
See the documentation in the
modules/projects
directory for creating organization projects (i.e., repositories that people
will be working in).
We support binary packaging for everything in Homebrew, RBEnv, and NVM.
See config/boxen.rb
for the environment variables to define.