Onboarding a Developer, Fast

Pruning our process from days to hours

At ITHAKA we have a handful of teams working on their respective pieces of the application layer behind JSTOR. While teams’ business cases vary, their day-to-day tools and environment are largely identical. Until recently, we maintained a collection of wiki pages that outlined the commands needed to bootstrap a new hire’s machine with the appropriate software. We collected these pages in a Trello board to help with the flow, but the process still took a couple of days.

Several of the command-line installation steps required careful attention and had to be run in very specific order to achieve the desired results. There remained plenty of room for human error in either the writing of our documentation or the execution of its content, with the potential to produce divergent software versions and environments among our developers. After a spate of new developer hires, these problems manifested more often and we knew we had to take action.

After realizing each developer had at least a couple of quirks in their personal setups, we decided to take it upon ourselves to fix the problem at the source. Doing so required the realization of one key fact: if you can document a command to achieve a result, you can automate a command to achieve that same result.

Automating all the things

Over the course of a few days we were able to create a developer bootstrap script that provisioned a major segment of the software we use every day. One goal during development was idempotency—this allows anyone to run the script multiple times without issue in the event of an unexpected error. Our developers are all working on Mac OS X, so portability wasn’t a major concern at the time of writing. Here’s what we’ve incorporated into this setup so far:

Xcode’s command-line utilities are required for using command-line tools like git on Mac OS X.

Homebrew is really a must-have for Mac developers at this point. We install this along with several packages like curl, wget, and sqlite.

Mac OS X ships with Python 2.7, but our applications run on Python 3. We also install virtualenv and virtualenvwrapper to make managing our virtual environments as easy as possible. Afterward we create and install requirements to the virtual environments we know will be needed on a regular basis.

We use Ruby for things like SASS and integration tests. The script sets up RVM, installs a version or two of Ruby, and creates the gemsets we know we’ll need.

Our backend services and a few of our helper tools like service location run on Java. We have some dedicated service teams, but we application developers do work here from time to time.

We configure SSH appropriately for use with GitHub and our other deployment tools. This includes generating key pairs and setting up the .ssh directory with the appropriate info.

Our code is stored in git repositories on GitHub. The script clones these repositories and populates .gitconfig with a few properties.

We use npm and grunt to build much of our asset bundle, so the script installs these and subsequently installs the dependencies our assets define.

This approach has been used with success for a couple of new hires so far. One of our product owners also completed the process successfully in order to get more insight into our codebase—he even writes some code for us on occasion! While the initial development of the script required three or four person-days of work, it’s already paid for itself. Other teams can easily adapt and extend the script—it’s just bash, after all—to accommodate their development needs. This approach can be augmented to great effect with machine images containing bigger pieces of software like IDEs and browsers.

If you’re still letting your developers fend for themselves when it comes to software installation, consider lending them a helping hand. Spend less time installing software and more time developing features!