Boxen | Mobomo

Read more about Maintaining Your Boxen Install

@Intridea we use boxen as part of our employee on-boarding process and equipment upgrades. The selling point: having a shared automated process for getting machines up and ready to do real work on...

What Happened?

Recently, a co-worker received a new laptop and I pointed him to our boxen-web instance. The problem is it didn't work for him. I was confused because running boxen on my machine worked just fine. After digging deep and troubleshooting I learned that the initial install process for boxen is quite different than running the boxen command afterwards.

It had been a few months since anyone installed from scratch with our boxen setup, and the only error message I was getting was pretty vague.

sudo: /opt/boxen/rbenv/shims/gem: command not found sudo: /opt/boxen/rbenv/shims/gem: command not found ...

I could tell both ruby and git were failing to set-up properly, but it wasn't much to go on. I didn't yet know whether the failure was due to Jeff's configuration or the main boxen configuration. After having him try it with his personal manifest files removed, it was confirmed to be a problem with the main boxen configuration. The next step was to try a fresh install myself.

Fixing our Boxen Setup

First I partitioned my hard drive and installed a fresh copy of 10.9.2. I removed the files for my personal manifest from the boxen repository in order to keep the install as simple as possible. I verified that I was receiving the same error message listed above.

Next, I tried a fresh install from the mainline boxen. This also failed with a different git related error. I've mentioned before that the boxen documentation is lacking, and I was only finding issues with people having the same problem and no solution. I was out of options.

I decided to merge mainline boxen with our boxen setup. I found that doing this created conflicts in both the Puppetfile and Puppetfile.lock. I fixed the conflicts in the Puppetfile. The official boxen docs say that it isn't necessary to resolve conflicts in the Puppetfile.lock. So I tried:

rm Puppetfile.lock bundle exec librarian-puppet install --clean

However, those steps only gave me this error:

Could not resolve the dependencies.

So I backed up a step and manually resolved the conflicts in the Puppetfile.lock. This, while extremely tedious, worked.

After merging mainline boxen, I was left with the same error referring to git. I next looked at what version of git our Puppetfile was using and what was available on the puppet-git repository. I found that mainline boxen was using 2.3.0 while 2.3.1 had been released more recently. On a hunch I upgraded to 2.3.1 and performed yet another fresh install of boxen. This time it worked.

Preventative Maintenance for your Boxen

After going through the above hellish process, here's some recommendations on how to ensure smooth operation in the future.

Keep a fresh install of OS X on an external drive

You should keep whatever point release you expect to send laptops out with (10.9.2 in our case).

Use the nuke tool

After an initial boxen run, you can restore the machine to pristine status by using the nuke tool that comes with boxen.

/opt/boxen/repo/script/nuke --force --all

The above command will remove boxen entirely from your machine. It isn't necessary to reinstall OS X.

Create a dummy user for your boxen repo

You will need a github user for your organization which has no personal boxen configuration. This makes it simple to determine whether the problem lies in personal configuration or in your company wide boxen configuration (site.pp).

Test the install often

In the above scenario, I left out the part about the homebrew version that boxen uses also being broken. Testing more often would have allowed us to catch and fix each of these minor problems one by one instead of as part of a marathon debugging session.

The mainline boxen is not always correct

In the scenario above, I figured merging the mainline ought to get us to a working state. However, mainline boxen had a broken puppet-git module (2.3.0) at that point, while 2.3.1 was the version that worked. So beware of keeping up to date with mainline too fast.

Got any tips or tricks for using boxen? Send us a tweet or message us on Facebook!

Today, we are open sourcing our Boxen repository.

To do this, we are maintaining two repositories: One public and one private. The only difference is in the project-related details. The contents of each user's project manifest is empty in the public version, like so:

class projects::people::gary { }

While the private version contains whatever projects they would normally include as part of daily use:

class projects::people::gary {    include projects::intridea::omniauth   include projects::client::secret  }

The user's project manifest is then included in a standardized way:

class people::gary {    include projects::people::gary  }

Using this layer of indirection for projects, along with the personal project inclusion pattern shown above, makes for dead simple maintenance between the repositories. Said pattern creates a line between public and private information, keeping sensitive details stored exclusively in each user's project file, and then using a blank placeholder on the public version of the repository. Using placeholder project manifests combined with the indirection we add for personal project inclusion ensures that no client information will be leaked to the Web.

Why go to all the trouble of open sourcing configs?

Every piece of knowledge can help someone else, no matter how trivial it may seem. When we first got setup with Boxen, writing a personal manifest seemed like a daunting task. Boxen's documentation, although better now, is still lacking. In many cases, reading others' configurations can be a bigger help than sifting through Boxen's code and Puppet's (good, but exhaustive) documentation.

Just as we found Plyfe's boxen repo to be so helpful that we used it as a baseline for our own configs, our goal in open sourcing our Boxen configuration is to pay it forward for the next organization that takes up Boxen.

Got any tips or tricks for using Boxen? Send us a tweet or message us on Facebook!

Why we love it.

Boxen comes with an addon project called boxen-web to facilitate quick and painless installs. At Intridea, when someone receives a new company laptop, they can visit https://intridea-boxen-web.herokuapp.com/, which will OAuth with their github account and display a command to be run in the terminal.

This command will install Boxen (and its dependencies), taking approximately 30 minutes to fully install. The end result? Without any customization, you get a machine set up with rbenv, a few ruby versions, node, git, nginx, and homebrew!

Github also provides many ready to use puppet modules under the Boxen Organization on Github. They are all named starting with puppet-*. If you can’t find the package you want under the Boxen organization, using the search works as well.

The learning curve.

Now, in order to take full advantage of Boxen and customize it to your organization's needs, you’ll need to learn Puppet. It’s a bit of a learning curve; standardizing your configuration and learning another language. However, while Boxen's documentation is quite sparse, reading up on the code and researching other Boxen forks will help get you up to speed.

In addition, Boxen has a great example of how to package software so that puppet can install it here; a huge help when creating my puppet module for Drobo.

Finally, keep in mind Boxen packages tend to be Github specific. For instance, the puppet-nginx module includes a landing page for Github employees. Initially, when utilizing this package, I had expected a vanilla nginx, similar to running brew install nginx. However, due the custom site in Github's puppet-nginx module, this wasn’t the case. After some troubleshooting, removing puppet-nginx and telling Puppet to install nginx via homebrew did the job.

Quick Tip: Boxen is rather opinionated, and keeps its own homebrew install in /opt/boxen/homebrew, while homebrew installs to /usr/local by default. The quick fix for this is to use brew --prefix in your scripts instead of hard-coding /usr/local.

Remember, it’s only a tool.

Alright, so we’ve gone over why Boxen is great. However, not only does it streamline the dev machine set up (although, lets be honest having 90% of what you need for ruby dev is enough in itself!), but it’s customizable too.

With Boxen, you can add organization, project, and user level customizations. Just keep in mind, when customizing you’ll need to rewire your thought process. Instead of changing your immediate environment, you’ll need to train yourself to edit your Boxen configuration and then run the updated boxen command.

Conclusion

Boxen; the one-stop shop for ruby development on OS X. Streamlining dev environment setups and configuration, Boxen is an awesome asset to any company. It is straightforward, quick, and virtually painless.