Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
476 lines (466 sloc) 37 KB
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Installing Rails &#183; RailsApps</title>
<link href="https://plus.google.com/u/0/b/117374718581973393536/117374718581973393536/posts/" rel="publisher" />
<link rel="stylesheet" href="http://railsapps.github.com/css/bootstrap.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="http://railsapps.github.com/css/screen.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="http://railsapps.github.com/css/gollum.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="http://railsapps.github.com/css/site.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="http://railsapps.github.com/css/syntax.css" type="text/css" charset="utf-8" />
<script src="http://code.jquery.com/jquery-1.6.min.js" type="text/javascript"></script>
<script src="http://railsapps.github.com/javascript/jquery.text_selection-1.0.0.min.js" type="text/javascript"></script>
<script src="http://railsapps.github.com/javascript/jquery.previewable_comment_form.js" type="text/javascript"></script>
<script src="http://railsapps.github.com/javascript/jquery.tabs.js" type="text/javascript"></script>
<script src="http://railsapps.github.com/javascript/gollum.js" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-5109366-14']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a href="http://railsapps.github.com/" class="brand">RailsApps Project</a>
<ul class="pull-right nav">
<li><a href="http://blog.railsapps.org/" class="twitter">Blog</a></li>
<li><a href="http://twitter.com/rails_apps" class="twitter">Twitter</a></li>
<li><a href="https://plus.google.com/117374718581973393536" class="google">Google +</a></li>
<li><a href="https://github.com/RailsApps" class="github">GitHub Repository</a></li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="content wikistyle gollum textile">
<h1>Installing Rails</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 20 July 2012</em></p>
<p>Installing Rails 3.2.6: Detailed (and current) instructions on how to install the latest release of Rails 3.2 with advice and troubleshooting tips.</p>
<p>Developers often install the newest version of Rails but neglect other components needed for Rails to run successfully. Rails is not just a Ruby gem, it is a complex and rapidly evolving ecosystem. A rapidly evolving ecosystem is not a bad thing. Rails is a powerful, widely used, and well-supported development platform. The constant changes bring increased utility. This guide explains how to install Rails with an emphasis on updating the complete development environment.</p>
<h3>RailsApps Examples and Tutorials</h3>
<p>This is a guide for developers using the example apps from the RailsApps repository. The RailsApps project provides open source apps and detailed tutorials for Rails developers. Next time you build an app, check the <a href="http://railsapps.github.com/">RailsApps</a> project to see if we can save you some time with a starter app.</p>
<p>If you’re new to Rails, see a list of recommended resources for <a href="http://railsapps.github.com/rails.html">Rails</a>.</p>
<p><a href="http://www.twitter.com/rails_apps"><img src="http://twitter-badges.s3.amazonaws.com/t_logo-a.png" title="Follow on Twitter" alt="Follow on Twitter"></a> Follow <a href="http://twitter.com/rails_apps">@rails_apps</a> on Twitter for updates and timely Rails tips.</p>
<h2>Shortcuts</h2>
<p>If you’ve already installed Ruby 1.9.3 and rvm (the Ruby Version Manager), skip ahead to the section <a href="#gems">Updating the Gems.</a></p>
<h4>Is Rails Already Installed?</h4>
<p>If you have an older version of Rails installed, it is possible to run <code>gem update rails</code> to get a newer version of Rails. <em>This is not recommended.</em> Instead, install rvm (the Ruby Version Manager) to create a new gemset and install the newest Rails version. Then you can switch between versions if necessary.</p>
<h2>What’s New</h2>
<p>If you have not been closely following the evolution of the Rails platform, here’s a summary of recent developments.</p>
<h4>Rails 3.2.6</h4>
<ul>
<li>Rails 3.2.6 was released June 12, 2012 with two important security fixes. See <a href="http://weblog.rubyonrails.org/2012/6/12/ann-rails-3-2-6-has-been-released/">Rails version 3.2.6 has been released</a>.</li>
<li>Rails 3.2.5 was released June 1, 2012 to correct a regression in Rails 3.2.4. See <a href="http://weblog.rubyonrails.org/2012/5/31/ann-rails-3-2-5-has-been-released/">Rails version 3.2.5 has been released</a>.</li>
<li>Rails 3.2.4 was released May 31, 2012 with minor bug fixes plus two important security fixes. See <a href="http://weblog.rubyonrails.org/2012/5/31/ann-rails-3-2-4-has-been-released/">Rails version 3.2.4 has been released</a>.</li>
<li>Rails 3.2.3 was released March 31, 2012 with improved protection from mass assignment vulnerabilities. See the <a href="http://weblog.rubyonrails.org/2012/3/30/ann-rails-3-2-3-has-been-released/">Rails 3.2.3 Announcement</a>.</li>
<li>Rails 3.2.2 was released March 1, 2012 with some minor bug fixes plus two important security fixes. See the <a href="http://weblog.rubyonrails.org/2012/3/1/ann-rails-3-2-2-has-been-released">Rails 3.2.2 Announcement</a>.</li>
<li>Rails 3.2.1 was released January 26, 2012 with some minor fixes. See <a href="https://gist.github.com/1685812">Ruby on Rails v3.2.1 Changelogs</a>.</li>
</ul><p><em>What You Need to Know:</em> Use the newest release of Rails because it is the most secure version.</p>
<h4>Rails 3.2</h4>
<p>Rails 3.2 was released January 20, 2012. Improvements include faster execution in development mode. The speed of resolving routes also improved. There are many tiny (but helpful) improvements throughout the framework. Rails 3.2 deprecates plugins (Rails 4.0 will remove them completely) so find Ruby gems to replace any plugins you may still be using. You can use Ruby 1.8.7 but consider moving to Ruby 1.9.3 (the current stable and recommended Ruby version) because Rails 4.0 will require Ruby 1.9.3. See the <a href="http://weblog.rubyonrails.org/2012/1/20/rails-3-2-0-faster-dev-mode-routing-explain-queries-tagged-logger-store">Rails 3.2.0 Announcement</a> and <a href="http://guides.rubyonrails.org/3_2_release_notes.html">Ruby on Rails 3.2 Release Notes</a> (with upgrade instructions). There’s a Railscast from Ryan Bates titiled <a href="http://railscasts.com/episodes/265-rails-3-1-overview">Upgrading to Rails 3.2</a>. Michael Hartl’s popular Ruby on Rails Tutorial book has been rewritten to cover Rails 3.2 with improved treatment of RSpec and Cucumber (<a href="http://ruby.railstutorial.org/ruby-on-rails-tutorial-book?version=3.2">Ruby on Rails Tutorial Version 3.2</a>). Finally, José Valim highlights his <a href="http://blog.plataformatec.com.br/2012/01/my-five-favorite-hidden-features-in-rails-3-2/">Five Favorite ‘Hidden’ features in Rails 3.2</a>.</p>
<p><em>What You Need to Know:</em> Upgrading from Rails 3.1 to Rails 3.2 is easy and yields faster performance (especially in development mode). You may run into issues if your application has routing complexities (the routing engine has changed). For an older application, upgrade to Rails 3.1 before upgrading to Rails 3.2.</p>
<h4>Rails 3.1</h4>
<p>Rails 3.1.0 was released August 31, 2011. Eight release candidates were released beginning May 21, 2011. Rails 3.1 introduced the <a href="http://www.youtube.com/watch?v=cGdCI2HhfAU">asset pipeline</a> which enables proper organization of <span class="caps">CSS</span> and JavaScript. Other features include <a href="http://railscasts.com/episodes/266-http-streaming"><span class="caps">HTTP</span> streaming</a>, default jQuery, reversible migrations, mountable engines, identity map, prepared statements, Rack::Cache on by default, forced <span class="caps">SSL</span>, role-based mass-assignment protection, has_secure_password, and custom serializers. See the <a href="http://weblog.rubyonrails.org/2011/5/22/rails-3-1-release-candidate">Rails 3.1 release candidate announcement</a> for details. There’s a <a href="http://railscasts.com/episodes/265-rails-3-1-overview">Rails 3.1 Overview</a> from Ryan Bates and a <a href="https://gist.github.com/958283">changelog</a> for all the details. Yehuda Katz explains <a href="http://yehudakatz.com/2011/06/14/what-the-hell-is-happening-to-rails/">What’s Up With All These Changes in Rails?</a>. The best overview of Rails 3.1 is Michael Hartl’s <a href="http://ruby.railstutorial.org/chapters/rails-3-1#top">chapter on Rails 3.1</a> in his Ruby on Rails Tutorial book.</p>
<p><em>What You Need to Know:</em> The greatest impact for developers moving from Rails 3.0 to 3.1 is the new location for <span class="caps">CSS</span> and JavaScript files and changes to the application layout file. See the official <a href="http://guides.rubyonrails.org/asset_pipeline.html">Rails 3.1 Asset Pipeline guide</a> for details.</p>
<h4>RubyGems</h4>
<p>RubyGems is a package management framework for Ruby. RubyGems installs as part of Ruby 1.9.3.</p>
<p>RubyGems 1.8.24 was released April 27, 2012 and increased the security used when RubyGems is talking to an https server (from the RailsApps blog: <a href="http://blog.railsapps.org/post/22057489814/rubygems-1-8-24-is-out">RubyGems 1.8.24 Is Out</a>).</p>
<p>If you think a gem may be failing because of an incompatibility with the newest RubyGems implementation, you can troubleshoot by rolling back to an earlier RubyGems system gem with <code>gem update --system 1.7.2</code> or <code>gem update --system 1.3.7</code>.</p>
<p><em>What You Need to Know:</em> Use <code>gem update --system</code> to upgrade to the <a href="https://rubygems.org/gems/rubygems-update">newest RubyGems system gem</a>.</p>
<h4>Rake</h4>
<p>Rake is the build tool for Ruby. Rake version 0.9.2 was released on June 5, 2011 and followed by Rake version 0.9.2.2 on October 22, 2011. Rake 0.9.2.2 installs as part of Ruby 1.9.3.</p>
<p>Many gems depend on Rake and conflicting dependencies can be a problem, especially since the release of Rake version 0.9.0 (May 20, 2011). For an explanation, see <a href="http://blog.davidchelimsky.net/2011/05/28/rake-09-and-gem-version-constraints/">David Chelimsky’s blog post</a>. If needed, you can specify an earlier version of Rake in your gemfile to force the use of an earlier Rake version.</p>
<p>You may have heard that it is good practice to use the command <code>bundle exec rake</code> instead of <code>rake</code> to force use of executables specified in your gemfile (or a dependency specified in the Gemfile.lock file) instead of other versions. For example, instead of <code>rake db:migrate</code>, run <code>bundle exec rake db:migrate</code>. If you’re using rvm, the <a href="https://rvm.io/">Ruby Version Manager</a>, as recommended below, you don’t need to use <code>bundle exec rake</code> instead of <code>rake</code> (rvm versions 1.11.0 and newer include the rubygems-bundler gem to handle this).</p>
<p><em>What You Need to Know:</em> Make sure you are using Rake 0.9.2.2 (or <a href="http://rubygems.org/gems/rake">newer</a>) with <code>gem update rake</code> before installing Rails 3.2.</p>
<h4>Bundler</h4>
<p><a href="http://gembundler.com/">Bundler</a> version 1.1.5 was released July 17, 2012. This version lets you specify a Ruby version (such as “1.9.3”) as well as a Ruby engine (such as “jruby”) in your Gemfile. You should install Bundler 1.1.5 if you plan to deploy to Heroku. Version 1.1.0 released March 7, 2012 improved speed significantly. See the <a href="https://github.com/carlhuda/bundler/blob/master/CHANGELOG.md"><span class="caps">CHANGELOG</span></a>.</p>
<p><em>What You Need to Know:</em> Use <code>gem update bundler</code> to upgrade to the <a href="https://rubygems.org/gems/bundler">newest Bundler gem</a>. Be sure to install Bundler 1.1.5 if you plan to deploy to Heroku.</p>
<h2 id="ruby">Installing Ruby 1.9.3 and rvm</h2>
<p>These instructions prepare your computer for installation of Rails.</p>
<h4>C language compiler</h4>
<p>You need a C language compiler to install Ruby and any gems that require native extensions. Default installations of Windows or Mac OS X don’t include gcc. Read on to prepare OS X or Windows for installing Ruby 1.9.3 and Rails. Linux operating systems include the necessary <a href="http://en.wikipedia.org/wiki/GNU_Compiler_Collection">gcc compiler</a>.</p>
<h4>Preparing a Mac</h4>
<p>The best guide for installation on a Mac is from Moncef Belyamani:</p>
<ul>
<li>
<a href="http://moncefbelyamani.com/how-to-install-xcode-homebrew-git-rvm-ruby-on-mac/">How to Install Xcode, Homebrew, Git, <span class="caps">RVM</span>, &amp; Ruby 1.9.3 on Snow Leopard &amp; Lion</a>.</li>
</ul><p>After following his instructions, skip ahead to the section <a href="#gems">Updating the Gems.</a></p>
<p>You can also install Ruby with pre-assembled packages:</p>
<ul>
<li><a href="http://railsinstaller.org/">RailsInstaller for OS X</a></li>
<li><a href="http://www.atmos.org/cinderella/">Cinderella</a></li>
<li><a href="http://bitnami.org/stack/rubystack">BitNami RubyStack</a></li>
</ul><p>Packages such as RailsInstaller, Cinderella or the BitNami RubyStack can be convenient but they often are not up-to-date. If you use a package, follow the instructions here to update rvm, Ruby, and Rails versions.</p>
<h4>Preparing Ubuntu Linux</h4>
<p>To install Ruby 1.9.3 on Ubuntu Linux, you have a choice of helpful guides:</p>
<ul>
<li>
<a href="http://installfest.railsbridge.org/installfest/ubuntu">Installing Rails on Ubuntu</a> from Railsbridge Installfest</li>
<li><a href="http://www.mirceagoia.com/downloads/Installation_Ruby-on-Rails_for_Ubuntu-Linux-Mint_www-mirceagoia-com.pdf">Mircea Goia’s tutorial</a></li>
<li><a href="https://github.com/joshfng/railsready">Joshua Frye’s Rails Ready setup script</a></li>
<li><a href="http://ryanbigg.com/2010/12/ubuntu-ruby-rvm-rails-and-you/">Ryan Bigg’s tutorial</a></li>
<li><a href="http://www.rubyinside.com/how-to-install-ruby-1-9-2-and-rails-3-0-on-ubuntu-10-10-4148.html">Peter Cooper’s screencast</a></li>
</ul><p>Since Rails 3.1, a JavaScript runtime has been needed for development on Ubuntu Linux (it is not needed for Mac OS X or Windows). For development on Linux Ubuntu, it is best to install the <a href="http://nodejs.org/">Node.js</a> server-side JavaScript environment:</p>
<pre>
$ sudo apt-get install nodejs
</pre>
<p>and set it in your <code>$PATH</code>.</p>
<p>If you don’t install Node.js, you’ll need to add this to the Gemfile for each Rails application you build:</p>
<pre>
gem 'therubyracer'
</pre>
<h4>Preparing Windows</h4>
<p><em>Before you start:</em> You can develop with Rails on Windows but be aware that most developers use Mac OS X or Ubuntu to develop Rails applications. Some gems requiring native extensions may be difficult to install on Windows. Developers (including <a href="http://thecodeshop.github.com/projects.html">The Code Shop</a>) are working to improve the speed of Ruby 1.9.3 on Windows (see a <a href="http://itreallymatters.net/post/12897174267/speedup-ruby-1-9-3-on-windows">benchmark</a>) as earlier versions were frustratingly slow.</p>
<p>To prepare Windows for installation of Ruby 1.9.3, start with <a href="http://railsinstaller.org/">RailsInstaller</a> from Engine Yard. RailsInstaller includes a “DevKit” which installs Ruby 1.9.3 and Rails 3.2 as well as gcc and other Unix build tools. See a guide to <a href="http://installfest.railsbridge.org/installfest/windows">Installing Rails on Windows</a> from Railsbridge Installfest for step-by-step instructions. On Windows, use <a href="http://github.com/vertiginous/pik">Pik</a> for services similar to rvm.</p>
<p>Another option on Windows is to install Ruby under <a href="http://www.cygwin.com/">Cygwin</a>. This gives you a Linux environment on Windows. Make sure you have the following Cygwin packages installed: git, readline, wget, patch, make, gcc, libsqlite3-devel, libxml2-devel, libxslt-devel. Then install <span class="caps">RVM</span> as described in the next section.</p>
<h4>
<span class="caps">RVM</span> and Alternatives</h4>
<p>You should install Ruby 1.9.3 on your computer using Wayne Seguin’s rvm, the <a href="https://rvm.io/">Ruby Version Manager</a>.</p>
<p>You’ll use rvm to manage your Rails versions and create a gemset specifically for each application you build. If you encounter conflicting gem dependencies, you can isolate the errors by creating different gemsets with rvm.</p>
<p>Sam Stephenson offers an alternative to rvm named <a href="https://github.com/sstephenson/rbenv">rbenv</a>. With rbenv, use Jamis Buck’s <a href="https://github.com/jamis">rbenv-gemset</a> to switch between gemsets. The utilities rbenv and rbenv-gemset are less “magic” than rvm and can be useful if you encounter issues with rvm. If you want to try rbenv, see notes for <a href="https://gist.github.com/1859298">installing Ruby on MacOS X 10.7.3 with XCode 4.3 and rbenv</a>.</p>
<p>Most Rails developers use rvm.</p>
<h4>Install or Update <span class="caps">RVM</span>
</h4>
<p>The rvm website explains <a href="https://rvm.io/rvm/install/">how to install rvm</a>.</p>
<p>If you have an older version of Ruby installed you don’t need to remove it. Any older Ruby and Rails versions will remain on your system and the rvm versions will take precedence. Rvm will leave your system version of Ruby untouched and use your shell to intercept any calls to Ruby.</p>
<p>If you already have rvm installed, update it to the latest version.</p>
<pre>
$ rvm get latest
$ rvm reload
$ rvm -v
</pre>
<h4>Which Ruby?</h4>
<p>Use <span class="caps">MRI</span>, <a href="http://en.wikipedia.org/wiki/Ruby_MRI">Matz’s Ruby Interpreter</a>, which is the reference implementation. It is the default when you install Ruby 1.9.3 using rvm.</p>
<p>There are other Ruby interpreters available:</p>
<ul>
<li><a href="http://www.rubyenterpriseedition.com/"><span class="caps">REE</span></a></li>
<li><a href="http://jruby.org/">JRuby</a></li>
<li><a href="http://rubini.us/">Rubinius</a></li>
<li><a href="http://maglev.github.com/">MagLev</a></li>
<li><a href="http://www.macruby.org/">MacRuby</a></li>
</ul><h4>Install Ruby 1.9.3</h4>
<p>Check for the current <a href="http://www.ruby-lang.org/en/downloads/">recommended version of Ruby</a>. Ruby 1.9.3 patch level 194 was current when this was written.</p>
<p>Ruby may already be installed on your computer (Mac OS X 10.7 comes with Ruby 1.8.7 preinstalled). You don’t need to remove an earlier version of Ruby if you install Ruby 1.9.3 using rvm.</p>
<p>Check for rvm installation notes for your operating system version:</p>
<pre>
$ rvm requirements
</pre>
<p>Check the requirements carefully. On Mac OS X 10.7 (Lion), you may need to install <a href="http://www.gnupg.org/related_software/libksba/index.en.html">libksba</a>. Install it with Homebrew, the package manager for OS X:</p>
<pre>
$ brew update
$ brew install libksba
</pre>
<p>Use rvm to install the recommended version of Ruby and make it your default:</p>
<pre>
$ rvm install ruby-1.9.3-p194
$ rvm --default use ruby-1.9.3-p194
$ ruby -v
</pre>
<p><em>Mac OS X 10.7.4 with XCode 4.3.2 or newer:</em> You should be able to install Ruby 1.9.3-p194 using rvm without any special command line options.</p>
<p><em>Earlier Mac OS X and XCode versions:</em> It’s advisable to upgrade to the newest Mac OS X and XCode versions.</p>
<h2 id="gems">Updating the Gems</h2>
<p>You can read more about how the building blocks of the Rails platform work together by reading the article <a href="http://railsapps.github.com/managing-rails-versions-gems.html">Managing Rails Versions and Gems</a>. It explains the relationships among Ruby, RubyGems, Rails, Rake, Bundler, and gemfiles and offers some advice.</p>
<h4>RubyGems</h4>
<p>The RubyGems package management system comes as part of a standard Ruby language installation.</p>
<p>What version of the RubyGems system is installed on your machine? Check with:</p>
<pre>
$ gem -v
</pre>
<p>Check for the <a href="https://rubygems.org/gems/rubygems-update">newest version of RubyGems</a>. It should be version 1.8.24 or newer.</p>
<p>Use <code>gem update --system</code> to upgrade the RubyGems system.</p>
<h4>RubyGems .gemrc File</h4>
<p>Check that your RubyGems <strong>.gemrc</strong> file is up to date:</p>
<pre>
$ cat ~/.gemrc
---
:backtrace: false
:benchmark: false
:bulk_threshold: 1000
:sources:
- https://rubygems.org
:update_sources: true
:verbose: true
install: --no-rdoc --no-ri
update: --no-rdoc --no-ri
</pre>
<p>If the file does not contain the RubyGems source <code>https://rubygems.org</code>, add it:</p>
<pre>
$ sudo gem source -a https://rubygems.org
</pre>
<p>If the file contains <code>gems.rubyforge.org</code> or <code>gemcutter.org</code>, remove them (they no longer exist):</p>
<pre>
$ sudo gem source -r http://gems.rubyforge.org
$ sudo gem source -r http://gemcutter.org
</pre>
<p>Generating the ri and RDoc documentation takes a long time when installing a gem. If you want to skip the documentation every time a gem gets installed, edit the <strong>.gemrc</strong> file to include:</p>
<pre>
install: --no-rdoc --no-ri
update: --no-rdoc --no-ri
</pre>
<h4>Update the Global Gemset</h4>
<p>Installing Ruby with rvm creates a default “global” gemset.</p>
<p>See what gems are installed in the “global” gemset:</p>
<pre>
$ rvm gemset use global
$ gem list
</pre>
<p>Two gems are installed with Ruby 1.9.3:</p>
<ul>
<li>bundler</li>
<li>rake</li>
</ul><p>Rvm installs two additional gems:</p>
<ul>
<li>rubygems-bundler</li>
<li>rvm</li>
</ul><h4>Update Rake</h4>
<p>Ruby 1.9.3 includes Rake version 0.9.2.2. Rake version 0.9.2.2 was current when this was written.</p>
<p>Update to the <a href="http://rubygems.org/gems/rake">newest version of Rake</a>.</p>
<pre>
$ rvm gemset use global
$ gem update rake
$ rake --version
</pre>
<h4>Update Rubygems-Bundler</h4>
<p>The newest version is needed if you intend to use the newest version of Bundler. Rubygems-Bundler version 1.0.3 was current when this was written.</p>
<p>Update to the <a href="http://rubygems.org/gems/rubygems-bundler">newest version of Rubygems-Bundler</a>.</p>
<pre>
$ rvm gemset use global
$ gem update rubygems-bundler
$ gem list
</pre>
<h4>Update Bundler</h4>
<p><a href="http://gembundler.com/">Bundler</a> version 1.1.5 was released July 17, 2012. You’ll need this version (or newer) if you plan to deploy to Heroku.</p>
<p>Update to the <a href="http://rubygems.org/gems/bundler">newest version of Bundler</a>.</p>
<pre>
$ rvm gemset use global
$ gem update bundler
$ bundle --version
</pre>
<h4>When Updates Don’t Work</h4>
<p>The command <code>gem update</code> is usually all you need. But if you need to upgrade to the pre-release version of a gem you may need to uninstall and then install. For example, to install a pre-release version of Bundler:</p>
<pre>
$ rvm gemset use global
$ gem uninstall -ax bundler
$ gem install bundler --pre
$ bundle --version
</pre>
<h4>Create a Rails 3.2 Gemset</h4>
<p>Create a default Rails 3.2.6 gemset. It’s advisable to create a new gemset for each application you build. But to get started, create a single new Rails 3.2.6 gemset as your default.</p>
<pre>
$ rvm ruby-1.9.3-p194@rails326 --create --default
</pre>
<p>To see a list of the gemsets you have installed:</p>
<pre>
$ rvm gemset list
</pre>
<h2>Install Rails 3.2.6</h2>
<p>Now you can install Rails 3.2.6.</p>
<p>Check for the <a href="http://rubygems.org/gems/rails">current version of Rails</a>.</p>
<p>If you want the most recent stable release:</p>
<pre>
$ gem install rails
$ rails -v
</pre>
<p>If you want the newest beta version or release candidate, you can install with <code>--pre</code>.</p>
<pre>
$ gem install rails --pre
$ rails -v
</pre>
<p>Or, as an alternative to <code>--pre</code>, for the newest version:</p>
<pre>
$ gem install rails -v "&gt;=3.2.6"
$ rails -v
</pre>
<p>Or you can get a specific version (just in case the newest version is broken).</p>
<p>For example, if you want the Rails 3.2.0 release, install with <code>--version=3.2.0</code>.</p>
<h4>Databases for Rails</h4>
<p>Rails uses the <a href="http://www.sqlite.org/">SQLite</a> database by default. Mac OS X come with SQLite pre-installed and there’s nothing to configure. On Windows, if you use a pre-assembled package to install Rails, it will likely have SQLite pre-installed.</p>
<p>On Ubuntu Linux, install SQLite with:</p>
<pre>
$ sudo apt-get install sqlite3 libsqlite3-dev
</pre>
<p>Though SQLite is adequate for development (and even some production applications), a new Rails application can be configured for other databases. The command <code>rails new myapp --database=</code> will show you a list of supported databases.</p>
<pre>
Supported for preconfiguration are: mysql, oracle, postgresql, sqlite3, frontbase, ibm_db, sqlserver, jdbcmysql, jdbcsqlite3, jdbcpostgresql, jdbc.
</pre>
<p>For example, to create a new Rails application to use <a href="http://www.postgresql.org/">PostgreSQL</a>:</p>
<pre>
$ rails new myapp --database=postgresql
</pre>
<p>The <code>--database=postgresql</code> parameter will add the pg database adapter gem to the Gemfile and create a suitable config/database.yml file. Here’s an article that explains how to install PostgreSQL on Mac OS X:</p>
<ul>
<li><a href="http://russbrooks.com/2010/11/25/install-postgresql-9-on-os-x">Install PostgreSQL 9 on OS X</a></li>
</ul><h2>Create a Test App</h2>
<p>You can create a test application:</p>
<pre>
$ rails new testapp
</pre>
<p>Switch to the application root directory to examine and test what you’ve built.</p>
<pre>
$ cd testapp
</pre>
<h4>Quick Test</h4>
<p>For a “smoke test” to see if everything runs, display a list of Rake tasks.</p>
<pre>
$ rake -T
</pre>
<p>There’s no need to run <code>bundle exec rake</code> instead of <code>rake</code> when you are using rvm (see <a href="https://rvm.io/integration/bundler/">rvm and bundler integration</a>).</p>
<h2>Create a Starter App</h2>
<p>The application you created with <code>rails new testapp</code> is very basic.</p>
<p>The <a href="http://railsapps.github.com/">RailsApps</a> project provides application templates for starter apps that provide many of the features you’ll need in an application. Most Rails developers have several favorite gems they use in any application. The RailsApps application templates will allow you to select and install from among the most commonly used gems.</p>
<p>Create a starter app using a popular application template:</p>
<pre>
$ rails new rails3-bootstrap-devise-cancan -m https://raw.github.com/RailsApps/rails3-application-templates/master/rails3-bootstrap-devise-cancan-template.rb -T
</pre>
<p>Use the <code>"rails new myapp -m"</code> command to generate a Rails web application from a template.</p>
<p>You can add the <code>-T</code> flags to skip Test::Unit if you are using RSpec for testing.</p>
<p>You can add the <code>-O</code> flags to skip Active Record if you are using a NoSQL datastore such as MongoDB.</p>
<p>Viist the <a href="http://github.com/RailsApps/rails3-bootstrap-devise-cancan/">GitHub repository</a> for the rails3-bootstrap-devise-cancan example application to learn how to configure and customize it.</p>
<h4>Other Choices for Starter Apps</h4>
<p>You can choose from other application templates for starter apps. Each one provides a set of useful, popular Rails gems integrated into a working application. Each example is known to work and can serve as your personal “reference implementation”. Each is an open source project. Dozens of developers use the apps, report problems as they arise, and propose solutions as GitHub issues. There is a tutorial for each one so there’s no mystery code.</p>
<table>
<tr>
<th>Author </th>
<th>Starter App </th>
<th>Tutorial </th>
<th>App Template </th>
<th>Comments </th>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails3-devise-rspec-cucumber">Devise, RSpec, Cucumber</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-devise-rspec-cucumber.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> Uses Devise for authentication with ActiveRecord and SQLite for a database </td>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails3-bootstrap-devise-cancan">Twitter Bootstrap, Devise, CanCan</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-bootstrap-devise-cancan.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> Devise for authentication, CanCan for authorization, Twitter Bootstrap for <span class="caps">CSS</span> </td>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails-prelaunch-signup">Startup Prelaunch Signup</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-prelaunch-signup.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> For a startup prelaunch signup site </td>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails3-mongoid-devise">Devise, Mongoid</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-mongoid-devise.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> Uses Devise for authentication with a MongoDB datastore </td>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails3-mongoid-omniauth">OmniAuth, Mongoid</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-mongoid-omniauth.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> OmniAuth for authentication with a MongoDB datastore </td>
</tr>
<tr>
<td> Daniel Kehoe </td>
<td> <a href="https://github.com/RailsApps/rails3-subdomains">Subdomains, Devise, Mongoid</a> </td>
<td> <a href="http://railsapps.github.com/tutorial-rails-subdomains.html">Tutorial</a> </td>
<td> <a href="https://github.com/RailsApps/rails3-application-templates">App Template</a> </td>
<td> Basecamp-style subdomains with Devise and MongoDB </td>
</tr>
</table><p>These starter apps were created with the <a href="https://github.com/RailsApps/rails_apps_composer">Rails Apps Composer</a> gem.</p>
<h2>Git</h2>
<p>You should set up your application with a source control repository using git. If you are developing with Rails, <a href="http://git-scm.com/">git</a> is an essential tool. Use git to roll back code changes as needed, when you are collaborating with others, and when you must deploy an app for hosting with a service such as Heroku. See the article:</p>
<ul>
<li><a href="http://railsapps.github.com/rails-git.html">Rails with Git and GitHub</a></li>
</ul><p>If git is installed on your computer and you’ve used a RailsApps application template to create your starter app, you’ll already have a git repository.</p>
<h2>Project-Specific Gemsets with .rvmrc</h2>
<p>After you’ve created an application, create an rvm gemset specifically for your application. Rvm recognizes an <strong>.rvmrc</strong> file in a directory and loads the gemset specified in the file. Here’s how to create a project-specific gemset for an application named “myapp” and create an <strong>.rvmrc</strong> file in the application’s root directory:</p>
<pre>
$ rvm --rvmrc --create ruby-1.9.3-p194@myapp
</pre>
<p>You’ll need to install Rails and the gems listed in your Gemfile into the new gemset by running:</p>
<pre>
$ gem install rails
$ bundle install
</pre>
<p>As an alternative, here’s how to create an <strong>.rvmrc</strong> file if you want to use an existing gemset named “ruby-1.9.3-p194@rails32”:</p>
<pre>
$ echo "rvm ruby-1.9.3-p194@rails32 --create" &gt; .rvmrc
</pre>
<p>Using an <strong>.rvmrc</strong> file means you’ll automatically be using the correct Rails and gem version when you run your application on your local machine.</p>
<h2>Deployment</h2>
<p>For easy deployment, use a “platform as a service” provider such as:</p>
<ul>
<li><a href="http://www.heroku.com/">Heroku</a></li>
<li><a href="http://www.cloudfoundry.com/">CloudFoundry</a></li>
<li><a href="http://www.engineyard.com/">EngineYard</a></li>
<li><a href="https://openshift.redhat.com/app/">OpenShift</a></li>
</ul><p>For deployment on Heroku, see the article:</p>
<ul>
<li><a href="http://railsapps.github.com/rails-heroku-tutorial.html">Rails 3.2 on Heroku</a></li>
</ul><h2>Troubleshooting</h2>
<h4>Problems with “Segmentation Fault”</h4>
<p>If you get a “segfault” when you try <code>rails new</code>, try removing and reinstalling rvm. If you are not using the current version of Mac OS X, you should upgrade before installing rvm.</p>
<h4>Problems with “Gem::RemoteFetcher::FetchError: SSL_connect”</h4>
<p>The newest Ruby and RubyGems versions (starting with Ruby 1.9.3p194 and RubyGems 1.8.23) require verification of server <span class="caps">SSL</span> certificates when Ruby makes an Internet connection via https. If you run <code>rails new</code> and get an error “Gem::RemoteFetcher::FetchError: SSL_connect returned=1 errno=0 state=SSLv3 read server certificate” see this article suggesting solutions: <a href="http://railsapps.github.com/openssl-certificate-verify-failed.html">OpenSSL errors and Rails</a>.</p>
<h4>Problems with “Certificate Verify Failed”</h4>
<p>Are you getting an error “OpenSSL certificate verify failed” when you try to generate a new Rails app from an application template? See this article suggesting solutions: <a href="http://railsapps.github.com/openssl-certificate-verify-failed.html">OpenSSL errors and Rails</a>.</p>
<h4>Problems with Rake</h4>
<p>If you see:</p>
<pre>
The template ... could not be loaded.
Error: You have already activated rake 0.8.7, but your Gemfile requires rake 0.9.x.
Consider using bundle exec.
</pre>
<p>If you are using Ruby 1.9.2, you must update the standard Ruby installation from Rake 0.8.7 to Rake 0.9.2 (or <a href="http://rubygems.org/gems/rake">newer</a>) before using the application templates to generate a new Rails app. It’s advisable to update to Ruby 1.9.3 which will provide Rake 0.9.2.</p>
<h2>Where to Get Help</h2>
<p>Your best source for help with problems is <a href="http://stackoverflow.com/questions/tagged/ruby-on-rails-3">Stack Overflow</a>. Your issue may have been encountered and addressed by others.</p>
<p>You can also try <a href="http://www.railshotline.com/">Rails Hotline</a>, a free telephone hotline for Rails help staffed by volunteers.</p>
</div><!-- class="content" -->
<div class="comments">
<div class="content wikistyle gollum">
<h2>Comments and Issues</h2>
</div>
<p>Is this helpful? Please add a comment below. Your encouragement fuels the project.</p>
<p>Did you find an error? Or couldn't get something to work? For the example apps and tutorials, please create a GitHub issue in the repository for the example app. Creating a GitHub issue is the best way to make sure a problem is investigated and fixed.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
<div class="footer row">
<div class="span4">
<h3>Credits</h3>
<p><a href="http://danielkehoe.com/">Daniel Kehoe</a> initiated the <a href="http://railsapps.github.com/">RailsApps Project</a>. Thanks to all the users and contributors.</p>
</div>
<div class="span4">
<h3>Wiki</h3>
<p>Corrections? Additions? You can edit this page <a href="https://github.com/RailsApps/railsapps.github.com/wiki/_pages">on the wiki</a>.</p>
</div>
<div class="span4">
<h3>Last edit</h3>
<p>by <b>Daniel Kehoe</b>, 2012-07-20 23:08:42</p>
</div>
</div>
</div>
</body>
</html>