What I Learned about Ruby on Rails after helping hundreds of people setup their dev machines.
Here’s what I wish I knew when I was just starting…
What you should know about setting up Rails dev environments
After having taught hundreds of people how to build a web application in a single weekend, the first step is always the same: setting up a development environment. The goal is always set the dev machine setup and tested Friday night so everyone can start coding first thing in the morning. As you can imagine things don’t always go super smoothly.
Now that I’ve done it so many times now I make this joke every time I get the chance…
I’ve installed Rails on so many machines I can install it pretty much anywhere. Give me a TI-83 calculator, I’ll get you up and running with Rails in no time.*
One-Click-Installer
I always have people install the software through the same process I would use on my own dev box if I was in their shoes. Some people have a bit of a head-start, and come to the workshop with their machine already setup through the 1-click installer.
When this happens, initially I would try to shoot ahead in our install process to the stuff they didn’t have. Inevitably, when trying to upgrade some gems, and get everything we need we would run into weird permission issues. Having spent hours debugging the issue, and trying to fix these problems on a case-by-case basis, we quickly realized it’s much easier for us to start from the beginning.
Starting fresh and having a clear path is usually way easier than being most of the way there and continuing. It’s a little counter-intuitive, but if you have almost everything setup, but you’re starting to see weird problems you don’t understand on your dev machine, starting from the beginning and knowing all the steps is almost always faster than starting close to the finish-line, but having no idea how the steps to actually get to the finish-line.
In addition to getting good at getting rails installed on people’s machines we got pretty good at removing all traces of ruby & rails.
RVM seems simpler than rbenv for someone starting out — but it’s actually not
RVM seems like a simpler ruby version manager to get started with than rbenv. I initially got involved with rbenv because I found out about the “obnoxious” redefinition of “cd” (for more info check this out), and the backlash of the ruby community. The neckbeard in me loves rbenv. RVM has long fixed the issue that was brought up, but rbenv sold me on being the right tool written by super smart people.
When setting up other people’s machines, the fact that I’m a neckbeard doesn’t mean I should impose a more complicated tool on other people. Since it takes a little bit of experience to understand what does “rbenv rehash” do? When would someone want to use that? I figured RVM would be the right tool. Plus it’s the tool I started out with…
The thing about RVM is it is a little bit simpler when it works…which is usually. However there would always be one or two times out of 25 when following the standard install that RVM would fail because of some super bizarre reason. We’d spend an hour or so debugging it, and then just “give rbenv a shot” because we’d exhausted all other options.
Following the standard install guide for rbenv has never failed once for me. It’s a few extra steps that you have to run in the terminal, but it ALWAYS WORKS, which is actually a lot better than usually working and being a little simpler.
We now start with rbenv instead of RVM because it always works.
Postgres Database
We have students install postgres on their dev machines, because they’ll be pushing to heroku and development machine environment parity with the production environment is important. It’s a lesson that I learned after being burned time after time at work, so starting people off with that best practice is something that’s important to me.
Homebrew
I liked installing postgres through homebrew, it’s the easiest way to get it on the machine for sure. But, there would be some times when OSx would have updates, or a machine would have an unusual configuration and the postgres install would fail through homebrew.
Because of that we switched away from using the homebrew installer for postgres. Having something that works all of the time, is so much more important than something that is a little easier for most people, but occasionally causes massive headaches for the minority.
Click-thru installer
The click-thru installer is pretty easy to go through. It provides a GUI that sets up the database with the username and password that you provide. The problem I had with it initially was that it also installs a ton of GUIs to do stuff (which is fine), but didn’t provide the command-line utilities that homebrew gives by default.
What took me far too long to discover was that you can access all those command-line tools too. All you have to do is add something to your bash_profile.
# ~/.bash_profile
source /Library/PostgreSQL/9.3/pg_env.sh # replace 9.3 with your version
Boom! You’re then able to run psql and pg_ctl like a pro. Being able to interface with postgres in the command-line is super helpful, especially if mistakes had been made changing the values in the installer (see the next point).
The Easiest Way to Start from Scratch on a Postgres Database
Sometimes postgres is installed fine, running like a champ, but you can’t connect to the database because the password has been forgotten, or something like that. The easiest way to solve this problem is to wipe the database and start from scratch with the data directly (I think there are ways to recover your password, but if you don’t care about the data this is by far the easiest):
sudo rm -rf /Library/PostgreSQL/9.3/data
initdb
Then you can initialize the database again with a new data directory.
Mac Updates Suck
Whenever a new mac release comes out, problems always come up that haven’t been fixed yet. It takes about a week or two after the release for the install process to be smooth. Immediately after mac updates there are always links to homebrew install issues that have no solution yet and other problems.
It’s always the worst to see a litany of StackOverflow posts with no solution…
If you’re about to setup a dev machine and an update for mac just came out, you’ll be doing yourself a favor by not upgrading for a couple weeks, unless you want to be an alpha tester for dev install tools.
GitHub’s SSH setup instructions are a little bit wrong
This page on GitHub.com is where you probably would go to learn how to setup an SSH key with GitHub. If you follow the instructions EXACTLY as they say (and don’t respond to the error messages the terminal tells you) it will fail.
The problem is that on a brand-spanking-new machine, there is not a ~/.ssh directory. That means that you can’t cd into the directory always until after step 2 in the guide. The problem comes up when you try to do ssh-add, “file not found” (because you’re not in the ~/.ssh directory, because when you tried to cd it failed).
This is a version that will work ALL THE TIME verbatim.
While it’s a super subtle thing it’s a problem that causes a ton of confusion for people just starting out.
When on Windows use a VM
If you’re on a windows box, you can use the windows installer, but we have folks use an Ubuntu Virtual Machine.
Now you can probably figure out a way to get everything to work smoothly on a windows machine if you put the time in, but the tools are way more well tested and easy to use on a Mac or Linux environment. Rather than swimming upstream, I think it’s easier to use more mainstream tools.
I know a lot of rails devs, and I only can think of one who uses rails on a windows dev box, but can think of countless that use it on Mac or Linux.
Solving the pains of an Ubuntu Virtual Machine
This first “trick” is so simple, I’m embarrassed how long it took me to figure it out.
The most painful part of running a VM on a laptop without a huge resolution is that the VM defaults to a screen that is always the same arbitrary size (I think it’s 1024 pixels tall). If your screen minus the height of the menu-bar, toolbar and startbar is less than size of the VM’s height, it will continue to render the full amount in the screen, but an annoying scrollbar will be present. If this has ever happened to you, you’ll know exactly what I’m talking about (if you haven’t, this probably sounds like gibberish). On almost all laptops if you use [HOST]+F to put the VM in FullScreen mode, you won’t have to deal with the annoying scrollbar bullshit.
An even better solution is installing guest additions. Installing guest additions allows the VM to read exactly how big your monitor is, and make it so it always displays the full amount of pixels. For any longterm hacking, setting this up is a no brainer. A word of warning though, if you install the guest additions and set some settings up wrong, it can totally brick your VM, meaning that your virtual environment won’t boot up any more. Before installing guest additions and tweaking the settings, it’s wise to make a snapshot of your VM that you can recover should problems like this arise.
Note: For our workshops, we typically don’t install the guest additions, since it’s only a weekend and the downside of it failing is way worse than the upside of getting a few extra pixels. For serious coders in the VM though, it makes sense to investigate this option.
The latest version of VirtualBox is optimized for Virtualization
And these changes take into account settings that are on machine’s BIOS. This means if you’re using the latest version of VirtualBox, and your BIOS settings on your host machine aren’t setup properly, You’re going to have a bad time. Basically your virtual machine won’t recognize the bootable medium and give a totally cryptic error.
Instead of having people mess around with their BIOS before installing VirtualBox, I typically tell people to install a slightly older, version of VirtualBox.
This falls inline with my philosophy of have something that works all the time, rather that something that’s a little better that usually works.
Command-line is better
It’s funny how much better it is to run things through a command-line vs a interface.
Teaching someone who has never touched the command-line before: what it is, how to use it and how to do a series of tasks is an order of magnitude easier than teaching how to use a user interface.
For example consider the following example to add your SSH key to heroku:
heroku login
heroku keys:add
vs. what you would have to explain using the heroku web interface:
First go to heroku.com
If your not logged in, log in now
Click on the Dashboard in the top right
Click on that ninja dude in the top right corner, to expand a menu
In the menu, click on the link to Account
Click on the Add SSH Key… textbox you see. It doesn’t really look like a textbox, but when you click it you’ll see the crossbar appear, and it will take input in
You should have your SSH key in your clipboard already, paste it into this textbox here.
Press the “add key” button
And it’s that easy. You should see a green banner that says you successfully added it successfully. If it gives you an error message, you must’ve messed up somewhere along the steps. Try again!
Rails was designed to be used in a terminal. It might be tempting to try to teach people who have no experience in the terminal how to do things with a GUI, but you’d be crazy. The terminal makes things so easy and it’s the right tool for the job.
The next steps for my dev environment journey
The first step for me was getting it so I could setup a dev machine manually, and consistently get it working. Now that I understand the pros and cons of all the tools and the process of setting up a dev box pretty well, I’m starting to look at how to automate the process as much as possible. I’ve been playing with boxen, and I have some mixed feelings. I also would love to be able to streamline the whole ubuntu virtual machine setup as well.
The nice thing about the Ubuntu VirtualBox environment is everyone always starts out at exactly the same place, a clean install of a specific version of Ubuntu, so the process almost always goes smoothly. While the Mac environment is a little more user-friendly, setting it up is a little more tricky because every machine is a little different. Some people have XCode already, some people installed a version of python that breaks the postgres installer, etc, etc.
*Note: I’ve never actually setup Rails on a TI-83 calculator, and it may actually be impossible to do.
