This document describes how to swap out the official Rails 3.2 gems with Rails 3.2 LTS Archive . If you have installed Rails LTS before and want to update to a newer version, please see our update instructions.

Prerequisites

1. Subscribe to a Rails LTS plan Archive to receive your credentials. If you already have a paid subscription for another version of Rails LTS, you can use the same credentials for Rails 3.2 LTS at no additional cost.

2. Make sure your project satisfies the system requirement for Rails LTS. This involves upgrading to the latest official Rails 3.2 release.

3. Make sure that you have Bundler 1.10 or newer by running:

   Copy
   gem list | grep bundler
   

   This should show you a line like this:

   Copy
   bundler (1.10.6)
   

   If your version is lower than 1.10, you can update Bundler like this:

   Copy
   gem install bundler
   

   Please note that you need to have a compatible version of Bundler on all PCs that will be running your application (developer boxes, production servers, staging servers).

Installation

2. Open the Bundler configuration file (Gemfile) in your project's root directory and find this line:

   Copy
   gem 'rails'
   

   Replace that line with the following code:

   Copy
   source 'https://username:password@gems.railslts.com' do
     gem 'rails', '~> 3.2.22'
     gem 'actionmailer',     :require => false
     gem 'actionpack',       :require => false
     gem 'activemodel',      :require => false
     gem 'activerecord',     :require => false
     gem 'activeresource',   :require => false
     gem 'activesupport',    :require => false
     gem 'railties',         :require => false
     gem 'railslts-version', :require => false
   end
   

   Replace username and password with your personal credentials that you received after subscribing to Rails LTS.
   Make sure a colon (:) separates username and password. If you don't want these credentials in your Gemfile, you can also set them in an environment variable BUNDLE_GEMS__RAILSLTS__COM=username:password.

   Note that our repositories are available via SSL (https) only, http://... will not work.

3. Run Bundler to complete the installation:

   Copy
   bundle update rails
   

   If you're running ruby 1.8.7, you might get an error rake requires Ruby version >= 1.9.3. To resolve this, add the following line to your Gemfile:

   Copy
   gem 'rake', '< 11' 
   

4. Decide whether to enable optional security enhancements shipped with Rails LTS.

   In order to keep maximum compatibility to the official Ruby on Rails releases, Rails LTS disables all additional security features by default. We do however recommend the :hardened configuration, which includes improvements we believe to be reasonable defaults for increased security in most applications.

5. Confirm that you are running the latest version of Rails 3.2 LTS.

6. Follow your normal release process (run tests, push, deploy to staging, do smoke/whatever testing, deploy to production).

Congratulations! You successfully deployed your application using Rails LTS.

If you have chosen to subscribe to the Rails LTS Notification List when signing up, you will be notified whenever a new patch for Rails LTS becomes available.

Note on rack

Rails 3.2 depends on Rack version 1.4.x (which itself is not currently part of Rails LTS). It has some minor security issues on its own. We have a public fork on Github Archive that fixes these issues.

Note on rake

Rails 3.2 depends on Rake. Versions of rake < 12.3.3 have a security issue, and you cannot use rake 12 with Ruby 1.8.7. If you cannot upgrade to rake 12, we have a public fork on Github Archive that fixes the issue.

Note on mysql

If you have trouble using the mysql gem, you should try upgrading to mysql2 which is mostly a drop-in replacement. We suggest you use our fork on mysql2 which fixes some compilation issues on newer linux distros, by adding this to your Gemfile:

Copy
gem 'mysql2', git: 'https://github.com/makandra/mysql2', branch: '0.3.x-lts'

Also, in your database.yml, change the adapter to mysql2.

Breaking changes

By default, Rails LTS does not allow for strings to be used in polymorphic path helpers, e.g. url_for(['edit', @user]) is not allowed. Symbols are fine. You can opt out of this change