How do I use Ruby (and Rails) scripts?

This answer is customized for cohousing.org. (change domain name)

Our Web hosting service includes support for Ruby scripts. We also have Ruby on Rails preinstalled in FastCGI mode.

Our servers currently use Ruby 1.8.7 (with Debian security patches) and Rails 2.2.3, although you can choose your own Rails version. Note that the system-wide Rails version can change without notice, which could break your Rails application. Be sure to read the section below about choosing a Rails version to make sure your Rails app doesn't "bind" itself to a version that might not exist in the future.

On this page:

Using Ruby on Rails

Ruby on Rails is a powerful Web development environment that is quickly becoming popular. Most Rails applications should work by following the installation instructions that come with them.

We should mention that the Rails authors say it's difficult to get Rails working on "shared hosting" servers, like ours, compared to more expensive "dedicated servers". We agree with that — certain decisions the Rails developers have made mean that Rails is harder to setup on shared hosting than other scripting solutions like PHP. You may want to consider using a dedicated server from another company instead if you intend to use Rails heavily. (We don't currently offer dedicated servers.)

That said, one of the reasons for the popularity of Rails is that it's more than a programming language — it's a framework that allows you to create full-blown applications without writing as much code as you would need in, say, PHP. And it does work on our servers with decent performance in FastCGI mode.

While we unfortunately can't offer support for programming questions, the information below demonstrates how advanced users could create a new Rails application.

1. Connect to the server

Make a telnet or SSH connection, then change to the html directory: 

cd html

2. Create the new Rails application

Rails can automatically create a new application for you. We'll call this one railstest. Just type: 

rails railstest

This creates a directory named railstest to contain the application. Change into that directory: 

cd railstest

3. Edit "config/environment.rb"

Edit the "config/environment.rb" file using your favorite text editor, such as nano: 

nano config/environment.rb

Then add this line near the bottom of the file, just before the line that says "end": 

config.action_controller.relative_url_root = "/railstest/public"

This tells Rails the URL we'll be using to access this test site.

4. Put a ".htaccess" file in the "public" directory

The current version of Rails requires that you add a file named ".htaccess" to the "public" directory. The Rails documentation has information about this, but here's a complete, working example .htaccess file to get you started: 

AddHandler cgi-script .cgi
Options +FollowSymLinks +ExecCGI
RewriteEngine On
RewriteRule ^$ index.html [QSA]
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ dispatch.cgi [QSA,L]

After adding that file to the "public" directory, you should be able to go to http://www.cohousing.org/railstest/public/ in a Web browser and see a working default Rails application.

5. Create a new controller

To make your Rails application do something other than the default, create a new controller class. We'll call it "test". Make sure you're back in the "railstest" directory, then type: 

script/generate controller test

Among other things, this creates a new file at app/controllers/test_controller.rb.

6. Edit the controller class

Edit the controller file: 

nano app/controllers/test_controller.rb

The file initially contains no special code — it looks like this: 

class TestController < ApplicationController
end

You can add a few lines of code so it looks like this: 

class TestController < ApplicationController
    def hello
        render :text => "Hello World!"
    end
end

After saving that file, you should be able to view http://www.cohousing.org/railstest/public/test/hello in a Web browser.

With the information above, advanced users should be able to make sense of various Rails tutorials available on the Web. If you have questions about Rails, Google's Ruby on Rails group is a great place to start.

Choosing a Rails version

If you create your own new Rails application as described above, the app will "bind" itself to the current installed version of Ruby Gems using RAILS_GEM_VERSION in config/environment.rb. This is not what you want to happen on a server where you don't control the Rails installation: in particular, it means your application won't work when Rails is upgraded and the old version removed from the server (we keep old versions around as long as possible, but they will eventually need to be removed — we probably won't have Rails 1.0 still installed on all our servers five years from now).

Instead, you'll want to either "comment out" the RAILS_GEM_VERSION line in the config/environment.rb file (which will make your application always use the latest version of Rails available on the server: this is good for security, but can cause compatibility problems) or freeze the version of Rails used by your application (which gives you much more control over what's happening: you can use any version of Rails you wish).

We do upgrade Rails on a regular basis, so if you're concerned about compatibility, you'll probably want to choose your own version by freezing Rails. Doing so makes sure you aren't affected when we upgrade Rails on our servers (but means you'll need to keep track of when new versions of Rails are available so you can upgrade your application).

Putting a Rails application at the top level of your site

If you followed the above instructions, you'll notice that the Rails application needs a special URL. However, for a production application, you may not want to include "/railstest/public" as part of the URL.

You can use a separate .htaccess file at the top level of your Web site to fix this. First create the application as described above, then add these lines to the .htaccess file: 

RewriteEngine On

# prevent unauthorized access to files in the Rails directory
RewriteRule ^railstest/ - [forbidden,last]

# rewrite all other requests to Rails, unless a real matching
# file exists
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule (.*) railstest/public/$1 [QSA,last]

(Of course, change "railstest" to the actual name of the application you create.)

Using FastCGI with Rails

To speed up production Rails applications, we support FastCGI (and we use mod_fcgid as the Rails documentation recommends).

To enable FastCGI for Rails, first finish debugging your application (using FastCGI during debugging can cause confusing error messages).

Then, make sure the .htaccess file in the public directory of your Rails application contains a "RewriteRule" with "dispatch.fcgi", like this: 

RewriteRule ^(.*)$ dispatch.fcgi [QSA,L]

Using "dispatch.fcgi" instead of "dispatch.cgi" makes Rails run about 20 times faster.

Installing a plain Ruby script as a CGI

You can also use Ruby scripts without using Rails. There's nothing particularly special about using Ruby on our servers; if you download a script from elsewhere, it should work. Here are some tips:

1. Use the correct Ruby location

Make sure that the first line of your script points to the correct location of Ruby on our servers. You can use either of these paths: 

#!/usr/bin/ruby

#!/usr/bin/ruby1.8

2. Publish using text (ASCII) mode in your FTP program

Use your FTP program to upload the script file in text mode (sometimes called "ASCII mode"), not "binary" mode. Although text mode is the default for most FTP programs, your Ruby script may not work if it's accidentally uploaded using binary mode, so it's wise to check.

3. Put the script in the cgi-bin directory

When you upload the script, place it in a directory (folder) named cgi-bin using your FTP program. You will need to create this directory the first time you upload a script.

(Advanced users can make other directories run scripts like the "cgi-bin" directory; see our "Making Additional Directories Executable" page for more information.)

4. Make the script executable

Set the file permissions to make your script "executable" after uploading (you'll sometimes see this process referred to as making the script permissions "mode 0755" or "mode 0700").

Your FTP program documentation should explain how to create directories, transfer a file in ASCII mode, and change the permissions of a file you've uploaded.

5. Use the Script Checker

You can use our Script Checker to verify that the script was uploaded properly. The page also gives you a quick way to make the file executable if you prefer to do that on the Web, rather than using your FTP program.

6. Test the script

Once your Ruby script is installed, you'll access it as: 

http://www.cohousing.org/cgi-bin/script.rb

... where "script.rb" is the actual name of your Ruby script.