Ruby on Rails Tutorial

Learn Rails by Example

Michael Hartl

Contents

About the author

Michael Hartl is a programmer, educator, and entrepreneur. Michael was coauthor of RailsSpace, a best-selling Rails tutorial book published in 2007, and was cofounder and lead developer of Insoshi, a popular social networking platform in Ruby on Rails. Previously, he taught theoretical and computational physics at the California Institute of Technology (Caltech) for six years, where he received the Lifetime Achievement Award for Excellence in Teaching in 2000. Michael is a graduate of Harvard College, has a Ph.D. in Physics from Caltech, and is an alumnus of the Y Combinator program.

A book-in-progress

Ruby on Rails Tutorial is an ongoing project. The most recently completed book chapter is Chapter 7, and I hope to complete 1–2 chapters per month until it’s done, with the goal of finishing in time for RailsConf in June 2010. If you have comments or suggestions, I welcome your feedback. You should also subscribe via RSS or by email to get the latest project updates.

Ruby on Rails Tutorial Screencasts

To complement the written book, I plan to produce an associated screencast series. If you’d like to be notified when the screencasts are ready, you should subscribe to the news feed or sign up for email notifications.

Acknowledgments

This book owes a lot to my previous Rails book, RailsSpace, and hence to my coauthor Aurelius Prochazka. I’d like to thank Aure both for the work he did on that book and for his support of this one. I’d also like to thank the Rails Activists for their support and enthusiasm. As for the rest: “your name here”, as they say. Help me out and you might just get a nod. Rails newbies: tell me what’s confusing; Rails experts: tell me what sucks. (But please be nice. :-)

Copyright and license

Ruby on Rails Tutorial: Learn Rails by Example. Copyright © 2010 by Michael Hartl. All source code in Ruby on Rails Tutorial is released under the MIT License.

Chapter 1 From zero to deploy

Welcome to Ruby on Rails Tutorial: Learn Rails by Example. The goal of this book is to be the best answer to the question, “If I want to learn web development with Ruby on Rails, where should I start?” Though the Ruby on Rails web framework benefits from a wealth of learning resources—including books, blogs, and screencasts—many of them assume a substantial background in Rails. Ruby on Rails Tutorial is designed to give you this background. By the time you finish this book, you will have a solid foundation in Rails programming, ready to benefit from more advanced Rails resources.

Ruby on Rails Tutorial follows essentially the same approach as my previous Rails book,¹ teaching web development with Rails by building a sample application from scratch. This allows you to see the many different pieces of Ruby on Rails in context, motivated by real problems, as well as how those pieces fit together. Moreover, though Rails is a large and fast-moving framework, in Ruby on Rails Tutorial we’ll focus on the smaller, more stable set of core Rails techniques that have crystallized in the last couple years, so the knowledge you gain here will not soon be obsolete. We’ll also take care not to rely on the generated code called scaffolding (Box 1.1), so that the Rails knowledge you gain will be adaptable to new problems.

In this chapter, we’ll get started with Ruby on Rails by installing all the necessary software and setting up our development environment (Section 1.2). Rails Tutorial emphasizes good software development practices, so immediately after creating our fresh new Rails project we’ll put it under version control with Git (Section 1.3). And, believe it or not, in this chapter we’ll even put our app on the wider web by deploying it to production (Section 1.4). Starting in Chapter 2, we’ll begin developing our application using test-driven development (TDD),² first creating static pages, and then adding some dynamic content. In subsequent chapters, we’ll add a user data model and a full login system, and then add microblogging and social features to make a working example site.

The resulting sample application bears more than a passing resemblance to a certain popular social microblogging site—a site which, coincidentally, is also written in Rails. Though of necessity our efforts will focus on this specific sample application, the emphasis throughout Rails Tutorial will be on general principles, so that you will have a solid foundation no matter what kinds of web applications you want to build.

1.1 Introduction

Since its debut in 2004, Ruby on Rails has rapidly become one of the most powerful and popular frameworks for building dynamic web applications. Rails users run the gamut from scrappy startups to huge companies: Posterous, UserVoice, 37signals, Shopify, Scribd, Twitter, Hulu, the Yellow Pages—the list of sites using Rails goes on and on. There are also many web development shops that specialize in Rails, such as ENTP, thoughtbot, Pivotal Labs, and Hashrocket, plus innumerable independent consultants, trainers, and contractors.

What makes Rails so great? Rails owes much of its success to its elegant and compact design. By exploiting the malleability of the underlying Ruby language, Rails effectively creates a domain-specific language for writing web applications. As a result, many common web programming tasks—such as generating HTML, making data models, and routing URLs—are easy with Rails, and the resulting application code is concise and readable.

Rails also adapts rapidly to new developments in web technology and framework design. For example, Rails was one of the first frameworks to fully digest and implement the REST architectural style for structuring web applications (which we’ll be learning about throughout this tutorial). And when other frameworks develop successful new techniques, Rails creator David Heinemeier Hansson and the Rails core team don’t hesitate to incorporate their ideas. Perhaps the most dramatic example is the merger of Rails and Merb, a rival Ruby web framework, so that Rails now benefits from Merb’s modular design, stable API, and improved performance.³ (Anyone who has attended a talk by Merb developer and Rails core team member Yehuda Katz can’t help but notice what an extremely good idea it was to bring the Merb team on board.)

Finally, Rails benefits from an unusually enthusiastic and diverse community. The results include well-attended conferences, a huge number of plugins and gems (self-contained solutions to specific problems such as pagination or image upload), a rich variety of informative blogs, and a cornucopia of discussion forums and IRC channels. The large number of Rails programmers also makes it easier to handle the inevitable application errors: the “Google the error message” algorithm nearly always produces a relevant blog post or discussion-forum thread.

1.1.1 Comments for various readers

Rails Tutorial contains integrated tutorials not only for Rails, but also for the underlying Ruby language,⁴ as well as for HTML, CSS, some JavaScript, and even a little SQL. This means that, no matter where you currently are in your knowledge of web development, by the time you finish this tutorial you will be ready for more advanced Rails resources, as well as for the more systematic treatments of the other subjects mentioned.

Although this book has no formal prerequisites, you should of course have at least some computer experience. If you’ve never even used a text editor before, it will be tough going, but with enough determination you can probably soldier through. If, on the other hand, your .emacs file is so complex it could make a grown man cry, there is still be plenty of material to keep you challenged. Rails Tutorial is designed to teach Rails development no matter what your background is, but your path and reading experience will depend on your particular circumstances.

Inexperienced programmers (non-designers): Rails Tutorial doesn’t assume any background other than general computer knowledge, so if you have limited programming experience this book is a good place to start. Please bear in mind that it is only the first step on a long journey; web development has many moving parts, including HTML/CSS, JavaScript, databases (including SQL), version control, and deployment. This book contains short introductions to these subjects, but there is much more to learn.

Inexperienced programmers (designers): Your design skills give you a big leg up, since you probably already know HTML and CSS. After finishing this book you will be in an excellent position to work with existing Rails projects and possibly start some of your own. You may find the programming material challenging, but the Ruby language is unusually friendly to beginners, especially those with an artistic bent.

After finishing Ruby on Rails Tutorial, I recommend that newer programmers read Beginning Ruby by Peter Cooper, which shares the same basic instructional philosophy as Rails Tutorial. After finishing Beginning Ruby, you’ll be ready for Agile Web Development with Rails by Dave Thomas and David Heinemeier Hansson and The Rails Way by Obie Fernandez.

Web applications, even relatively simple ones, are by their nature fairly complex. If you are completely new to web programming and find Rails Tutorial overwhelming, it could be that you’re not quite ready to make web applications yet. In that case, I’d suggest learning the basics of HTML and CSS and then giving Rails Tutorial another go. (Unfortunately, I don’t have a personal recommendation here, but Head First HTML looks promising.) You might also consider reading the first few chapters of Beginning Ruby, which starts with sample applications much smaller than a full-blown web app.

Experienced programmers new to web development: Your previous experience means you probably already understand ideas like classes, methods, data structures, etc., which is a big advantage. Be warned that if your background is in C/C++ or Java, you may find Ruby a bit of an odd duck, and it might take time to get used to it; just stick with it and eventually you’ll be fine. (Ruby even lets you put semicolons at the ends of lines if you miss them too much. :-) Rails Tutorial covers all the web-specific ideas you’ll need, so don’t worry if you don’t currently know a PUT from a POST.

Experienced web developers new to Rails: You have a great head start, especially if you have used a dynamic language such as PHP or (even better) Python. The basics of what we cover will likely be familiar, but test-driven development may be new to you, as may be the structured REST style favored by Rails. Ruby has its own idiosyncrasies, so those will likely be new, too.

Experienced Ruby programmers: The set of Ruby programmers who don’t know Rails is a small one nowadays, but if you are a member of this elite group you can fly through this book and move on to Agile Web Development with Rails or The Rails Way. (Of course, you could try skipping right to one of those books, but I still think my intro material is better. ;-)

After finishing Ruby on Rails Tutorial, I recommend that experienced programmers read The Well-Grounded Rubyist by David A. Black, which is an excellent in-depth discussion of Ruby from the ground up. Then move on to Agile Web Development with Rails by Dave Thomas and David Heinemeier Hansson and The Rails Way by Obie Fernandez.

Inexperienced Rails programmers: You’ve perhaps read some other tutorials and made a few small Rails apps yourself. I suspect that you can still get a lot out of this book. Among other things, the techniques here may be more up-to-date than the ones you picked up when you originally learned Rails. Let me know if my suspicion is correct.

Experienced Rails programmers: This book is unnecessary for you, but you might enjoy seeing Rails from a different perspective. I’d especially like your feedback on any code you think can be improved (bearing in mind that it shouldn’t be too advanced too soon).

At the end of this process, no matter where you started, you will be ready for the more intermediate-to-advanced Rails resources. Here are some I particularly recommend:

• Railscasts: Excellent free Rails screencasts
• PeepCode, Pragmatic.tv, EnvyCasts: Excellent commercial screencasters
• Rails Guides: Good topical and up-to-date Rails references. Rails Tutorial refers frequently to the Rails Guides for more in-depth treatment of specific topics.
• Rails blogs: Too many to list, but there are tons of good ones.

1.1.2 “Scaling” Rails

Before moving on with the rest of the introduction, I’d like to take a moment to address the one issue that dogged the Rails framework the most in its early days: the supposed inability of Rails to “scale”—i.e., to handle large amounts of traffic. Part of this issue relied on a misconception; you scale a site, not a framework, and Rails, as awesome as it is, is only a framework. So the real question should have been, “Can a site built with Rails scale?” In any case, the question has now been definitively answered in the affirmative: some of the most heavily trafficked sites in the world use Rails. Actually doing the scaling is beyond the scope of just Rails, but rest assured that if your application ever needs to handle the load of Hulu or the Yellow Pages, Rails won’t stop you from taking over the world.

1.1.3 Conventions in this book

The conventions in this book are mostly self-explanatory; in this section I’ll mention some that may not be. First, both the HTML and PDF editions of this book are full of links, both to internal sections (such as Section 1.2) and to external sites (such as the main Ruby on Rails download page).⁵ Sometimes you may encounter an undefined internal link, such as Section sec:not_yet_defined, but don’t be alarmed; this is a book-in-progress, and these undefined cross-references are usually intentional reminders of gaps to fill.

Second, your humble author is a Linux/OS X kind of guy, and hasn’t used Windows as his primary OS for more than a decade; as a result, Rails Tutorial has an unmistakable Unix flavor.⁶ For example, in this book all command line examples use a Unix-style command line prompt (a dollar sign):

$ echo "hello, world"
hello, world

Rails comes with lots of commands that can be run directly under Unix but often require an explicit call to the Ruby interpreter under Windows;⁷ for example, in Section 1.2.5 we’ll run a local development web server as follows:

# Unix (Linux, OS X, etc.)
$ script/server
# Windows (explicitly uses the Ruby interpreter)
> ruby script/server

Rails Tutorial will also use Unix-style forward slashes as directory separators; my Rails Tutorial sample app, for instance, lives in

/Users/mhartl/rails_projects/sample_app

The root directory for any given app is known as the Rails root, and henceforth all directories will be relative to this directory. For example, the config directory of my sample application is in

/Users/mhartl/rails_projects/sample_app/config

This means that when referring to the file

/Users/mhartl/rails_projects/sample_app/config/routes.rb

I’ll omit the Rails root and write config/routes.rb for brevity.

1.2 Up and running

It’s time now to get going with a Ruby on Rails development environment and a sample application. There is quite a bit of overhead here, especially if you don’t have extensive programming experience, so don’t get discouraged if it takes a while to get started. It’s not just you; every developer goes through it (often more than once), but rest assured that the effort will be richly rewarded.

1.2.1 Development environments

Considering various idiosyncratic customizations, there are probably as many development environments as there are Rails programmers, but there are at least two broad themes: text editor/command line environments, and integrated development environments (IDEs). Let’s consider the latter first.

IDEs

There is no shortage of Rails IDEs; indeed, the main Ruby on Rails site names four: RadRails, RubyMine, 3rd Rail, and NetBeans. All are cross-platform, and I’ve heard good things about several of them. I encourage you to try them and see if they work for you, but I have a confession to make: I have never found an IDE that met all my Rails development needs—and for some projects I haven’t even been able to get them to work at all.

Text editors and command lines

What are we to use to develop Rails apps, if not some awesome all-in-one IDE? I’d guess the majority of Rails developers opt for the same solution I’ve chosen: use a text editor to edit text, and a command line to issue commands (Figure 1.1). Which combination you use depends on your tastes and your platform:

• Macintosh OS X: Like many Rails developers, I prefer TextMate. Other options include Emacs and MacVim (launched with the command macvim), the excellent Macintosh version of Vim.⁸ I use iTerm for my command line terminal; others prefer the native Terminal app.
• Linux: Your editor options are basically the same as OS X, minus TextMate. I’d recommend graphical Vim (gVim) or gedit with the GMate plugins. As far as command lines go, you’re totally set: every Linux distribution comes with at least one command line terminal application (and often several).
• Windows: Unfortunately, I can’t make any personal recommendations here, but you can do what I did: drop “rails windows” into Google to see what the latest thinking is on setting up a Rails development environment on Windows. Two combinations look especially promising: Vim for Windows with Console (recommended by Akita On Rails) or the E Text Editor with Console and Cygwin (recommended by Ben Kittrell). Rails Tutorial readers have suggested looking at Komodo Edit (cross-platform) and the Sublime Text editor (Windows only) as well. No matter which editor you choose, I recommend trying Cygwin, which provides the equivalent of a Unix terminal under Windows; most of the command-line examples in the book should work with minimum modification.

If you go with some flavor of Vim, be sure to tap into the thriving community of Vim-using Rails hackers. See especially the rails.vim enhancements and the NERD tree project drawer.

Figure 1.1: A text editor/command line development environment (TextMate/iTerm).

Browsers

Although there are many web browsers to choose from, the vast majority of Rails programmers use either Firefox or Safari when developing. I prefer Firefox, and the screenshots in Rails Tutorial will generally be of a Firefox browser. One of the big reasons I like Firefox is the amazing Firebug add-on, which lets you perform all sorts of magic, such as dynamically inspecting (and even editing) the HTML structure and CSS rules on any page. (Apparently Safari has some sort of equivalent, but I already know and love Firebug.)

I also recommend the Firefox HTML Validator, which automatically checks to make sure that your pages are valid HTML markup. (If you install Validator, you should go to the add-on Preferences to disable it for all pages, and then visit localhost and explicitly enable it for local pages. Otherwise it will try to validate every page you visit.) I have never been able to consistently keep a large project’s HTML validated without HTML Validator. Figure 1.2 shows both add-ons in action.

Figure 1.2: Firefox running with the Firebug and HTML Validator add-ons.

A note about tools

In the process of getting your development environment up and running, you may find that you spend a lot of time getting everything just right. The learning process for editors and IDEs is particularly long; you can spend weeks on TextMate or Vim tutorials alone. If you’re new to this game, I want to assure you that spending time learning tools is normal. Everyone goes through it. Sometimes it is frustrating, and it’s easy to get impatient when you have an awesome web app in your head and you just want to learn Rails already, but have to spend a week learning some weird ancient Unix editor just to get started. But a craftsman has to know his tools; in the end the reward is worth the effort.

1.2.2 Ruby, RubyGems, and Rails

Now it’s time to install Ruby and Rails. The canonical up-to-date source for this step is the Ruby on Rails download page. I’ll assume you can go there now; parts of this book can be read profitably offline, but not this part. I’ll just inject some of my own comments on the steps.

Install Ruby

It’s possible that your system already has Ruby; try running

$ ruby -v
ruby 1.8.7

to see the version number. The Rails team recommends Ruby 1.8.7, but 1.8.6 works for the time being. (Rails 3 will require Ruby 1.8.7 and will work best with Ruby 1.9.2.)

If you have to install Ruby, I strongly recommend doing a search for “install ruby OS X 10.5” (or whatever is appropriate for your system), since there are tons of options depending on your exact setup. Be warned that installing Ruby might take some trickery. If you run into any errors, just Google them.

Note: If you’re running Ubuntu Linux, at this point you might try these instructions for installing Rails on Karmic Koala rather than following the steps below.

Install RubyGems

RubyGems is a package manager for Ruby projects, and there are tons of great libraries (including Rails) available as Ruby packages, or gems. Installing RubyGems should be easy once you install Ruby. You should download RubyGems, extract/unzip it, and then go to the rubygems directory and run the setup program:

$ sudo ruby setup.rb

If you already have RubyGems installed, you might want to update your system to the latest version:

$ sudo gem update --system

Install Rails

This part should be really easy once you install RubyGems:

$ sudo gem install rails -v 2.3.5

Here the optional version flag -v just ensures that you get the exact version of Rails used in this tutorial.⁹ (Rails 3 is already in beta, and I will update the tutorial as soon as possible after its official release.)

To verify that this worked, run the following command:¹⁰

$ rails -v
Rails 2.3.5

1.2.3 The sample application

Virtually all Rails applications start the same way, with the rails command. This handy program creates a skeleton Rails application in a directory of your choice. To get started, make a directory for your Rails projects and then run the rails command to make the initial sample application:

$ mkdir rails_projects
$ cd rails_projects
$ rails sample_app
    create  
    create  app/controllers
    create  app/helpers
    create  app/models
    create  app/views/layouts
    create  config/environments
    create  config/initializers
    create  config/locales
    create  db
    create  doc
    create  lib
    create  lib/tasks
    create  log
    create  public/images
    create  public/javascripts
    create  public/stylesheets
    .
    .
    .

Notice how many files and directories the rails command creates. This standard directory and file structure (Figure 1.3) is one of the many advantages of Rails; it immediately gets you from zero to a functional (if minimal) application. Moreover, since the structure is common to all Rails apps, you can immediately get your bearings when looking at someone else’s code. We’ll learn about most of these files and all of these directories throughout the rest of this book.

Figure 1.3: The directory structure for a newly hatched Rails app.

1.2.4 Model-view-controller (MVC)

Even at this early stage, it’s helpful to get a high-level overview of how Rails applications work (Figure 1.4). You might have noticed that the standard Rails application structure (Figure 1.3) has an application directory called app/ with three subdirectories: models, views, and controllers. This is a hint that Rails follows the model-view-controller (MVC) architectural pattern, which enforces a separation between “domain logic” (also called “business logic”) from the input and presentation logic associated with a graphical user interface (GUI). In the case of web applications, the “domain logic” typically consists of data models for things like users, articles, and products, and the GUI is just a web page in a web browser.

When interacting with a Rails application, a browser sends a request, which is received by a web server and passed on to a Rails controller, which is in charge of what to do next. In some cases, the controller will immediately render a view, which is a template that gets converted to HTML and sent back to the browser. More commonly for dynamic sites, the controller interacts with a model, which is a Ruby object that represents an element of the site (such as a user) and is in charge of communicating with the database. After invoking the model, the controller then renders the view and returns the complete web page to the browser as HTML.

Figure 1.4: A schematic representation of the model-view-controller (MVC) architecture.

If this discussion seems a bit abstract right now, worry not; we’ll refer back to this section frequently as we fill in the sample application. We’ll first encounter controllers and views in Section 2.1.2, and we’ll introduce models in Section 5.1. We’ll first see an example of all three working together in Section 5.3.2.

1.2.5 script/server

Thanks to running rails in Listing 1.1, we already have an application we can run—but how? Happily, Rails comes with a command-line program, or script, that runs a local web server,¹¹ visible only from your development machine:¹²

$ cd sample_app/
$ script/server
=> Booting WEBrick
=> Rails 2.3.5 application starting on http://0.0.0.0:3000
=> Call with -d to detach
=> Ctrl-C to shutdown server

This tells us that the application is running on port number 3000¹³ at the address 0.0.0.0. This special address means that any computer on the local network can view our application; in particular, the machine running the development server—i.e., the local development machine—can view the application using the address localhost:3000.¹⁴ We can see the result of visiting http://localhost:3000/ in Figure 1.5.

Figure 1.5: The default Rails page (http://localhost:3000/).

Figure 1.6: The default Rails page (http://localhost:3000/) with an error.

Unfortunately, we’re not quite done; click on the link About your application’s environment and you’ll see your very first Rails error message¹⁵ (Figure 1.6). Looking in the web server log (Figure 1.7), we eventually see the incriminating lines:

  Status: 500 Internal Server Error
  no such file to load -- sqlite3

Figure 1.7: The incriminating lines in the server log.

This is a hint that we’re missing SQLite, the default database used by Rails. Even though we won’t need a database until Chapter 5, since Rails is opinionated software it still expects a database to be installed, so let’s take a few seconds to set it up. First, we need the SQLite gem for Ruby:

$ sudo gem install sqlite3-ruby -v 1.2.5
Building native extensions.  This could take a while...
.
.
.

If you’re running Linux you might get an error like this:

Building native extensions. This could take a while...
ERROR: Error installing sqlite3-ruby:
ERROR: Failed to build gem native extension.

In this case, install sqlite3 and libsqlite3-dev first:

$ sudo apt-get install sqlite3
$ sudo apt-get install libsqlite3-dev
$ sudo gem install sqlite3-ruby

Once you’ve installed SQLite, all that’s left is to set up the (empty) database using Rake (Box 1.2):

$ rake db:migrate

This does nothing but create an empty SQLite database for now,¹⁶ but we’ll see in Chapter 5 how to use rake db:migrate to create a database for the sample app’s users.

Now hit Ctrl-C to quit the server, and then restart it with script/server. You should see the result in Figure 1.8. Of course, we don’t need the default Rails page in the long run, but it’s nice to see it working for now. We’ll remove the default Rails page (and replace it with a custom home page) in Section 4.2.2.

Figure 1.8: The default Rails page (http://localhost:3000/) with the SQLite gem installed.

How would you know to install SQLite if I weren’t here to tell you? The best bet is usually to drop the error message into Google (maybe with the word rails thrown in) and keep searching until you find an answer. If that doesn’t work, emailing the Ruby on Rails mailing list is probably worth a try.

At this point, in principle you’re ready to start developing your Rails application, so I suppose you could skip ahead to Chapter 2. On the other hand, it would be irresponsible of me not to very strongly recommend that you follow the rest of the chapter—especially the next section on version control. A couple years ago maybe you could get away with writing a Rails tutorial book without integrating version control from the start, but not any more.

  $ ./configure && make && sudo make install

  $ rake -T db

  $ rake -T

1.3 Version control with Git

Now that we have a fresh and working Rails application, we’ll take a moment for a step that, while technically optional, would be viewed by many Rails developers as practically essential, namely, placing our application source code under version control.

Version control systems allow us to track changes to our project’s code, collaborate more easily, and roll back any inadvertent errors (such as accidentally deleting files). There are many options for version control, but the Rails community has largely standardized on Git, a version control system originally developed by Linus Torvalds to host the Linux kernel. Git is a large subject, and we’ll only be scratching the surface in this book, but there are many good free resources online; I especially recommend Pro Git by Scott Chacon (Apress, 2009).

Putting your source code under version control with Git is strongly recommended, not only because it’s nearly a universal practice in the Rails world, but also because it will allow you to share your code more easily (Section 1.3.4) and deploy your application right here in the first chapter (Section 1.4).

1.3.1 Installation and setup

The first step is to install Git if you don’t have it already. You should follow the instructions for your platform at the Installing Git section of Pro Git.

First-time system setup

After installing Git, you should perform a set of one-time setup steps. These are system setups, meaning you only have to do them once per computer:

$ git config --global user.name "Your Name"
$ git config --global user.email youremail@example.com

You can optionally set the editor Git will use for commit messages, and there’s a subtlety if you use a graphical editor such as TextMate, gVim, or MacVim; you need to use a flag to make sure that the editor stays attached to the shell instead of detaching immediately:¹⁷

$ git config --global core.editor "mate -w"

Replace "mate -w" with "gvim -f" for gVim or "mvim -f" for MacVim.

First-time repository setup

Now we come to some steps that are necessary each time you create a new repository (which only happens once in this book, but is likely to happen again some day). First navigate to the root directory of your sample app and initialize a new repository:

$ git init
Initialized empty Git repository in /Users/mhartl/rails_projects/sample_app/.git/

The next step is to add the project files to the repository. There’s a minor complication, though: by default Git tracks the changes of all the files, but there are some files we don’t want to track. For example, Rails creates log files to record the behavior of the application; these files change frequently, and we don’t want our version control system to have to update them constantly. Git has a simple mechanism to ignore such files: simply include a file called .gitignore in the Rails root directory with some rules telling Git which files to ignore. To ignore all log files, which live in the log/ directory, we use the asterisk wildcard and ignore all files that end in .log by including log/*.log in .gitignore (and so on for the other kinds of files we want Git to ignore). So, create a new .gitignore file using your favorite editor:¹⁸

$ mate .gitignore

Then fill the file with the contents of Listing 1.2.

log/*.log
tmp/*
tmp/**/*
doc/api
doc/app
db/*.sqlite3
*.swp
*~
.DS_Store

The lines in Listing 1.2 tell Git to ignore log files, Rails temp files, documentation files, SQLite databases, Vim and Emacs swap files, and (for you OS X users) the weird .DS_Store directories created by the Mac Finder application. Don’t worry if you wouldn’t have guessed these lines; Understanding just why each of these file types should be ignored comes from having practical experience with both Rails and Git. By using this .gitignore from the start, you can benefit immediately from the collective Git experience of the Rails community.

1.3.2 Adding and committing

Finally, we’ll add the files in your new Rails project to Git and then commit the results. You can add all the files (apart from those that match the ignore patterns in .gitignore) as follows:¹⁹

$ git add .

Here the dot ‘.’ represents the current directory, and Git is smart enough to add the files recursively, so it automatically includes all the subdirectories. This command adds the project files to a staging area, which contains pending changes to your project; you can see which files are in the staging area using the status command:²⁰

$ git status
# On branch master
#
# Initial commit
#
# Changes to be committed:
#   (use "git rm --cached <file>..." to unstage)
#
#       new file:   README
#       new file:   Rakefile
.
.
.

(The results are long, so I’ve used vertical dots to indicate omitted output.)

To tell Git you want to keep the changes, use the commit command:

$ git commit -m "Initial commit"
[master (root-commit) df0a62f] Initial commit
42 files changed, 8461 insertions(+), 0 deletions(-)
create mode 100644 README
create mode 100644 Rakefile
.
.
.

The -m flag lets you add a message for the commit; if you omit -m, Git will open the editor you set in Section 1.3.1 and have you enter the message there.

It is important to note that Git commits are local, recorded only on the machine on which the commits occur. This is in contrast to the popular open-source version control system called Subversion, in which a commit necessarily makes changes on a remote repository. Git divides a Subversion-style commit into its two logical pieces: a local recording of the changes (git commit) and a push of the changes up to a remote repository (git push). We’ll see an example of the push step in Section 1.3.5.

By the way, you can see a list of your commit messages using the log command:

$ git log
commit df0a62f3f091e53ffa799309b3e32c27b0b38eb4
Author: Michael Hartl <michael@michaelhartl.com>
Date:   Thu Oct 15 11:36:21 2009 -0700

  Initial commit

To exit git log, type q to quit.

1.3.3 What good does Git do you?

It’s probably not entirely clear at this point why putting your source control does you any good, so let me give just one example. (We’ll see many others in the chapters ahead.) Suppose you’ve made some accidental changes, such as (D’oh!) deleting the critical app/controllers/ directory:

$ ls app/controllers/
application_controller.rb
$ rm -rf app/controllers/
$ ls app/controllers/
ls: app/controllers/: No such file or directory

Here we’re using the Unix ls command to list the contents of the app/controllers/ directory and the rm command to remove it. The -rf flag means “recursive force”, which recursively removes all files, directories, subdirectories, and so on, without asking for explicit confirmation of each deletion.

Let’s check the status to see what’s up:

$ git status
# On branch master
# Changed but not updated:
#   (use "git add/rm <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       deleted:    app/controllers/application_controller.rb
#
no changes added to commit (use "git add" and/or "git commit -a")

We see here that a couple files have been deleted, but the changes have only been staged; they haven’t been committed yet. This means we can still undo the changes easily by having Git check out the previous commit with the checkout command (and a -f flag to force overwriting the current changes):

$ git checkout -f
$ git status
# On branch master
nothing to commit (working directory clean)
$ ls app/controllers/
application_controller.rb

The missing directory and file are back. That’s a relief!

1.3.4 GitHub

Now that you’ve put your project under version control with Git, it’s time to push your code up to GitHub, a social code site optimized for hosting and sharing Git repositories. Putting a copy of your Git repository at GitHub serves two purposes: it’s a full backup of your code (including the full history of commits), and it makes any future collaboration much easier. This step is optional, but being a GitHub member will open the door to participating in a wide variety of Ruby and Rails projects (GitHub has high adoption rates in the Ruby and Rails communities, and in fact is itself written in Rails).

Figure 1.9: The first GitHub page after account creation.

Figure 1.10: Creating the sample app repository at GitHub.

GitHub has a variety of paid plans, but for open source code their services are free, so sign up for a free GitHub account if you don’t have one already. (You might have to read about SSH keys first.) After signing up, you’ll see a page like the one in Figure 1.9. Click on create a repository and fill in the information as in Figure 1.10. After submitting the form, push up your sample application as follows:

$ git remote add origin git@github.com:<username>/sample_app.git
$ git push origin master

These commands tell Git that you want to add GitHub as the origin for your main (master) branch and then push your repository up to GitHub. Of course, you should replace <username> with your actual username. For example, the command I ran for the railstutorial user was

$ git remote add origin git@github.com:railstutorial/sample_app.git

The result is a page at GitHub for the sample application repository, with file browsing, full commit history, and lots of other goodies (Figure 1.11).

Figure 1.11: A GitHub repository page.

1.3.5 Branch, edit, commit, merge

If you’ve followed the steps in Section 1.3.4, you might notice that GitHub automatically shows the contents of the README file on the main repository page. In our case, since the project is a Rails application generated using the rails command, the README file is the one that comes with Rails (Figure 1.12). This isn’t very helpful, so in this section we’ll make our first edit by changing the README to describe our project rather than the Rails framework itself. In the process, we’ll see a first example of the branch, edit, commit, merge workflow that I recommend using with Git.

Figure 1.12: The initial (rather useless) README file for our project at GitHub.

Branch

Git is incredibly good at making branches, which are essentially copies of a repository where we can make (possibly experimental) changes without modifying the parent files. In most cases, the parent repository is the master branch, and we can create a new topic branch by using checkout with the -b flag:

$ git checkout -b modify-README
Switched to a new branch 'modify-README'
$ git branch
master
* modify-README

Here the second command, git branch, just lists all the local branches, and the asterisk * identifies which branch we’re currently on. Note that git checkout -b modify-README both creates a new branch and switches to it, as indicated by the asterisk in front of the modify-README branch.

The full value of branching only becomes clear when working on a project with multiple developers,²¹ but branches are helpful even for a single-developer tutorial such as this one. In particular, the master branch is insulated from any changes we make to the topic branch, so even if we really screw things up we can always abandon the changes by checking out the master branch and deleting the topic branch. We’ll see how to do this at the end of the section.

By the way, for a change as small as this one I wouldn’t normally bother with a new branch, but it’s never too early to start practicing good habits.

Edit

After creating the topic branch, we’ll edit it to make it a little more descriptive. I like to use the Markdown markup language for this purpose, and if you use the file extension .markdown then GitHub will automatically format it nicely for you. So, first we’ll use Git’s version of the Unix mv (“move”) command to change the name, and then fill it in with the contents of Listing 1.3:

$ git mv README README.markdown
$ mate README.markdown

# The Ruby on Rails Tutorial sample application

This is the sample application for the book 
[*Ruby on Rails Tutorial: Learn Rails by Example*](http://www.railstutorial.org/) 
by [Michael Hartl](http://www.michaelhartl.com/).

Commit

With the changes made, we can take a look at the status of our branch:

$ git status
# On branch modify-README
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       renamed:    README -> README.markdown
#
# Changed but not updated:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#       modified:   README.markdown
#

At this point, we could use git add . as in Section 1.3.2, but Git provides the -a flag as a shortcut for the (very common) case of committing all modifications to existing files (or files created using git mv, which don’t count as new files to Git):

$ git commit -a -m "Improved the README file"
2 files changed, 5 insertions(+), 243 deletions(-)
delete mode 100644 README
create mode 100644 README.markdown

Be careful about using the -a flag improperly; if you have added any new files to the project since the last commit, you still have tell Git about them using git add first.

Merge

Now that we’ve finished making our changes, we’re ready to merge the results back into our master branch:²²

$ git checkout master
Switched to branch 'master'
$ git merge modify-README
Updating 34f06b7..2c92bef
Fast forward
README          |  243 -------------------------------------------------------
README.markdown |    5 +
2 files changed, 5 insertions(+), 243 deletions(-)
delete mode 100644 README
create mode 100644 README.markdown

Note that the Git output frequently includes things like 34f06b7, which are related to Git’s internal representation of repositories. Your exact results will differ in these details, but otherwise should essentially match the output shown above.

After you’ve merged in the changes, you can tidy up your branches by deleting the topic branch using git branch -d if you’re done with it:

$ git branch -d modify-README
Deleted branch modify-README (was 2c92bef).

This step is optional, and in fact it’s quite common leave the topic branch intact. This way you can switch back and forth between the topic and master branches, merging in changes every time you reach a natural stopping point. We’ll see an example of how this works (including the use of git rebase) in Section sec:git_rebase.

As mentioned above, it’s also possible to abandon your topic branch changes, in this case with git branch -D:

# For illustration only; don't do this unless you mess up a branch
$ git checkout -b topic-branch
$ <really screw up the branch>
$ git add .
$ git commit -a -m "Screwed up"
$ git checkout master
$ git branch -D topic-branch

Unlike the -d flag, the -D flag will delete the branch even though we haven’t merged in the changes.

Push

Now that we’ve updated the README, we can push the changes up to GitHub to see the result:²³

$ git push

As promised, GitHub nicely formats the new file using Markdown (Figure 1.13).

Figure 1.13: The improved README file formatted with Markdown.

1.4 Deploying

There are several great options for deploying Rails applications, including Phusion Passenger, a module for the Apache and Nginx²⁴ web servers available on many shared hosts, full-service deployment companies such as Engine Yard, and cloud deployment services such as Engine Yard Cloud and Heroku, a hosted platform built specifically for deploying Rails and other Ruby web applications.²⁵

Because of the remarkable strides in Rails deployment, in this section we’ll already be deploying our still-empty Rails application. This step is optional, of course, but getting in the habit of early and rapid deploys means we’ll catch any deployment problems early in our development cycle. The alternative—deploying only after laborious effort sealed away in a development environment—often leads to terrible integration headaches when deployment time comes. Better to have our app out in the wild right from the start. (Though it won’t matter for the Rails Tutorial sample app, if you’re worried about accidentally making your app public too soon there are several options; see Section 1.4.4 for one.)

For instant Rails deployment, no service I know of even comes close to Heroku—as long as your source code is under version control with Git. (This is yet another reason to follow the Git setup steps in Section 1.3 if you haven’t already.) The rest of this section is dedicated to deploying our new sample application to Heroku.

1.4.1 Heroku setup

After signing up for a Heroku account, install the Heroku gem:

$ sudo gem install heroku

As with GitHub (Section 1.3.4), when using Heroku you will need to create SSH keys if you haven’t already, and then tell Heroku your public key so that you can use Git to push the sample application repository up to their servers:

$ heroku keys:add

Finally, use the heroku gem to create a place on the Heroku servers for the sample app to live (Listing 1.4).

$ heroku create
Created http://severe-fire-61.heroku.com/ | git@heroku.com:severe-fire-61.git
Git remote heroku added

Yes, that’s it. The heroku gem creates a new subdomain just for our application, available for immediate viewing. There’s nothing there yet, though, so let’s get busy deploying.

1.4.2 Heroku deployment, step one

To deploy to Heroku, the first step is to use Git to push the application to Heroku:

$ git push heroku master

1.4.3 Heroku deployment, step two

There is no step two! We’re already done (Figure 1.14).²⁶ To see your newly deployed application, you can visit the address that you saw when you ran heroku create (i.e., Listing 1.4, but with the address for your app, not the address for mine). You can also use a command provided by the heroku gem that automatically opens your browser with the right address:

$ heroku open

Figure 1.14: The nascent Rails Tutorial sample app running on Heroku.

Once you’ve deployed successfully, Heroku provides a beautiful interface for administering and configuring your application (Figure 1.15).

Figure 1.15: The beautiful interface at Heroku.

1.4.4 Heroku commands

There are tons of Heroku commands, and we’ll barely scratch the surface in this book. Let’s take a minute to show just one of them by renaming the application as follows:

$ heroku rename railstutorial

Don’t use this name yourself; it’s already taken by me! In fact, you probably shouldn’t bother with this step right now; using the default address supplied by Heroku is fine. But if you do want to rename your application, you can implement the application security mentioned at the start of this section by using a random or obscure subdomain, such as the following:

hwpcbmze.heroku.com
seyjhflo.heroku.com
jhyicevg.heroku.com

With a random subdomain like this, someone could visit your site only if you gave them the address. (By the way, as a preview of Ruby’s compact awesomeness, here’s the code I used to generate the random subdomains:

('a'..'z').to_a.shuffle[0..7].join

Pretty sweet.)

In addition to supporting subdomains, Heroku also supports custom domains. (In fact, the Ruby on Rails Tutorial site lives at Heroku; if you’re reading this book online, you’re looking at a Heroku-hosted site right now!) See the Heroku documentation for more information about custom domains and other Heroku topics.

1.5 Conclusion

We’ve come a long way in this chapter: installation, development environment setup, version control, and deployment. All that’s left is to, you know, actually start learning Rails. Let’s get to it!