Ruby - - By João M. D. Moura

Boxen: Quit Worrying About Your Tools


How many times have you felt the pain of setting up your development environment, installing your dependencies, configuring databases, handling environment variables, and all the usual tasks that developers are supposed to do on their first day (or week, lol) when starting a new project?

If your answered “more than once”, then keep reading this post and, maybe, take your chances with Boxen (OSX only).

As the Boxen website says:

Automate the pain out of your development environment. Boxen installs your dependencies so you can focus on getting things done.

Where Did It Come From?

Boxen started as a Github Project, originally called “The Setup”. Github started developing it because they realized how much time they spent setting up development environments and how much trouble incompatible environments can produce.

They believe that development is production, so they value consistency, predictability, and reproducibility over one-off, hand-tweaked development environments. Align this with the goal of helping employees start shipping on day one and voilá.

Once that Boxen became a well-known and used internal project, they decided to extract features and wrap up everything to make it easier to work at any company.

Installing Something Manually is a Bug

The idea is to set up everything your project might need, with any customization you want, so there is no need to worry about anything else but starting development. It will not only setup your environment, but also handle all crucial updates automatically.

Boxen can clone your projects, install your toolchains, apply security policies, configure your favorite music player, set your screensaver, clone your dotfiles, and scream for help when things go haywire.

There are many, many libraries that already work with Boxen, and there is also a great community supporting it. If you can’t find what you are looking for, you can easily customize an existing library or create your own by following these simple steps.

Secret Sauce

The big secret behind all those cool features is that Boxen uses Puppet, a configuration management tool, to do all the hard work! And it’s pretty simple!

To use it, you or anyone on your team writes a project manifest. After that, all you need to do is run a single command and you’ll get a project with all its dependencies ready to go.

Let’s Get It On

Before we get to some real code examples, there are a few details you need to know to avoid silly mistakes:

  • Boxen only works on Macs
  • Boxen requires the Xcode Command Line Tools to be installed.
  • Boxen will not work with an existing rvm install.
  • Boxen may not play nice with a GitHub username that includes a 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 full Xcode.

There is a beginner’s tutorial on the Boxen repository that will guide you through the initial setup and help you with the distribution to your co-workers. Once you finish it, you will be ready to customize it as you need. Don’t forget to take a closer look at all those ready-to-use libraries!


The Puppetfile is located at the root of your Boxen repository. Place all your dependencies in this file, similar to a Gemfile.

# Core modules for a basic development environment.

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

github "java",     "1.1.0"


The manifests folder holds all the node definitions (the concept of a node is, essentially, the machine on which Puppet is running) by including the modules that you need.

Boxen runs everything inside manifests/site.pp by default. The default ‘site.pp’ file looks like:

node default {
  # core modules, needed for most things
  include dnsmasq

  # more...

The coolest part of Boxen is the amazing open source modules that configure the most common tools you might need. Now, you don’t have to write tons of code inside your manifest.

Once you have configured your Puppetfile and manifest, all you have to do is run Boxen


Boxen will ask a few questions, such as your github account credentials and your root password for sudo. With those questions answered, it will take-off and install everything.

Wrap Up

Long story short, if you have problems when setting up your work environment on a Mac, you should give Boxen a try. It’s really simple to configure and will install all the dependencies you need.

A Quick Tour

  1. On an git friendly computer

    • Fork and clone the our-boxen repository
    • Add all github modules you’ll need to the Puppetfile
    • Add all modules you want to be installed into the manifests folder
  2. On the new Mac

The Ultimate Tools Package

After many years of working on different projects, I’m excited to see the incredibly useful tools that developers have invented to make our lives easier.

Using some of those new tools, I have built (what I consider to be) the ultimate default package for any project that I’m working with using Boxen and Vagrant.

Use Boxen to set up a new machine, install VirtualBox, Vagrant, your favorite editor, and anything else you need. Once it’s done, use Vagrant to download the projects Box and setup a full environment. No fuss, no mess.

The thing is, Boxen is a great project that solves one of the most commons problems with environments. It’s supported and created by one of the most progressive and forward-looking companies. I’m sure it can and will help you, once you give it a try!