The Set Up (You Need This)

Have you looked at your Rails ./bin directory lately? Perhaps you have a ./scripts directory as well, one your team uses to store custom scripts and avoid conflicts with Rails’ built-ins.

As a Test Double consultant, I see a ton of Rails apps. That gives me a broad perspective of the industry, or at least the portion of the industry who hires consultants like us.

That perspective includes lots of Rails scripts. For example:

• Setting up a development environment from scratch
• Abstracting some common gem or system library task
• … and that one-off script for fixing that bug in production that everyone is afraid of deleting in case the problem rises from the dead 🧟‍♂️

Over the past few years, I’ve written some simple short scripts that my clients have raved about. In this three-part series, I’ll share those scripts with you.

Setup scripts

I am a professional onboarder. Moving from client to client, I get to do it often. I even worked on the new hire onboarding team for one of our clients for a year. So I’ve seen a ton of onboarding strategies.

After the financial/privacy/HR compliance training and the SSO setup for all of your apps, the one other constant I see is the “How to set up your development environment” document.

If your document says anything much more than “Run the setup script”, you’re probably missing an opportunity.

Often, the lines of code in that document can be simply copy-pasted into a shell script file. I’ll do this myself with new clients if it looks like an easy, early win. If you notice such an opportunity in your app, take some time to knock it out now. Here’s an example bin/setup script, but your preferred installers may vary.

#!/usr/bin/env bash

# bash "strict mode"
set -euo pipefail

# install homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# install rbenv
brew install rbenv

# install a ruby
rbenv install --skip-existing

# install a db
brew install postgresql

# install gems
gem install bundler
rbenv rehash
./bin/bundle

# setup the db
brew services start postgresql
./bin/rake db:setup

Find out more about bash “strict mode”.

The trickiest part of setup may be all the system library packages. Bundler will sometimes handle system-level dependencies. But it doesn’t always. And there may be dependencies that it misses or that aren’t referenced by any of your Ruby gems, like rbenv.

That’s where package managers like Homebrew come in, specifically Homebrew Bundle. Create a Brewfile—I usually see it in a Rails app’s root directory—containing all the magic incantations your app needs to install its system libraries (usually via brew, but it could also be Mac App Store apps and VSCode plugins). Then make brew bundle (or brew bundle check || brew bundle) part of your ./bin/setup.

If you’re familiar with Homebrew Bundle, you may remember a time when it generated a lockfile named Brewfile.lock.json. It was tempting to push this file into your repo, similar to the way Bundler recommends checking in your Gemfile.lock. Unfortunately, that’s not how it was meant to be used. In practice, it generated much PR churn as dot releases were automatically fetched and installed, depending on the version specificity in your Brewfile. I experienced this myself with a client. I created piles of tiny PRs every time a locally installed library (like PostgreSQL) automatically pulled in a patch release. The lesson I learned was to “gitignore” the Homebrew lockfile. If I want to “lock” a version, I should add that version specificity to the Brewfile instead.

Thankfully, the Homebrew Bundle lockfile was removed in 2024. So if lockfile churn turned you off in the past, give it another try.

I want to give a shout-out to asdf. I’ve never used it, but it also appears to have a bundle file it calls .tools-versions, which seems to be similar to Brewfile, and dissimilar to Brewfile.lock.json. Some of my fellow Test Double agents prefer it for a couple of reasons.

First, asdf can lock libraries to more specific versions than Homebrew, reducing upgrade churn.

Unexpected updates, or “upgrade churn”, may introduce regression errors, even when library authors are careful with versioning. However, when using asdf, even bug-fix updates must be installed intentionally instead of automatically, which you may not be used to.

Second, asdf can isolate libraries to the current project directory instead of installing them system-wide, similar to nodeenv and pyenv.

If you’re looking for starter templates for your environment setup scripts, check out github/scripts-to-rule-them-all.

Shell scripting can look scary and complicated. Not every programming language is dedicated to developer happiness. 😉 Thankfully, these files don’t change often.

But I can’t get my team to agree on an environment setup! 😖

That’s ok.

If someone wants to use Docker or Nix, nothing’s stopping them. If they use Linux or Windows, more power(shell) to them. They don’t have to use your setup script. There’s enough disk space for different scripts to live side-by-side in your bin/directory. You can even create one script that branches to the others based on the current OS. (However, what language would you write it in?)

Your setup script doesn’t have to be a standard. It just needs to be a paved path. The more it’s used, the more it’s paved. You can save the standardization conversation for later.

No one is going to maintain this 🙄

A broken Rails app setup is a sign that you may not have hired anyone in a while, or ever! Everyone’s environments may be locked to a unique set of lib versions that work for them. But some of those gems or libraries may not exist on the Internet anymore. Or maybe a dreaded Mac Command Line Tools update broke the build, but no one noticed until the new hire (or consultant! 👋) attempted to onboard.

The first task for every new hire should be to fix the setup script. It’s the classic campsite rule: leave the code in a better place for the next hire.

Without frequent onboarding, your team may not notice the setup is broken until someone’s laptop needs to be replaced.

‍

*Congratulations on your new Mac! You get to be a newbie again! https://pixabay.com/photos/broken-business-monitor-2237920/ from Pixabay user https://pixabay.com/users/mediamodifier-1567646/ *

‍

If there are multiple environment setup options, every new team member gets to vote for their favorite. Over time, a standard may emerge. It’ll probably be the one that works with the least amount of haggling.

If you’re not hiring or upgrading hardware, then simply running setup on a clean machine quarterly can catch script drift before it bites you.

I hope you’ve found these environment setup scripts useful. Reducing onboarding time will reduce a new hire’s “time to first commit” by hours, even days!

Coming Next: Parts 2 and 3 of this series will shareRails scripts that make DevOps easier for your team.

‍Ed Toro is a Senior Consultant at Test Double and has experience in Ruby, Rails, and shell scripting.