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.
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.
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.
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:
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.
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 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
.rvmrc file, put the following lines:
# Use this gemset. If it does not exist, create it rvm use ruby-1.9.3-p194@rails-dev-box --create
.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 ruby-1.9.3-p194@rails-dev-box. This selects the gemset we created. To install Vagrant, execute:
gem install vagrant
Progress, sweet progress.
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:
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
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 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:
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:
vagrant suspendis like a pause button for your virtual environment. It will save the state of the virtual machine and wait for you to
vagrant resumeto start using it again.
vagrant haltis the equvalent of hitting the shutdown button for the server. It turns the virtual server off. You can use
vagrant upto turn it on again.
vagrant destroyerases 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!
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@example.com:USERNAME/rails.git
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
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
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.
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:
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
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!