Since the original tech preview release of FastCGI last year, we've been seeing a lot of requests for getting Ruby on Rails running with our FastCGI.  Theoretically, since the FastCGI component uses a standard protocol to support FastCGI-enabled applications, this shouldnt be an issue - but, in practice, this is very far from reality.  After factoring in setup problems, configuration, and variations in runtime behavior / protocol deviations, every single FastCGI application we've looked at has required quite some effort to support properly.

So, for FastCGI Tech Preview 2, I spent some time researching what it would take to enable Ruby on Rails, resulting in "experimental" RoR support in the TP2 release.  It is "experimental" because we did only limited testing, and given our lack of experience with Ruby its very hard to tell whether a real Ruby application will work as expected at this point.

I am confident that the experience can be improved significantly with community testing, and any necessary fixes to both the FastCGI component and Ruby.  I am looking forward to any feedback/bug reports that can help us get there - please feel free to leave comments on the blog, or post to IIS FastCGI forums.

Without further ado, these are the 10 steps get RoR working with FastCGI TP2:

Read this first - platform limitations

The steps below can be used to install Ruby on Rails on a Windows Server 2003 operating system, and configure it to work with the Microsoft IIS FastCGI technical preview 2 release.  Unfortunately Windows XP does not support the required configuration necessary for the FastCGI TP2 component to run RoR, and Windows Vista's version of FastCGI TP2 uses a different mechanism to run RoR (post on how to get that working in the near future).  The initial steps to install Ruby on Rails described here are similar for Windows XP, Windows Server 2003, and Windows Vista.

FastCGI TP2 Installation

1) Download and install FastCGI Technical Preview 2

Download the appropriate TP2 package for your OS, which in this case means either the IIS6 32bit FastCGI or IIS6 64bit FastCGI.  You can read more about this on my previous blog post.  Here is the synopsis of the install steps:

• Download the appropriate FastCGI TP2 package
• Unzip it to a local directory on your machine
• Use fcgisetup.js to install it:

  > cscript fcgisetup.js /install

This will install FastCGI on your machine, and enable us to configure it manually later.  We will not be using the automatic configuration support in the installer because we will need some customizations specific for RoR later.

Ruby Installation

2) Download and install Ruby(latest tested version was 1.8.5-22 Final)

3) Install Rails Open a new command line window, and run the gem installer:

> gem install rails --include-dependencies

4) Download and install RoR IIS extensions

The RubyForIIS.exe package contains the FastCGI client library on which RoR is dependent in order to use its dispatch.fcgi script.  During the installation, the installer will ask for the location of the Ruby directory - be sure to point the installer to the directory where you installed Ruby, for example, f:Ruby.

During the installation, you may get an error "Unable to write to file ...msvcp7.dll"  - press ignore to continue.  If you want to double-check that everything went well, open a command prompt, and type in: > irb <enter> > require 'fcgi' <enter> If you see "true", then its installed correctly.  If not, re-install and give the right path this time.

5) Fix the Ruby CGI script

This is a workaround for an IIS-specific behavior in Ruby that actually does not work with IIS.  Feel the irony.  Quick background - NPH, or No Parsed Headers, is a CGI mode of operation in which the CGI program produces a complete response including the http headers, instead of supplying the headers to the web server and letting the webserver manage them.  Most of today's webservers, including IIS, manage response headers on their own - for example, IIS enables a number of web server features that modify response headers in order to enable functionality like caching, compression, etc.  Ruby's CGI script assumes that IIS always requires NPH, and this of course completely breaks the FastCGI component because it does not even support NPH   The funnier thing is that even IIS CGI does not require NPH, and doesnt use it by default.  This is one of the things that totally makes sense to be fixed in a future Rails release to provide a more cohesive experience on IIS.

Open <f:Ruby>libruby1.8cgi.rb, and edit line 559 of the script to remove:                                        "OR /IIS/n.match(env_table([‘SERVER_SOFTWARE’])".

You can also download the already fixed script  if you dont want to do surgery yourself.

Creating a sample Ruby application

At this point, if you followed the instructions above, you should have Ruby on Rails installed and ready to go on your Windows machine.  Now, we will create a sample RoR application to use with the FastCGI component:

6) Create a sample Ruby app

Open a command line window, change to a base directory where you want to create your app, and type:

> rails myapp > cd myapp > ruby scriptgenerate controller test

This creates the myapp RoR application, and then generates a sample "test" RoR controller.  Edit this controller to display some useful stuff by opening appcontrollertest_controller.rb, and pasting the following into it:

class TestController < ApplicationController   def index     render :text=>"The index action"   end   def about     render :text=>"Testing app v1.0"   end end

Configure the RoR application with IIS and FastCGI

We are almost there, so don't panic.  I promise to not exceed 10 steps

7) Create a website for your RoR app

Create a new website on port 81 pointing to the public directory of your rails app, which for me was f:rubymyapppublic:

8) Create the RoR FastCGI handler mapping

Because RoR uses SEF (search engine friendly) urls, it needs to use a wildcard mapping to forward all requests to FastCGI / RoR mapping - unlike PHP, which requires .PHP files to be mapped to the PHP / FastCGI mapping.  Because of reliance on wildcard mapping, FastCGI can only be used to run RoR on Windows Server 2003 (since Windows XP's version of IIS doesnt support wildcard mappings).  This is the sole reason why this walkthrough is limited to W2k3.

To create the mapping, click the "Configuration" button on the website, and "Insert" the handler mapping to "fcgiext.dll" FastCGI ISAPI handler (which you installed in step 1):

Be sure to clear the "Verify that file exists" checkbox.

9) Create the FastCGI application pool for your website

If you remember in step 1, when we installed the FastCGI TP2 package, we didnt use the installer's support for registering a FastCGI program.  This is because RoR requires some custom settings in the FastCGI config file that the installer doesnt surface.

Because of this, we will manually create this configuration by editing the %windir%system32inetsrvfcgiext.ini configuration file (NOTE that for 64bit installations, you will also need to make the same edits to %windir%syswow64inetsrvfcgiext.ini):

[Types] *:85358523=Ruby

[Ruby] ExePath=F:Rubybinruby.exe Arguments=F:Rubymyapppublicdispatch.fcgi IgnoreDirectories=0 IgnoreExistingFiles=1 QueueLength=1000 MaxInstances=4 InstanceTimeout=30 InstanceMaxRequests=200

- Replace the ExePath with the path to your ruby.exe. - Replace the Arguments with the path the dispatch.fcgi script inside your application. - Replace the "85358523" number above with your site id.  You could omit this if you are not planning to run multiple Ruby applications on your machine. You can get it from the logging properties of your website:

This configuration shows the several new configuration / behavior features we needed to add to TP2 in order to get Ruby working.  This includes support for specifying arguments to the FastCGI executable (per pool), the ability to scope FastCGI extension mappings to a particular site id (so that you can map the same extension to different pools for different sites), and the ability to execute as a wildcard mapping that only processes files that do not exist on disk.  More information on all of these later.

10) You are done!

At this point, you should be up and running.  Hit up http://localhost:81/test/about, and you should get the RoR response from our test controller.

Please try this out with your real RoR apps, and let me know how it went / what issues you hit.  Your feedback will be instrumental in getting to a production quality FastCGI support for RoR in a future release.  Feel free to leave comments on this blog, or hit us up at the FastCGI forums on www.iis.net.

Finally, I want to thank Brian Hogan, without whose invaluable help in explaining the workings of Ruby On Rails and how to get it installed on Windows, I wouldn't have been able to get even this far.  He has a book on Ruby on Rails coming out soon, and I hope that we can get IIS FastCGI and RoR to play well enough together to be mentioned in it