If you are using Ubuntu/Debian, you can build binary packages easily. Just do the following:

bash $ apt-get install git build-essential devscripts pbuilder cmake
bash $ git clone https://github.com/mikeowens/ModRuby.git
bash $ cd ModRuby
bash $ sudo /usr/lib/pbuilder/pbuilder-satisfydepends
bash $ fakeroot debian/rules clean
bash $ dpkg-build -b

And this will build the complete debian package. The resulting deb file(s) will be put in the above directory. For example, it produces the following on AMD 64:

bash $ ls ../
total 17M
drwxr-xr-x  3 owensmk owensmk 4.0K 2009-07-27 16:27 .
drwxr-xr-x  3 owensmk owensmk 4.0K 2009-07-28 14:35 ..
-rw-r--r--  1 owensmk owensmk 426K 2009-07-27 16:27 mod-ruby_3.0.0-1_amd64.build
-rw-r--r--  1 owensmk owensmk 1.9K 2009-07-27 16:27 mod-ruby_3.0.0-1_amd64.changes
-rw-r--r--  1 owensmk owensmk 207K 2009-07-27 16:26 mod-ruby_3.0.0-1_amd64.deb
-rw-r--r--  1 owensmk owensmk 1004 2009-07-27 16:27 mod-ruby_3.0.0-1.dsc
-rw-r--r--  1 owensmk owensmk  16M 2009-07-27 16:25 mod-ruby_3.0.0-1.tar.gz
-rw-r--r--  1 owensmk owensmk 337K 2009-07-27 16:26 mod-ruby-dev_3.0.0-1_amd64.deb
drwxr-xr-x 15 owensmk owensmk 4.0K 2009-07-28 14:15 mod-ruby

ModRuby requires the following dependencies:

Installing the prerequisites in FreeBSD is easy. You need to make sure you have FreeBSD ports installed however. That said, do the following as root:

bash $ pkg_add -r wget cmake flex apache2 sqlite3
bash $ cd /usr/ports/lang/ruby19 && make && make install
bash $ cd /usr/ports/devel/apr1 && make && make install

Then you can fetch the ModRuby source and build it normally, as described in Section 2.4, “Compiling”

On Max OS X you need to make sure the following are installed on your system:

If you have these, then everything should compile normally as described in the next section.

To compile from scratch, you need to get the Apache source. Download and extract it into apache/lib/src. On Debian you would do this as follows (from source root):

bash $ apt-get install apache2-prefork-dev

Now from within the source root, you can build the project:

bash $ cmake .
bash $ make

Copy mod_ruby.so to wherever your Apache modules directory is. Copy the debian/mod_ruby.load and mod_ruby.conf scripts to your module configuration directory (or put their contents into your main Apache configuration file). The copy the lib/core contents into your Ruby site install directory. That should do it.

To make development easier, you can run everything from the source distribution without having to install anything. That way, the changes you make as you develop can take affect immediately (sometimes requiring an Apache restart). You just have to symlink things to the right places.

bash $ ln -s /{path_to}/mod_ruby/example /etc/apache2/sites-available/
bash $ ln -s /{path_to}/mod_ruby/debian/mod_ruby.load /etc/apache2/mods-available/
bash $ ln -s /{path_to}/mod_ruby/debian/mod_ruby.conf /etc/apache2/mods-available/
bash $ ln -s /{path_to}/mod_ruby/apache/mod_mod_ruby.so.2.0.0 /usr/lib/apache2/modules/mod_mod_ruby.so
bash $ ln -s /{path_to}/mod_ruby/lib/core/mod_ruby.rb /usr/lib/ruby/{1.9.x}/
bash $ ln -s /{path_to}/mod_ruby/lib/core/mod_ruby /usr/lib/ruby/{1.9.x}/
bash $ ln -s /{path_to}/mod_ruby/example /var/www/mod_ruby-example
bash $ mkdir /usr/share/mod_ruby
bash $ ln -s /{path_to}/mod_ruby/lib/site /usr/share/mod_ruby/
bash $ ln -s /{path_to}/mod_ruby/lib/assets /usr/share/mod_ruby/

bash $ sudo a2enmod mod_ruby include
bash $ sudo a2ensite mod_ruby-example
bash $ sudo apache2ctl restart

bash $ ln -s /{path_to}/mod_ruby/config/mod_ruby.conf /usr/local/etc/apache2/Includes/
bash $ ln -s /{path_to}/mod_ruby/apache/mod_mod_ruby.so.2.0.0 /usr/local/libexec/apache22/mod_mod_ruby.so
bash $ ln -s /{path_to}/mod_ruby/lib/core/mod_ruby.rb /usr/local/lib/ruby/1.9/
bash $ ln -s /{path_to}/mod_ruby/lib/core/mod_ruby /usr/lib/ruby/1.9/
bash $ mkdir /var/www/
bash $ ln -s /{path_to}/mod_ruby/example /var/www/mod_ruby-example
bash $ mkdir /usr/share/mod_ruby
bash $ ln -s /{path_to}/mod_ruby/lib/site /usr/share/mod_ruby/
bash $ ln -s /{path_to}/mod_ruby/lib/assets /usr/share/mod_ruby/

Once the packages are installed, you need to enable mod_ruby and the example site as follows:

user@host $ sudo a2enmod mod_ruby
user@host $ sudo a2ensite mod_ruby-example

If you are running a stock Ubuntu Apache install, that’s it! Restart Apache to institute the changes using apache2ctl restart.

If you are not using the default Ubuntu Apache configuration and wish to configure it manually, you can modify the VHost configuration in mod_ruby-example.conf. The following as a minimal configuration to get the ModRuby module loaded and a simple site running:

LoadModule ruby_module /usr/lib/apache2/modules/mod_ruby.so

<IfModule ruby_module>
AddHandler ruby-handler .rsp
AddHandler ruby-handler .rhtml
AddHandler ruby-script-handler .rb

AddType text/html .rhtml .rb

RubyDefaultHandlerModule 'modruby'
RubyDefaultHandlerClass  'ModRuby::Handler'
RubyDefaultHandlerMethod 'handle'
</IfModule>

<VirtualHost *>
  ServerName modruby.example.org
  ServerAdmin webmaster@example.org
  DocumentRoot "/var/www/modruby-example/content"

  <Directory />
    Options Includes FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all
  </Directory>

</VirtualHost>

This tells Apache to load the mod_ruby.so module, and associate its handler to files with the suffixes .rb and .rhtml. The AddType directive defines associates these extension with text/html MIME types. You could rather associate these suffixes with system’s mime.types configuration file. In this case, you would simply modify the appropriate line of that file as follows:

text/html                   html htm rb rhtml

Be sure to restart Apache to make these changes take effect.

It is important that you use a fully-qualified domain name in your browser for the example site, otherwise cookies will not work properly. By default, the Apache configuration file for the example site uses the domain modruby.example.org. You need to add an entry to your /etc/hosts file as follows:

127.0.0.1       modruby.example.org

Now you can load the example site in your browser by going to http://modruby.example.org.

So that’s it. Everything is set up and working. Let’s move on to the interesting stuff.