Plyfe's Boxen

This is Plyfe's incarnation of GitHub's Boxen. Automated Mac provisioning.

Getting Started with Boxen at Plyfe:

tested on clean OS X 10.8 machine

Prerequisites

1. You have a GitHub account, and have been added to the plyfe organization.
2. Someone has 'onboarded' you to the plyfe/our-boxen repository and has created a modules/people/manifests/$YOUR_GITHUB_HANDLE.pp personal manifest file. See @dliggat or @chrislopresto for more info.
3. You have a public name and email address associated with your GitHub account. If you don't, the installer will bomb. See this issue for more details.

Steps

0. Format machine to a clean install of OS X 10.8 Mountain Lion

• Important: Backup all important data and settings with liberal use of Dropbox and Time Machine
• Reboot machine, insert bootable USB drive with OS X installer, and hold the Option key
• Use the USB drive's disk utility to erase Macintosh HD
• Install OS X onto the newly-erased Macintosh HD

1. Install Xcode from the Mac App Store.
2. Open Xcode -> Preferences -> Downloads -> Install Command Line Tools.
3. In that same Download window, install the iOS Simulator for the current and previous version (as of the time of writing on 2013-07-31, that would be iOS6 and iOS5.1).
4. Boxen checks and verifies that FileVault, OS X's full-disk encryption, is turned on.

• In the case of a laptop, it's probably a good idea. You can turn on FileVault in OS X's 'Security and Privacy' System Preferences pane. Be aware that this may take several hours to enable - so this should be done overnight preferrably.
• In the case of a shared machine (e.g. Mac Mini), it's probably not worth the effort.
• If you don't want Boxen to complain about the lack of FileVault, add --no-fde to step (7) to remove the check.

5. Open Terminal.app and do the following:

sudo mkdir -p /opt/boxen
sudo chown ${USER}:staff /opt/boxen
git clone https://github.com/plyfe/our-boxen.git /opt/boxen/repo
cd /opt/boxen/repo

6. Run script/boxen --debug --profile. (optionally add --no-fde if you aren't turning on FileVault)
7. When complete, close Terminal.app, and open iTerm.app via Spotlight search. Ignore Terminal and use iTerm for all future command line interactions :D
8. Now within iTerm, cd /opt/boxen/repo and run script/boxen --debug --profile for a second time (This is necessary due to what appears to be a bug in boxen - without a second run, the system wide gems are not installed, which causes bundler to fail downstream).

The machine's Plyfe boxen provisioning is now complete. Apps (Chrome, Dropbox, etc), Rubies (1.8.7, 1.9.3 - default, and 2.0.0), and Homebrew packages (heroku-toolbelt, pidof, etc) have been automatically installed. Further custom tweaks can be added and scripted automatically by editing your personal .pp manifest file (established in Prerequisite #2).

Initial Setup for the Plyfeme Project:

1. Run cd ~/code/boxen/plyfeme.
2. Run mysql -u root < db/init_dev_user.sql (Initializes the local development database user account)
3. Run bundle install.
4. Run bundle exec rake db:drop db:create db:migrate db:seed db:test:prepare.
5. Run the unit test suite: bundle exec guard. After the batch of javascript tests visibly completes, enter rspec all to run the ruby tests. Ctrl-C to exit.
6. Finally, run the app itself: script/thinserver and when it loads, visit https://development.plyfe.me:3001

Our Boxen (instructions from GitHub Inc...)

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

To give you a brief overview, we're going to:

• Install dependencies (basically Xcode)
• Bootstrap a boxen for your self/team/org/company
• Then convert your local copy of that boxen to the post-bootstrapped version

There are a few potential conflicts to keep in mind. Boxen does its best not to get in the way of a dirty system, but you should check into the following before attempting to install your boxen on any machine (we do some checks before every Boxen run to try and detect most of these and tell you anyway):

• Boxen requires at least the Xcode Command Line Tools installed.
• Boxen will not work with an existing rvm install.
• Boxen may not play nice with a GitHub username that includes dash(-)
• Boxen may not play nice with an existing rbenv install.
• Boxen may not play nice with an existing chruby install.
• Boxen may not play nice with an existing homebrew install.
• Boxen may not play nice with an existing nvm install.
• Boxen recommends installing the full Xcode.

Dependencies

Install the Xcode Command Lines Tools and/or full Xcode. This will grant you the most predictable behavior in building apps like MacVim.

How do you do it?

1. Install Xcode from the Mac App Store.
2. Open Xcode.
3. Open the Preferences window (Cmd-,).
4. Go to the Downloads tab.
5. Install the Command Line Tools.

Bootstrapping

Create a new git repository somewhere. It can be private or public -- it really doesn't matter. If you're making a repository on GitHub, you may not want to fork this repo to get started. The reason for that is that you can't really make private forks of public repositories easily.

Once you've done that, you can run the following to bootstrap your boxen:

sudo mkdir -p /opt/boxen
sudo chown ${USER}:staff /opt/boxen
git clone https://github.com/boxen/our-boxen /opt/boxen/repo
cd /opt/boxen/repo
git remote rm origin
git remote add origin <the location of my new git repository>
git push -u origin master

Distributing

That's enough to get your boxen into a usable state on other machines, usually. From there, we recommend setting up boxen-web as an easy way to automate letting other folks install your boxen.

If you don't want to use boxen-web, folks can get using your boxen like so:

sudo mkdir -p /opt/boxen
sudo chown ${USER}:staff /opt/boxen
git clone <location of my new git repository> /opt/boxen/repo
cd /opt/boxen/repo
script/boxen

Keep in mind this requires you to encrypt your hard drive by default. If you do not want to do encrypt your hard drive, you can use the --no-fde.

script/boxen --no-fde

It should run successfully, and should tell you to source a shell script in your environment. For users without a bash or zsh config or a ~/.profile file, Boxen will create a shim for you that will work correctly. If you do have a ~/.bashrc or ~/.zshrc, your shell will not use ~/.profile so you'll need to add a line like so at the end of your config:

[ -f /opt/boxen/env.sh ] && source /opt/boxen/env.sh

Once your shell is ready, open a new tab/window in your Terminal and you should be able to successfully run boxen --env. If that runs cleanly, you're in good shape.

What You Get

This template project provides the following by default:

• Homebrew
• Git
• Hub
• dnsmasq w/ .dev resolver for localhost
• rbenv
• Full Disk Encryption requirement
• Node.js 0.4
• Node.js 0.6
• Node.js 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.

Including boxen modules from github (boxen/puppet-)

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 "repository", "2.0.2"
github "dnsmasq",    "1.0.0"
github "gcc",        "1.0.0"
github "git",        "1.2.2"
github "homebrew",   "1.1.2"
github "hub",        "1.0.0"
github "inifile",    "0.9.0", :repo => "cprice404/puppetlabs-inifile"
github "nginx",      "1.4.0"
github "nodejs",     "2.2.0"
github "ruby",       "4.1.0"
github "stdlib",     "4.0.2", :repo => "puppetlabs/puppetlabs-stdlib"
github "sudo",       "1.0.0"

# Optional/custom modules. There are tons available at
# https://github.com/boxen.

github "java",     "1.1.0"

In the above snippet of a customized Puppetfile, the bottom line includes the Java module from Github using the tag "1.1.0" 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.1.0"
include java

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

  # more...
}

How Boxen interacts with Puppet

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:

• Modules
• Classes
• Defined Types
• Facts

Creating a personal module

See the documentation in the modules/people directory for creating per-user modules that don't need to be applied globally to everyone.

Creating a project module

See the documentation in the modules/projects directory for creating organization projects (i.e., repositories that people will be working in).

Binary packages

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

Sharing Boxen Modules

If you've got a Boxen module you'd like to be grouped under the Boxen org, (so it can easily be found by others), please file an issue on this repository with a link to your module. We'll review the code briefly, and if things look pretty all right, we'll fork it under the Boxen org and give you read+write access to our fork. You'll still be the maintainer, you'll still own the issues and PRs. It'll just be listed under the boxen org so folks can find it more easily.

Integrating with Github Enterprise

If you're using a Github Enterprise instance rather than github.com, you will need to set the "BOXEN_GITHUB_ENTERPRISE_URL" and "BOXEN_REPO_URL_TEMPLATE" variables in your Boxen config.

Halp!

See FAQ.

Use Issues or #boxen on irc.freenode.net.