Deploying a Ruby on Rails Development Environment onto Ubuntu Linux 8.04 or 10.04

Edwin W. Meyer

www.edwinmeyer.com

July 30, 2010

Introduction

It seems that publishing a set of Rails installation instructions is a rite of passage for many Ruby on Rails developers, and I am no different. I do not claim any special expertise, and indeed these instructions are based upon what I located on the web. I am merely reporting what worked for me in the hope that others may find the information useful.

See below for a discussion of Why Linux? Why Ubuntu? and First Get Yourself an Ubuntu Linux

Comments and especially corrections are welcome. Please email me at edwin@edwinmeyer.com

Ubuntu Versions

The following was originally performed on an Ubuntu 8.04 system. Most sections were repeated following a recent upgrade to Ubuntu 10.04. I expect that these instructions will also work with intervening Ubuntu versions 9.04 and 9.10, as well as some earlier and later versions. What is important is not the precise Ubuntu version, but that a mutual compatible set of Ruby, Rails, and supporting packages are installed. These instructions might also work with other Linux distributions which use the Debian package management system.

Also see below for a note on Turnkey Linux for Server Installation

Note on Installed Software

The following software versions are installed:

The following Ruby gem packages are installed (as listed by gem list --local)

*** LOCAL GEMS ***
actionmailer (2.3.8)
actionpack (2.3.8)
activerecord (2.3.8)
activeresource (2.3.8)
activesupport (2.3.8)
cgi_multipart_eof_fix (2.5.0) (part of mongrel Install)
daemons (1.1.0) (part of mongrel Install)
fastthread (1.0.7) (part of mongrel Install)
gem_plugin (0.2.3) (part of mongrel Install)
mongrel (1.1.5)
mysql (2.8.1)
rack (1.2.1)
rails (2.3.8)
rake (0.8.7)
rubygems-update (1.3.7)

Note: You might see different gem version numbers, or even multiple version numbers, e.g. mysql (2.8.1, 2.7). Multiple version numbers can be the result of performing a gem install when you already had a previous version installed. (Installing a gem does not automatically remove a different version of the same gem.)

Deployment onto a Development Environment

The following instructions are intended specifically for deployment of a Ruby on Rails development (not a production) environment onto Ubuntu.

1. Open a Terminal Window

Open a command window for your work by making the following menu selections from the menu bar:

Applications | Accessories | Terminal

(If there is a terminal icon on your desktop, you can instead click it.)

Gain root access for each subsequent command.

sudo -s # Then provide the root user’s password.

All subsequent work in this window is performed as root, which is required for many installation commands.
Note: You can omit this step, but in that case you will have to prefix each command requiring root access with sudo.

2. Install or Update Ruby

There are several partially conflicting Linux package manager frontends. Here, we use apt rather than aptitude or Synaptic

Perform the following to either install ruby or update it to a later version, if needed. (No action is performed for packages which are already up to date.)

apt-get install ruby-full build-essential

The packages to be downloaded are listed, plus recommendations and the amount of disk space required. It is possible that everything is up to date, in which case apt-get just returns. Otherwise apt_get pauses after outputting To continue, type: y. Do it.

You can see what has been installed or updated by performing

dpkg --list | grep ruby # Debian package manager utility, filter to show only “ruby” lines

You should see a number of packages with “ruby” either in the package name or description. Some will have versions like “1.8.7.249-2”, others “4.2”.

Note: apt and other package managers query a database of trusted repositories to download from. My downloads came from http://us.archive.ubuntu.com

3. Test the Ruby Installation

which ruby # => /usr/bin/ruby
ruby -v # => ruby 1.8.6 (2007-09-24 patchlevel 111) [i486-linux]
ruby -ropenssl -rzlib -rreadline -e "puts :success" # => success

4A. Install or Update RubyGems from RubyForge

Note: An alternate rubygems install method provided below promises to be much simpler than the method listed below (which I used.) This may install a slightly older version of RubyGems than the latest in RubyForge, but the Ubuntu repository version should work fine. Try it first.

cd /usr/local/src # download location for gem source

Here we use a multi-step procedure involving bash (shell) variables to avoid mistyping.

Set bash environment variables for downloading the latest stable version.
(http://rubyforge.org/frs/?group_id=126 provides this info.)

RUBYGEMS="rubygems-1.3.7" # latest as of this writing
RG_VERID="70696" # Hover over the .tgz link in the rubyforge page to read this

Download the “tarball” from rubyforge and unpack it.

wget http://rubyforge.org/frs/download.php/$RG_VERID/$RUBYGEMS.tgz
tar xzf $RUBYGEMS.tgz

Note: You could have just downloaded directly from the webpage into the proper directory, but I feel this explicitness is less problematic.

Switch to the created rubygem directory and install

cd $RUBYGEMS
ruby setup.rb # This can take a couple of minutes
ln -s /usr/bin/gem1.8 /usr/bin/gem # essential to place gem on search path
gem update --system # updates the gem version — unnecessary if the latest gem is downloaded

Note: Since this installation bypasses the normal package manager procedures, RubyGems will not appear as installed when using Synaptic or other package utilities.

4B. Alternate Install for RubyGems from the Ubuntu Repository

The following procedure for installing RubyGems (copied from ubuntu.com) promises to be much simpler than the procedure I used. It is supposed to work for Ubuntu 9.04 and later. However, I have not tested it.

sudo apt-get install rubygems1.8
sudo gem install rubygems-update
sudo update_rubygems # Note: this will clean out your gems!

5. RubyGems Post-Installation Tasks

Update Ruby Gems

gem update --system # Updates both RubyGems and rubygems-update to version 1.3.7, if a lower version is installed.

Test the RubyGems Installation

which gem # => /usr/bin/gem
gem --version # => 1.3.7

Add Generic Links if Necessary

A number of the web pages I checked advise the creation of generic links to individual application folders in /usr/bin (or possibly /usr/local/bin for non-Ubuntu systems.) My experience is that these are already created for you by the installation program. To check this, type

ls -l /usr/bin | grep ^l.*1\.8 # list the directory and output only those links including the string “1.8”

You are likely to find about seven pre-established links of the form ruby -> ruby1.8. These permit you to access the 1.8 version of a program by typing e.g. ruby instead of its actual name ruby1.8. If so, omit the rest of this substep.

Otherwise perform the following separately

ln -s /usr/bin/<app-name>1.8 /usr/bin/<app-name>

for each version 1.8 program, replacing <app-name> with the following seven program names: ruby, gem, rdoc, ri, irb, erb, and testrb.

6. Install Rails

Following the installation of RubyGems, use it to install Rails.

Note: While there may be packages for some of these in Debian-based Ubuntu package format, the RubyGem package manager should be used for installs as much as possible, since there are significant technical (and religious) conflicts between the Ruby Gem and Debian package manager philosophies.

gem install rails --no-rdoc --no-ri

This queries the servers in its preconfigured list to locate and download Rails.

Note: Omit "--no-rdoc --no-ri" if you have the necessary disk space want to install the associated RDoc and RI documentation packages.

Check the installed Rails version

rails -v # => Rails 2.3.8, if you have the latest version. You can omit the next step in this case.

7. Update Rails if Necessary

First, review what’s already in the local computer’s repository and what’s available remotely.

List Rails version(s) in local repository.

gem list -l rails # => Rails 2.3.3 (or another out of date version)

List Rails version(s) in remote repository.

gem list -r rails # outputs many packages with “rails” in the name, including “rails (2.3.8)”

Update rails and associated packages & docs to the latest available version.

gem update rails # updates rails packages to version 2.3.8 (except for rack, which is installed at version 1.1.0) This can take some time.

List post-update Rails version(s) in the local repository.

gem list -l rails # => rails (2.3.8, 2.3.3) — showing both new and old versions

(Optional) Uninstall an older Rails version. You will have several versions if there was a previous version already installed when you performed gem update rails.

gem uninstall rails # provides numbered list of versions) to uninstall
<enter the list number (not version) of older version to uninstall>

OR

gem uninstall rails --version 2.3.3 # Or whatever version you want to uninstall

Note: Rails also installs other related gems with the same version numbers: actionmailer, actionpack, activerecord, activeresource, and activesupport. Also uninstall these in a like manner to clear out all gems related to a particular Rails version.

The latest version is used by default when Rails is run, so I myself also have an older version installed which a particular Rails application requires.

Check the Rails version
p(ind). rails -v # => Rails 2.3.8

8. Install MySql (Optional)

I installed a MySql server on my development environment, because that is what most of the production sites I develop to run on. Rails comes preconfigured with SqlLite. Skip this step if that is sufficient for you.

Install the MySQL database and its connector. (apt-get retrieves from the Ubuntu-specified repositories — Not necessarily the latest MySql version, but good enough.)

apt-get install mysql-server mysql-client

Following the download, a window is presented asking for a password for the MySql ‘root’ user. Just cancel to allow MySql access without a password. (This is OK for a development system where the database will not be accessible over the net, but never omit a password in a production system.)

Or you may enter a password. (If you do, you will need to enter the password into each Rails app database.yml configuration file.)

apt-get install libmysql-ruby libmysqlclient-dev # You may need to instead specify libmysqlclient15-dev
gem install mysql # MySQL C Driver for Ruby

Test the installation

which mysql # => /usr/bin/mysql
mysql --version # => mysql Ver 14.14 Distrib 5.1.41, for debian-linux-gnu (i486) using readline 6.1

Access MySql & run a command to test it.

mysql
show databases; # output should include the information_schema system database
exit

Note: If you entered a password above, type: mysql -p<password entered above -- no space after '-p'>. You might also need to supply the user -u<user> option. The default is root.

Note 2: The MySql “daemon” is now configured to start automatically upon O.S. startup.

Note 3: ubuntu.com provides more valuable information about MySql installation and operation.

9. Install the Mongrel Web Server (Optional, but Recommended)

Ruby 1.8 already includes the WEBrick server, and it is ready to run in a local development environment without configuration.that is acceptable for initial work with Ruby on Rails. While WEBrick is acceptable for initial work with Ruby on Rails, installing Mongrel is very simple, and it is reputed to run faster than WEBrick. (I also found that one of my applications fails in WEBrick but works in Mongrel.1)

I installed Mongrel as follows (using the instructions at the Mongrel GitHub page:

gem install mongrel

A number of lines are output beginning as follows:

Building native extensions.  This could take a while...
Building native extensions.  This could take a while...
Successfully installed gem_plugin-0.2.3
Successfully installed daemons-1.1.0
Successfully installed fastthread-1.0.7
Successfully installed cgi_multipart_eof_fix-2.5.0
Successfully installed mongrel-1.1.5
5 gems installed
...

And that’s it!

10. Create and Run a Short Test Rails Application

Create the Application

Create the top level rails app directory test_rails_app at a location of your choice — here in your home directory.

rails ~/test_rails_app

A substantial directory structure containing the Rails framework is created within test_rails_app.

Run the Web Server from a New Terminal Window

Open a new command window, again using the menu selections Applications | Accessories | Terminal

cd ~/test_rails_app # to the top level directory of your created app.
script/server # starts the Mongrel (or WEBrick) server for this Rails application, outputs to the console, then becomes quiescent.

Note 1: The command does not return until you terminate the server by entering Ctrl-C. That is the reason for creating a new terminal window. Appending the -d option to the end of the line will detach the server from the window. However, this prevents you from seeing server output useful for debugging in the window.

Note 2: If you have installed Mongrel and you subsequently want to instead use the WEBrick server, just start the server as script/server webrick (Note “webrick” is in lower case.)

Access the Test Application from a Browser

Enter into a web browser on the local machine:

http://localhost:3000/ 

Your skeleton application in test_rails_application should present the Rails logo graphic plus “Welcome aboard – You’re riding Ruby on Rails!” with further brief information.

11. Create the Article Demo Rails Application

A very nice demo Rails application can be found at visionmasterdesigns.com. Nice, because it is almost trivial to create and deploy, yet it will test basic aspects of the Ruby on Rails installation, most critically database access. The tutorial is written for Windows systems, but it is nonetheless quite useful and informative. Brief instructions for creating and running the demo under Ubuntu using MySql follow.

rails -d mysql ~/articlesystem # create the articlesystem RoR app in the home directory. Omit -d mysql if you are using SqlLite.

mysql # also enter the password as above if needed
create database articlesystem_development;
show databases; # should include articlesystem_development in the database list
exit

Note: If you need to change the mysql username or enter a non-null password, you will have to use gedit or another text editor (I use geany) to insert/change these in the section for the articlesystem_development database in the configuration file articlesystem/config/database.yml. How to do this is not explained here.

cd ~/articlesystem
ruby script/generate scaffold article title:string article:text # creates code for the articles table. Isn’t it simple?
rake db:migrate # create articles database table with columns as specified by script/generate scaffold

To Purge An Existing Application

You might find yourself wanting to remove an application you have previously created, perhaps to recreate it afresh. Here’s how the existing articlesystem application and its MySql development database is purged.

rm -rf ~/articlesystem # delete the existing application directory hierarchy
mysql # plus password if needed
show databases; # Should display articlesystem_development
drop database articlesystem_development; # delete existing articlesystem_development database
exit

12. Run the Article Demo Rails Application

Again run a Mongrel or WEBrick web server from a separate terminal window as in step 7 above. (If you are still running the server from step 7, first type control-C to exit the server and get a command prompt — necessary to release port 3000 for reuse. You can immediately reuse this command window rather than create a new one.

cd ~/articlesystem # the web server will serve the application in the current directory
ruby script/server # start serving the articlesystem Rails application

Access the application on the local system from a browser.

http://localhost:3000/articles # Shows a page titled “Listing articles” as created by the Rails scaffolding system

Create and view a new article

Click: "New Article"

Enter text in Title & Article fields.

Click: "Create"

If you now see “Article was successfully created.” and the title and article text that you entered, you can be assured that you have successfully deployed Ruby on Rails onto your Ubuntu system.

Other RoR Ubuntu Installation Resources:

The following are some of web pages I have consulted for preparation of this document. While I can not vouch for their accuracy, You may find them useful. All are specific to Ubuntu 8.04 except as otherwise noted.

ubuntu.com The primary base for these instructions. It has extra detail related to possible errors and server installations. Ubuntu 8.04 & 9.04

funonrails.com — A recent contribution from an Indian site. Ubuntu 9.04

Peter Marklund on github.com — Comprehensive details on how to deploy to a production server environment. Includes Nginx & Capistrano.

uhleeka.com — Ubuntu 8.10

hackido.com — Includes instructions for Apache and Phusion Passenger. Ubuntu 8.10

ubuntugeek.com — Ubuntu 8.10

webbynode.com — Includes instructions for Nginx and Mongrel

linuxmonk.org — Has some info on possible errors.

adventuresinswitching.blogspot.com — Brief, but also has some error info.

Why Linux? Why Ubuntu?

It is possible to perform Ruby on Rails development under MS Windows, and the Mac OS X system is the OS of choice for many RoR developers. But for those who no longer want to put up with the awkwardness of developing under Windows and for whom the “coolness” of a Mac is a tad too pricey, Linux is the obvious alternative. After all, most RoR production deployments are onto some sort of Linux box.

There are many different Linux distributions, almost all of which are likely to be satisfactory for RoR development. I chose Ubuntu Linux simply because it is a very popular distribution with an emphasis on ease of installation and usability that is promoted by a well-resourced organization.

First Get Yourself an Ubuntu Linux

If you’re going to perform Ruby on Rails development under Ubuntu, you first need an Ubuntu system. An older underutilized PC box on which you can perform a “bare-metal” Ubuntu install would probably be ideal. Or you can convert an existing Windows installation into a dual boot Ubuntu/Windows configuration. (The Ubuntu install system can guide you through this option.) Just make sure you back up your existing system and are able to restore it if something goes wrong.

This is not the place to say much more about installing Ubuntu, but anyone interested in finding out more about Ubuntu would do well to download and read the free PDF edition of Getting Started with Ubuntu 10.04. A hardcopy version from Lulu.com is also available.

Here also are four books (with links to their Amazon.com description pages) that I am familiar with:

Ubuntu Linux Bible by William von Hagen

Recently revised for Ubuntu 10.04, this massive 1224 page tome (includes installation CD) adds hundreds of pages over the previous edition.

A Practical Guide to Ubuntu Linux by Mark G. Sobell

Due to be released in August, 2010, the Sobell book is also expanded, to 1320 pages. Plus, it will include an Ubuntu 10.04 installation DVD.

Both books offer one-stop shopping for getting started with Ubuntu 10.04. My impressions from having read the previous editions is that the von Hagen book is somewhat more user-oriented and presents overview detail of various user applications, while the Sobell book often (but not always) presents more information about Linux structure and system administration functions — necessary knowledge even for a personal Linux system. The massive amount of sometimes not well structured information provided may make both books a difficult first read.

Note: Installing from a DVD — to be included with the von Hagen book — rather than a CD as provided by the von Hagen book, is important for those with low bandwidth connections to avoid having to download packages part of the basic distribution from the Ubuntu website. Even with a DSL connection, it took me over four hours to perform this part of the installation; for those with only dialup connections, the task would be impossibly long.

Beginning Ubuntu Linux by Keir Thomas & Jaime Sicam

Provided with a DVD for the older Ubuntu 8.04 distribution, this book has the twin benefit of being more digestible (though less detailed) than the above two books, as well as focusing on how to transition from Windows. Still a hefty 768 pages, this book is an excellent introduction to Linux, especially for Windows users.

Tip: Buy this book used through Amazon at less than $6 (including shipping) along with a more recent detail-oriented book such as one of the two above.

Running Linux by Matthias Kalle Dalheimer & Matt Welsh

While it is an older 2006 book and not written specifically for the Ubuntu distribution, Running Linux is a fine book full of valuable detailed information about various packages and other aspects of Linux that doesn’t quickly go out of date. While I might not have paid $33 for the book new, I did pay $6 to get this most recent 5th edition used. You probably can too.

Turnkey Linux for Server Installation

TurnKey Linux provides a free installation CD image based upon Ubuntu 8.04 (with a beta of 10.04 as of this writing) that includes Ruby on Rails pre-installed and configured. Since it installs a server version without a GUI, this probably isn’t what you want for development. But do keep it in mind if you are going to perform a deployment to one of your own production servers.

1 I have an application that produces the following error in WEBrick when performing user authentication: NoMethodError in SessionsController#create -- undefined method `create' for WEBrick::Log:Class. It works without problem in Mongrel.