HostingRails.com

Install and freeze your own RubyGems

This is a wiki article created by HostingRails users. Please login or signup to make edits.

Contents:

1. Overview and motivation
   
2. Create a .gems directory in your root and download/install some gems
   
3. Temporarily assign GEM_HOME and GEM_PATH
   
4. Unpack gems to your application's vendor folder
   

---

Overview and Motivation

    At the end of March 2006, when Rails 1.1.0 was released and many hosts performed the highly anticipated upgrade, thousands of Ruby on Rails applications across the Internet temporarily failed as a result of incompatibility errors. A small minority of developers, however, managed to avoid the downtime because they had smartly 'frozen' their gems, a process involving the unpacking of gems into the vendor folder of a Rails app.

    While HostingRails.com keeps the basic and most stable gems installed on their servers, it is HIGHLY recommended that everyone on a shared server freeze their gems - allowing total control over your production environment. Plus, you don't have to wait on someone to install a special gem you may need.

---

Create a .gems directory in your root and download/install some gems

SSH to root:

[~]# mkdir .gems  

This is where you'll download all the gems you want - including any version of Rails.

[~]# gem install gem_name -i ~/.gems 

Be sure to replace gem_name with the name of your gem.  It will automatically find the source of your gem and install it into your ~/.gems directory.  

---

Temporarily assign GEM_HOME and GEM_PATH

Better to keep these temporary and not use bash.  If you run into problems with rails not finding rake or any gems try logging into a new shell session.  

    Here we're essentially going to be telling the server where to grab the gems when we unpack them (next section) - so go ahead :

[~]# export GEM_HOME=$HOME/.gems
[~]# export GEM_PATH=/usr/local/lib/ruby/gems/1.8:$GEM_HOME

---

Note
If you type rails -v it will show the default rails version. If you want to obtain the rails version freezed in your application, place the given line in the .bashrc file of your home directory.
 

export GEM_HOME=$HOME/.gems

Now rails -v will show the exact version in which the application is developed.

Simple enough, let's move on...

---

Unpack gems to your application's vendor folder

To unpack/freeze gems to the vendor folder just:

[~]# cd vendor
[~/vendor]# gem unpack gem_name
[~/vendor]# gem unpack another_gem_name

To unpack a particular version of gem:

[~/vendor]# gem unpack gem_name -v=<version>

For eg:

[~/vendor]#gem unpack rails -v=1.2.3

(note you proably wouldn't use this example to freeze rails - see rake rails:freeze:gems below)

You get the idea.

That's it - Your Rails application will permanently run on these gems unless you delete them from the vendor folder.  

---

If you want to automatically freeze the version of Rails that is current on the server, you can logout and create a new shell session and:

[~]# cd rails_app
[~/rails_app]# rake rails:freeze:gems

If you're using Capistrano, you would typically have several releases inside your deploy directory. In the context of freezing the gems, you should not bother about that deploy directory. Rather, here, 'rails_app' means the folder on the server into which you checked out your app source code. After freezing the rails gem, you should commit the changes, which means those frozen gems will be the ones used across future releases.

If you want to freeze a specific version of Rails that is installed on the server but is NOT the most current, you can follow these steps:

[~]#cd ../vendor
[~]#gem unpack rails --VERSION=1.2.3
[~]#cd ..
[~]#rake rails:freeze:edge TAG=rel_1-2-3

NOTE: don't create a new shell session if you've downloaded a version of Rails into your ~/.gems folder that's different than the latest version on the server.  

---

IMPORTANT NOTE: certain gems need to be required manually (Though this is EXTREMELY rare after Rails 1.1.0). When doing so, be sure to include the path to their lib folder.

For example:

require �RedCloth/lib/RedCloth�

or for a specific version

require_gem 'rfacebook', '= 0.7.1'

---

Other ways, and useful links:

http://gemsonrails.rubyforge.org/ " " " " "