Getting Started
The first thing that one needs to understand before using Iowa is how it interoperates with the web server and how one gets Iowa to handle a web page request.
Iowa applications generally run as persistent processes which are seperate from the web server. They need not even run on the same machine as the web server. So, there has to be some mechanism through which the web server process can pass the request to the Iowa application and then receive the response back that it will in return send on to the requesting browser. Iowa currently provides four mechanisms for working with this architecture.
The only exception to this architecture occurs when using Iowa with WEBrick. Since WEBrick provides a pure ruby webserver, Iowa can be embedded right into WEBrick. The combination provides for a single webserver that can directly handle all of an applications needs, from Iowa generated content to static content such as images or static HTML pages to CGI generated content. Using Iowa with WEBrick is also by far the easiest arrangement to get setup and running because there is no need to deal with any external configurations or files. Take a look in your Iowa distribution at the examples/webrick directory for an example of an application setup to use WEBrick. You should be able to simply run it, and it should work.
The simplest of the other mechanisms is to use a simple CGI adapter process to connect the web server to the Iowa application. A template for an adapter program is provided in the Iowa distribution as iowa.cgi. This template can be copied and edited to create an actual adapter, which will look very similar to this:
#!/usr/local/bin/rubyrequire 'iowa/Client'iowa_socket = 'localhost:9987'client = Iowa::Client.new(iowa_socket)client.handle_request
When invoked as a CGI program, this little script will create an instance of Iowa::Request, a class that looks and acts a lot like a mod_ruby Apache::Request class. This object encapsulates the request. The handle_request() method then takes care of all of the details around sending the request to the Iowa application process and then receiving and outputting the response from the application process.
The second method is to run the Iowa Application directly as a FastCGI process. To do this you change the:
require 'iowa'
within the application's startup script to:
require 'iowa_fcgi'
Then configure your web server as with any other FCGI program, with the exception that it can not be setup as a dynamic FCGI server. With the current architecture there must only be a single persistent process.
The third method also involves using FastCGI. In this case, however, the FCGI program just acts as a proxy between the web server and the Iowa application. It is included in the distribution as iowa_fcgi_proxy.rb. You will need to make a copy of it and edit the copy so that it knows what socket the Iowa application is running on, then just setup your web server as normal to use the Iowa proxy application. The proxy can run as a dynamic FCGI server.
The fourth method is to use the mod_ruby handler provided with the distribution. This handler is named mod_iowa.rb. That file actually contains two handlers, a translation handler and a response handler. The response handler can be used by itself to redirect single URLs to the appropriate Iowa application, or it can be used with the translation handler in order to let an Iowa application selectively handle a large swath or URLs while allowing Apache to keep responsibility for any that the Iowa application is not prepared to handle. For example, all of a site's .html "files" could actually be mapped to Iowa content objects while allowing any images or other files on the site to fall through the mod_iowa handler to be handled in the normal way by Apache.
To use the handler you need to have mod_ruby load it. Place the following in your Apache configuration file:
RubyRequire 'apache/mod_iowa'
Then, to tell Apache to use the handler, in an appropriate location you would place something like this:
<Location /myapplication>RubySetEnv IOWA_SOCKET "localhost:9987"SetHandler ruby-objectRubyHandler Apache::Iowa</Location>
If you want to make use of the translation handler and the mapfile, perhaps to place most of a site's content generation into the hands of an Iowa application, you would use something like this:
<Location />RubySetEnv IOWA_SOCKET "localhost:9987"RubySetEnv MAP_FILE "/var/www/mysite.com/mapfile.cnf"SetHandler ruby-objectRubyHandler Apache::IowaRubyTransHandler Apache::Iowa</Location>
This configuration would cause every request for the site to get passed through the translation handler. If the URL being requested matches one listed in the file specified in the MAP_FILE environment variable, the the Iowa application will be allowed to handle the request. Otherwise the handler declines to handle the request and Apache handles it normally. More detailed information on using Iowa to handle broad mappings of URLs will be covered in a later chapter.
