Configuration Management With Boxen and GitHub Enterprise

09:10 reading time

In this article, I’ll show you how to configure Boxen to work with GitHub Enterprise, sharing some of the tricks I’ve picked up by using Boxen here at Leapfrog Online.


On February 15th, 2013, GitHub launched a cool configuration management system for Macs called Boxen. If you have a bunch of developers, designers and operations folks in your organization, Boxen is a great tool for getting software installed on their workstations quickly and consistently. Under the hood, Boxen uses two key technologies: 1) Puppet, which installs software on the workstations, and 2) GitHub, which stores the Puppet configurations, propogates configuration changes to users, and handles user authentication and authorization.

At launch, Boxen worked really well for users with accounts, but you couldn’t configure it to work with GitHub Enterprise. Over the following months, the Boxen community worked to add support for GitHub Enterprise installations, and today Boxen works equally well (well, almost) with both and GitHub Entperprise.

Creating VMs…or Not

While not strictly required, I highly recommend setting up an OS X virtual machine before you start experimenting with Boxen. I actually use two: one for Mountain Lion and one for Mavericks. For each VM I maintain a snapshot of a clean, fully-upgraded OS X install, which is really helpful for testing end-to-end Boxen bootstrapping. I also take a separate snapshot with the Boxen prerequisites installed. Mountain Lion installations require Xcode and the Command Line Tools for Xcode. Mavericks installations only need the Command Line Tools; running xcode-select --install from the Terminal is a fast way to install them.

If you have VMWare 6, you should be able to set up both Mountain Lion and Mavericks VMs easily. I’ve also tried (without success) to set up OS X VMs with VirtualBox. While the VirtualBox VMs themselves work fine, some of the pre-built binaries that Boxen uses don’t seem to play well with VirtualBox.

You don’t have to use VMs for your development, but in the long run the ability to restore to a snapshot will save you a lot of time. If you want to set up some VMs now, go ahead…I’ll wait.

Setting up Boxen in GitHub Enterprise

So, your organization uses GitHub Enterprise, and you’ve decided to automate workstation configuration for you and your peers. Great! You have made a wise choice, and future generations of developers will thank you for it. Let’s create your initial Boxen environment. First, go to your GitHub Enterprise instance and create a new repository to host Boxen (something like https://<github_host>/<your_org>/my-boxen). Next, run the following command to pull down the latest version of “our-boxen”, the starting template for all Boxen configurations, to your workstation:

git clone my-boxen
cd my-boxen
## push changes to your GitHub Enterprise instance
git remote rm origin
git remote add origin https://<github_host>/<your_org>/my-boxen
git push -u origin master

Now you have a starting point, but you’re still one step away from an actual working Boxen. Go into config/boxen.rb with the editor of your choice and uncomment/set the following three environment variables, filling in the correct values for your GitHub host and organization:

ENV['BOXEN_REPO_NAME']             = '<your_org>/my-boxen'
ENV["BOXEN_GITHUB_ENTERPRISE_URL"] = 'https://<github_host>'
ENV['BOXEN_REPO_URL_TEMPLATE']     = 'https://<github_host>/%s'

The other variables don’t need to be set, so feel free to ignore them. Now go back to the Terminal and commit the changes:

git commit -am "configuring Boxen for GitHub Enterprise"
git push origin master

Now you’re ready to test! At this point I recommend switching to a VM, but if you can’t do that the steps are the same on your local workstation. Just keep in mind that Boxen wants to control your configuration and won’t play well with pre-existing versions of certain software (e.g. Homebrew, Macports, RVM, rbenv).

Go to your Terminal, pull down your Boxen, and run the configuration:

sudo mkdir -p /opt/boxen
sudo chown ${USER}:staff /opt/boxen
git clone https://<github_host>/<your_org>/my-boxen /opt/boxen/repo
cd /opt/boxen/repo
### skip the --no-fde flag if you're using Full Disk Encryption
script/boxen --no-fde

Hopefully you’ll get a successful, end-to-end run of Boxen. If everything looks OK, open a new Terminal and type boxen --help to see if Boxen is running properly. Congratulations: you’ve installed gcc, homebrew, nodenv, rbenv, git, hub, dnsmasq, nginx, 4 versions of ruby, and 4 versions of node. Now you’re ready to start customizing your Boxen installation!

Customizing your Boxen

It’s likely that you’ll want to expand beyond Boxen’s default set of modules. At Leapfrog Online we use 33 (and counting!) additional modules. Boxen’s instructions for adding new modules are here. Essentially you add the module you want in your Puppetfile, include it in you site.pp, and run boxen. Boxen will handle the rest automatically.

In theory. Unfortunately, this is one of the rough edges in Boxen’s GitHub Enterprise support. GitHub throttles API usage for anonymous users, which can cause your module downloads to fail. In order to work around this, you need to supply your API token manually (Enterprise tokens will not work). You can create a Personal Access Token for Boxen at After you update your Puppetfile, you’ll have to manually run librarian with your PAT: GITHUB_API_TOKEN=<your_PAT> ./bin/librarian-puppet Then you can run boxen to install the modules, and finally you should add the new modules to source control so they will be distributed to other users. I’d like to make this more streamlined someday.

Once you’ve added all the modules your users will need, you’re ready to distribute Boxen to the masses.

Distributing Boxen

Here are a few options for how to distribute Boxen within your organization.

Clone the repo with git

This is a simple, albeit manual, approach:

sudo mkdir -p /opt/boxen
sudo chown ${USER}:staff /opt/boxen
git clone https://<github_host>/<your_org>/my-boxen /opt/boxen/repo
cd /opt/boxen/repo

Set up a boxen-web server

There is a nifty web application that will create Boxen bootstrap scripts for users automatically: The repository describes how to deploy boxen-web via Heroku. Presumably, your GitHub Enterprise instance is behind a firewall, however, so a Heroku server isn’t an option. Therefore you’ll have to design your own deployment method for boxen-web. I’ve never attempted to use boxen-web myself.

Host your own bootstrapping script

This is the method we use at Leapfrog Online. Rather than run boxen-web, we serve a static script from GitHub Enterprise that performs a similar function. It’s based on the template that boxen-web uses internally. Here is a similar script that you can try yourself:


Here are a couple more things to keep in mind when setting up Boxen.

Creating Boxen projects

Project modules allow users to install software from the Boxen command-line. If you use the boxen::project class (and you should, because it’s awesome), keep in mind that the <org>/<repo> shorthand in the source attribute will try to pull code from You can still use the boxen::project class for GitHub Enterprise repositories; you just need to specify the full repository URL instead:

class projects::example {
  boxen::project { 'example':
    ruby          => '1.9.3',
    source        => 'https://<github_host>/<example_org>/<example_repo>'

Support for older processors

Boxen’s binaries don’t work very well with older processors (Core 2 Duos and earlier), especially under Mavericks. Testing Boxen compatibility against old processors is also a pain, since VMWare can simulate different operating systems but cannot emulate other processors. If your organization uses a lot of these older machines, Boxen may not be for you.


Hopefully this article will make setting up Boxen a little easier. If you have any questions about using Boxen with GitHub Enterprise, you can email me at


Morgan Delagrange
Director, Software Engineering