Table of Contents
ModRuby is an Apache module that embeds a Ruby virtual machine, enabling
you to use Ruby natively within Apache. It does what you would expect from a
traditional language module like mod_perl or
mod_python, but also a little bit more. That is, it gives you
more than just a “faster-than-CGI” environment and native access to Apache’s C
API from within Ruby. It also provides you with three intuitive ways of using
Ruby within Apache, based on your needs/preferences. These are in the form of
different Apache handlers. One handler is designed to run straight-up Ruby (like
in a Fast CGI environment). Another one processes embedded Ruby (RHTML)
files. The third (and most useful) is a user-defined handler that lets you
specify how to handle requests — pointing to the Ruby class/method of your
choosing to handle incoming requests. Using this handler, you can implement or
integrate external web frameworks.
Basically, ModRuby’s main purpose is to enable you to easily use Ruby within Apache in almost any way you could want, giving you full access to both Ruby and Apache via the Apache C API, module framework, and configuration system.
This documentation covers all aspects of ModRuby and is targeted to web developers who have a working knowledge of Ruby, Apache and know their way around a Linux/UNIX environment. It addresses administration (compiling/building, installing, configuring), development (both general web development and extending/customizing ModRuby) as well as design (goals, features and limitations).
The general approach is illustration by examples that progressively build on each other. All examples are actual working example from a test site that accompanies the documentation. This allows you to both read the code and watch it work. Using this approach, the documentation starts with the most basic, rudimentary concepts and leads into advanced topics.
As mentioned already, to get the most out of this documentation, you should have basic experience with Ruby, Apache, and a UNIX-like operating system such as FreeBSD or Linux.
This documentation does not cover how to install, configure, or use Apache unless you are using FreeBSD or Debian-based distribution (Devuan or Ubuntu). While ModRuby compiles and runs on other Linux distributions, NetBSD, OpenBSD and other UNIX-like systems, they are not covered specifically in this documentation. Regardless, installation and configuration is still quite easy across the board: you can set up a working system running the ModRuby example site with only a few commands.
Building from source requires a basic knowledge of the following:
Compiling and installing software. You will need to know how to compile packages from source using the standard UNIX build tools (tar, make, etc.). All of the support libraries for ModRuby must be downloaded, compiled, and installed.
Installing Apache. You will either have to have an existing Apache system running, or you will need to know how to get a basic Apache system up and running.
Module Installation. You will need to know where to install Apache modules on your system, specifically the location (directory) in which they are located.
Ruby. You will have to have a working version of Ruby 1.9.x+ on your system along with the Ruby header files.
The following are some some good resources for learning Ruby, and Apache:
The Ruby Programming Language. This is a very good book that is not only a good introduction to Ruby, but covers advanced topics and good programming practices.
The Apache Server Documentation. The Apache user documentation is both comprehensive and well written.
The Apache Modules Book. This is an advanced book for people who want to develop Apache modules. While the Apache documentation for end users is well written, documentation for developers is slim to none. This book is an indespensible guide for anyone who want to develop with Apache.
The Apache Module Development Documentation. Straight from the source.
The following typographical conventions are used in the online documentation:
System commands and programs such as grep, awk and dmesg are shown in this manner.
Literal expressions such as select * from user; are
shown in this manner.
Files and paths such as /etc/shadow and
/var/log/apache are shown in this manner.
Variable names in code such as $pwd and
$SHELL are shown in this manner.
Constants such as PATH_MAX are shown in this
manner.
Functions such as strlen are shown in this
manner.
Function parameters such as len
are shown in this manner.
Classes such as StringIO are shown in this
manner.
Class methods such as StringIO::read() are
shown in this manner.
XML markup such as XInclude is shown in this manner.
Links such as Chapter 3, Programming are shown in this manner.
The DocBook markup system is described in the printed book DocBook - The Definitive Guide [TDG1999]. There is an up-to-date local HTML copy at CERN [TDG2002]