Getting started with the Rails Development Box

On Wednesday, 15th August 2012, the Ruby on Rails development team made a very exciting announcement on Twitter:

Ruby on Rails has been an Open Source project since 2004. Created by David Heinemier Hannson, its evolution is made possible by a community of developers under the inspiration of a core team. Anyone can contribute code to the Ruby on Rails code base. It is highly encouraged!

It seems every few months a more convenient way to make contributing to Rails becomes available. The announcement of the Ruby on Rails Development Box is another huge step to making it easier for more people to at least look at the source code.

The Ruby on Rails Development Box is a virtual machine that automatically sets up a sandbox development environment. Within this environment, you can hack, test, break and fix Rails to your heart’s content without any changes to your established development setup.

I found the setup unfamiliar so this article is really for personal reference in case I run in to trouble in the future.

Where we are going

This tutorial will get us from having no virtual machine at all to having one in which the most basic edge Rails tests can be run.

My Setup

I’ll be installing the Rails Development Box on a MacBook running Mac OS 10.6.8. I use Git installed and managed by Macports and have a GitHub account already set up. To manage different versions of Ruby, I use RVM. There will be a lot to download so I’m using an Unlimited Mobile Internet data bundle from MTN Zambia. I just hope the power does not go out because my laptop battery is quite weary.

Let’s get this show on the road.

Ruby (via RVM)

RVM is a great tool for Ruby development. Several actively developed versions of Ruby exist. RVM makes it easy to switch between them. It also provides the concept of a gemset which allows you to isolate gems from each other to use specific versions on specific projects. I like boundaries between things so gemsets make me feel warm and fuzzy.

There is a command-line installer for RVM that automatically downloads, compiles and configures RVM for you. It is available through the RVM installation page. In case you do not have curl on your Mac, you can install it with Macports using:

sudo port install curl

After that, you can install RVM:

curl -L https://get.rvm.io | bash -s stable

To test that the installation works run:

rvm list

You should see something like this:

rvm rubies
# No rvm rubies installed yet. Try 'rvm help install'.

As of writing, Edge Rails (the bleeding edge of the Ruby on Rails code base) will only work with Ruby 1.9.3 or later. To install Ruby 1.9.3 using RVM, issue the command:

rvm install 1.9.3

Let’s set up a gemset for our Rails Development Box.

rvm gemset create rails-dev-box

To get a list of the gemsets you have, use:

rvm gemset list

We’ll come back to this gemset after we set up the virtualisation tools.

VirtualBox

VirtualBox is an x86 virtualization application developed by Sun Microsystems (now Oracle). It will allow us to install an operating system (guest) within our operating system (host).

Visit the VirtualBox downloads page and grab the version for your operating system. I got the one for Mac OS X. Also, while you are at it, grab the Oracle VM VirtualBox Extension Pack as well.

Install VirtualBox first. After that, double-click the Oracle VM VirtualBox Extension Pack to run it. It should automatically launch VirtualBox which will manage the installation.

Vagrant

Vagrant makes it easy to manage deployment of virtual machines. It’s like a virtual machine chef that can take a recipe for how to build a virtual environment and then build it for us! It’s really quite cool.

There are several ways to install Vagrant. The installer is recommended. There is also a RubyGem available. I chose to install the RubyGem in the RVM gemset we created earlier.

First, create a folder to put all the Edge Rails Development files in:

mkdir -p ~/Projects/Rails/Edge
cd ~/Projects/Rails/Edge
touch .rvmrc

Next, inside .rvmrc file, put the following lines:

# Use this gemset. If it does not exist, create it
rvm use [email protected] --create

The .rvmrc will automatically load the rails-dev-box gemset whenever we navigate in to the Edge folder in ~/Projects/Rails. Without this, we’d have to manually select the gemset each time.

Finally, with the gemset in place, we’ll install Vagrant. Navigate in to ~/Projects/Rails/Edge or issue the command rvm [email protected]. This selects the gemset we created. To install Vagrant, execute:

gem install vagrant

Progress, sweet progress.

The Rails Development Box

Now, we are ready to set up the Rails Development Box. Make sure to have Git installed and create a profile on GitHub (if you have not already). We’ll use Git to install the Rails Development Box. We’ll use GitHub to create our very own fork of the Rails code base.

Again, let’s navigate in to our Edge Rails folder. We’ll clone the Rails Development Box in to it:

cd ~/Projects/Rails/Edge

Have a look at the Rails Development Box GitHub project page. To clone the repository, copy the “HTTP” or “Git-Read Only” URL then issue the git clone command, like this:

git clone git://github.com/rails/rails-dev-box.git

Then cd rails-dev-box.

The Rails Development Box has a default recipe to download an Ubuntu Server 12.04 LTS (Precise Pangolin) image (on the first run). After downloading the operating system, the recipe will install and configure a VirtualBox virtual machine and to it, install Git, MySQL, PostgreSQL, SQLite3, Ruby and perform several configurations all in a single command. The virtual machine will run “headless”. It’s really quite spectacular!

To get started, from within the rails-dev-box folder, issue this command:

vagrant up

Vagrant will take over from here. My download and configuration took over an hour so if you have errands to run, now is a good time. I’ll be waiting right here.

…

Ready to continue? Fantastic!

Vagrant has built a virtual server for us which is quietly purring away in the background just like a server should. To log in to the server, we’ll use SSH. To do that we’ll connect with:

vagrant ssh

To exit the server issue the exit command. It will remain running and ready to accept new SSH connections as you’d expect from a bare-metal server. Here are some useful Vagrant commands you may need:

1. vagrant suspend is like a pause button for your virtual environment. It will save the state of the virtual machine and wait for you to vagrant resume to start using it again.
2. vagrant halt is the equvalent of hitting the shutdown button for the server. It turns the virtual server off. You can use vagrant up to turn it on again.
3. vagrant destroy erases the virtual machine permanently. It’s as final but perhaps not as satisfying as trashing your server with a brick or axe.

Just like that, we’ve jacked in and out of our virtual server. Feels real doesn’t it!

Edge Rails

Before we can do any hacking on the Rails core, we’ll need a fork of the project. Sign in to your account on GitHub. After signing in, visit the Rails project on GitHub. To create your personal fork of the project, click “Fork”.

Now, we’ll need a copy on our development machine so we can run tests and edit the source code with our very own tools. Again, from within the rails-dev-box folder, clone your fork of the Rails project using the SSH URL (where USERNAME is your GitHub username):

git clone [email protected]:USERNAME/rails.git

Splendid!

A useful feature of the Vagrant-built virtual server is that it has shared folders. Any files we place inside the rails-dev-box folder are automatically available to us and mounted at /vagrant/.

To see just how useful this is, SSH in to the virtual server with vagrant ssh. We’ll stay inside our home folder and issue the UNIX file listing command ls -al /vagrant/.

Notice that the contents of the rails-dev-box folder are right there. In fact, any files you move in or out will be immediately available or missing from both your virtual environment (in /vagrant/) and your host machine (in ~/Projects/Rails/Edge/rails-dev-box/).

If you’ve been thinking ahead, then you’ll realise that we can use the cloned rails source code from both our development and virtual machines. In fact, that’s exactly what we’ll do.

Running the Edge Rails Test Suite

First let’s make a symbolic link so that we can access the rails folder in /vagrant/rails from the home folder (~) of the virtual machine.

ln -s /vagrant/rails ~/rails

Check that a compatible version of Ruby is installed by running ruby --version. Any Ruby from ruby 1.9.3p0 (2011-10-30 revision 33570) and above is acceptable. We can use RVM to manage Rubies on the virtual machine as well. For this tutorial, we’ll work with the installed default.

Contributing to Ruby on Rails is an excellent resource to help you get started hacking the Rails core.

Let’s see if we can get the test suite to run in the Rails Development Box. Start by navigating in to the rails foder in the virtual machine:

cd ~/rails

During setup, the Rails non-gem, development dependencies are automatically installed in the Development Box. So, all we need to do is update bundler to the most current version.

gem update bundler

Install the gem dependencies for Rails:

bundle install --without db

To run the test suite, the command is:

bundle exec rake test

Your Turn!

This is as far as I will take you, today.

The motivation to do this particular post is to encourage Zambian developers to contribute to Open Source software. I use Ruby on Rails a lot so it was a natural starting point.

Hope this inspires you!