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

Prerequisites

1. Make sure your project satisfies the system requirement for Rails LTS. This involves upgrading to Rails 2.3.18.

2. The instructions below assume you are using Bundler to manage your gem dependencies.
   If your project isn't using Bundler, you can either upgrade to Bundler (recommended) or install Rails 2.3 LTS without Bundler.

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).
   We recommend to re-deploy your application after updating Bundler on a remote server.

Installation

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

   Copy
   gem 'rails'
   

   As a customer of a paid plan (Startup, Standard, Enterprise), replace that line with the following code:

   Copy
   source 'https://username:password@gems.railslts.com' do
     gem 'rails', '~>2.3.18'
     gem 'actionmailer',     :require => false
     gem 'actionpack',       :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.

   As a subscriber to the free Community edition, use the following code instead:

   Copy
   git 'https://github.com/makandra/rails.git', :branch => '2-3-lts' do
     gem 'rails', '~>2.3.18'
     gem 'actionmailer',     :require => false
     gem 'actionpack',       :require => false
     gem 'activerecord',     :require => false
     gem 'activeresource',   :require => false
     gem 'activesupport',    :require => false
     gem 'railties',         :require => false
     gem 'railslts-version', :require => false
   end
   

   You will not need a username or password for the Community edition.

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

2. Open config/environment.rb within your project directory and delete the following line:

   Copy
   RAILS_GEM_VERSION = '2.3.xx' unless defined? RAILS_GEM_VERSION
   

3. Run Bundler to complete the installation:

   Copy
   bundle update rails
   

   If the clone process aborts with an error like "The requested URL returned error: 403" or "Cannot get remote repository information" your Git version is probably too old. In such case you should upgrade your Git to version 1.7+ or you can install Rails LTS without Bundler.

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 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.