Our Boxen

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.

Getting Started

1. Install XCode Command Line Tools and/or full XCode.
2. Create a new repository on GitHub as your user for your Boxen. (eg. wfarr/my-boxen). Make sure it is a private repository!

3. Get running like so:

   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 co -b master upstream/master
   git remote add origin https://github.com/wfarr/my-boxen
   git push origin master
   
   script/boxen
   

4. 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.

5. 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.

What You Get

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

Customizing

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.

Node Definitions

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
  <...>
}

All Puppet class declarations should be included in the default node definition. Theoretically, you COULD declare every Puppet resource in the manifests/site.pp file, but that would quickly become unwieldy. Instead, it's easier to create Puppet modules inside the modules folder of the Boxen repo. Boxen is setup to discover any modules you create in the modules folder, and we've already created a people and projects module structure for you to start using.

Creating a personal module

Using the modules/people folder that's been provided in the Boxen repo, start by creating a file in modules/people/manifests in the format of your_last_name.pp (Feel free to use the Puppet module cheat sheet if you need some extra help). If we were making a module for Tim Sharpe, we would create a file called modules/people/manifests/sharpe.pp that would look like the following:

# modules/people/manifests/sharpe.pp
class people::sharpe {
  # Resource Declarations go here
  package { 'tree':
    ensure   => installed,
    provider => homebrew,
  }
}

This class is installing the tree package out of Homebrew, but feel free to add whatever resource declarations you'll need. Finally, add the following line in the manifests/site.pp file within the default node definition:

include people::sharpe

Finally, run boxen --noop to simulate, or test what changes your code would have made. If you're happy with how things look, you can then run boxen to enforce the changes you've made

You'll have to make sure your "node" (Puppet's term for your laptop, basically) includes or requires them. You can do this by either modifying manifests/site.pp for each module, or we would generally recommend you create a module for your organization (eg. modules/github) and create an environment class in that. Then you need only adjust manifests/site.pp by doing include github::environment or what-have-you for your organization.

Creating a project module

The modules/projects folder is provided for organizational projects that aren't specific to one person. You're free to create any number of modules in the modules directory. As long as you follow Puppet's module naming patterns, everything should be fine. For more information, see the documentation in the projects module template that we provide.

Binary packages

We support binary packaging for everything in Homebrew, RBEnv, and NVM. See config/boxen.rb for the environment variables to define.