Martin @ Blog

software development and life.


Using Boxen to manage your machine

What is Boxen

Boxen is a framework developed by Github to automate the initial installation of a new laptop for development (or any other task which requires a fixed set of tools). It is developed by Github and was initially called The Setup. The philosophy behind Boxen is that development is production which means that it should be automated like a production environment. Boxen is opinionated in some choices made by the developers who created Boxen, but it is also very pragmatic.

Boxen is basically a wrapper around Puppet, and should be used to manage your installed applications and tools. The nice part is that, since it is open source and used by quite a number of companies already, there are many modules available to automatically install and setup a wide variety of tools, ranging from MySQL to Skype and from Caffeïne to Minecraft. It is also highly configurable and it is very easy to made custom changes for individual developers or machines.

Initial installation of a laptop basically only requires you to install Xcode (which is very trivial since Mavericks) and cloning the our-boxen Git repository and your laptop will be installed within minutes. The best thing is that the latest changes and updates are also pulled automatically when you run boxen, so it is not only useful for when you have a brand new installation on your laptop.

Why Boxen

A while ago I looked into using Boxen to manage my laptop, especially because it would be a very easy way to setup laptops of new colleagues as well. Before I heard about Boxen, I created an install script for MacBooks which is used quite a lot within our company, but has a lot of issues. The main problem with an install script are:

  • Hard to make it idempotent (i.e. to re-run it once it has ran once)
  • Very hard to make it fail-safe. This is because every slight difference in configuration can make the script fail and impossible to recover. You have to cater for almost every possible setup which exists.
  • It doesn’t handle changes in configurations nicely.
  • It is a awful lot of work to keep it up-to-date

With Boxen, all those points are addressed.

Another nice thing is that Boxen is taking the pragmatic approach, so you can basically change everything and still benefit of the fact that a lot of code is reused and it will always be possible to re-run the script to automatically adopt changes in configurations required by your projects.

There are some downsides to Boxen as well. I started experimenting with Boxen around a year ago, at which point the documentation was not very abundant. That is a bit improved now, but many things still have to be deducted from the source. When you have problems, it is not always easy to find the cause and it requires some painfull debugging now and then. Fortunately, since quite some developers are using it nowadays, many issues are somehow covered in issues in Github, so this problem is less prominent then in the beginning.

The main issues I had where because we are using GitHub Enterprise (which means that we have our own GitHub installation running on a private server), and in the beginning that wasn’t really supported (or at least not documented). That is fixed now. Another issue is that our MacBooks are logging in on the Windows Active Directory stuff we have running internally, which causes some issues with user groups. This has been addressed in this issue.

Recommended way of starting with Boxen

Initially, I thought to create an our-boxen repository, tweak it and try it on a fresh VM installation of Mac OS X. While that sort of works, it is quite ellaborate and not very ‘eat your own dogfood’. As a result, I thinkered with the setup for over a year, without really using it. So that is definitely not the recommended way.

The way to get started with Boxen I recommend is to just start using it on your local development environment. For me, that meant that I had to delete my existing Homebrew installation and dump my rvm RVM setup. While that is not always a realistic option, in my experience it is the best one to get started with Boxen. It requires that you fix everything as quickly as possible in order to get a running environment ASAP and also ensures that everything actually works. Because of the fact that I wouldn’t have a running environment for at least a couple of hours, I decided to do this in between Christmas and New Year, because we’re not working that much at our office and it is not a problem that you’re not able to run everything locally anyway.

Don’t do everything with Boxen

Initially, I thought it was a good idea to basically do everything with Boxen, including checking out all the required repositories to run our services on your local machine. However, after a while I discovered that would be pretty much unmaintainable (our setup is quite dynamic, even more dynamic than I expected). So instead of that, I decided that it would be a better idea to make sure all required tools, like Play, Thrift, Scala, Maven, Java, IntelliJ, Skype, etc. would be managed by Boxen and the actualy projects (checking out, starting, stopping, executing database migrations) by the tools which are specialized in that. While we didn’t have a proper tool for those tasks, I decided to create that first (also while using it myself, so it forces me to have it in a working state). This turned out to work quite well and basically allowed me to improve the time to convert a freshly installed MacBook into a completely working environment from a couple of days to around an hour. Having the tools for updating, starting, stopping services to be separate also makes it a lot faster to keep my development machine up-to-date.

Distributing Boxen

There is a project called Boxen-web available which makes it easy to distribute a Boxen setup. However, as far as I could see, that uses Heroku. I didn’t really try it yet, but for now I opted to create a simple script which does the initial setup required for Boxen.

Some things we had to fix

We were still manipulating /etc/hosts file to actually get development domains point to your localhost. With Boxen it is relatively trivial to let everything ending in .dev point to your localmachine. This blogpost has a nice explaination on how to do this.


I have just started using Boxen on my own laptop and besides some testing in VM’s, it is not used yet to install fresh laptops (that will happen this week), so we don’t have much experience yet, but so far it looks very nice.

2 Responses to “Using Boxen to manage your machine”

  1. March 20th, 2014 at 13:58

    enrico teotti says:

    Nice article! Do you plan to use boxen only for the developers machines or also for the rest of the company’s?

  2. April 3rd, 2014 at 9:48

    Martin Sturm says:

    Only developer machines at the moment. For ‘normal’ workstations, there is already a default image and besides that, most of the non-developers are working on Windows…