Section 4: Configurations
4.3 Hit the Ground Running:Example Configurations
This section will show you how Mongrel can be configured for your development or deployment purposes. Mongrel will even generate configuration files for you. We will walk through each of the configuration options you saw earlier in detail.
4.1. Configuring Mongrel
Mongrel lets you configure and extend it through Yaml configuration files. You can write these by hand or pass configuration options into Mongrel, and it will generate one for you that you can later pass as a parameter.
In most cases, during development you won’t need to change the defaults. A common practice is to daemonize the Mongrel process, and when it’s necessary to run multiple Rails applications at once, specify the port, like so:
$ mongrel_rails -d -p 3001
This can become tedious if you have to type it frequently, so in keeping with the Don’t Repeat Yourself principle, Mongrel will take in a config file (see the -C parameter) in YAML format that sets these parameters for you. It even comes with a Generator parameter (see the -G parameter) that will generate this config file for you. You can tell Mongrel to put the file wherever you want, and include all the parameters you want to set. In this example we put it in Rails’ config directory.
The content of your config file should look like this:
We can now run Mongrel without having to type the config in every time:
$ mongrel_rails start -C config/bam.yml
4.1.1. Mongrel Scripts
If you want to mount a handler yourself, you can tell mongrel_rails to run a script file. It’s just a Ruby file, so you can require or include whatever code you need. However, don’t name the file with an .rb extension, because Rails will automatically load it if it is in the load path. We usually use.conf, though it doesn’t really matter.
Mongrel has a DirHandler that will list the contents of a directory, so we’ll mount the /drawing prefix to point to a directory on our system that we want to let users browse. You could mount a directory from anywhere in your file system. Let’s create a file drawings.conf with the following content:
uri ’/your_face’, :handler => DirHandler.new(’/Users/matt/examples/your_face’)
If you are using a config file (like we just used above), you’ll need to regenerate it with all the correct options, or you can just edit the existing config manually. Mongrel will give precedence to the parameter values in the config file over those in the command line. Since the -G parameter writes out all the parameters (even the empty ones, like :config_script in the above example), if you tried to run the following command, Mongrel would NOT load the script file.
$ mongrel_rails start -C config/bam.yml -S config/drawings.conf
Instead you should change the bam.yml file’s existing :config_script parameter to config/drawings.yml, and it will work like a charm.
4.2. Common Configurations
Now that you can see how easily Mongrel can be configured, let’s see what people are doing with it. Most of the configuration options will change from defaults because you want to run Mongrel in a cluster or in a production environment where you want to sit it behind a static HTTP server like Apache.
4.2.1. Mongrel Standalone
As a real HTTP server, Mongrel will work just fine as a front-facing Web server. After all, this is how it works in your development environment. Typically small Web sites will run just fine with a single Mongrel process. If you need SSL, you can run Mongrel behind a reverse-proxy like Pen. If you have request hogs like file uploads, you’ll probably want to run more than one Mongrel, which means you’ll need Mongrel Cluster and a reverse-proxy server.
4.2.2. A Pack of Mongrels (mongrel_cluster)
Depending on what kind of Web application you’re running and how much traffic you expect, you might want to have multiple Mongrel processes running in a cluster. If you are accustomed to running multiple FCGI processes, then you will want to run a cluster of Mongrel processes (a “cluster” in this case does not mean you need separate machines, just separate processes running on a single machine). To help figure out how many Mongrels you’ll need, you should read “How Many Mongrels” (http://rubyforge.org/pipermail/mongrel-users/2006-May/000200.html). If you need at least two, then you’ll want to run a cluster. You do this with the mongrel_cluster gem, written by Bradley Taylor from RailsMachine. Detailed instructions for setup and use are available on the Mongrel Web site (http://mongrel.rubyforge.org).
4.2.3. Mongrel Behind a “Static” Web Server
A common configuration for running a Rails application these days is to have a fast, compiled Web server like Apache field incoming requests, and have it reverse-proxy to a cluster of Mongrels. We call this a “static” server setup because the front-facing server will be good at serving static content like cached pages, CSS, Javascript, and images fast. Mongrel can serve static files quickly, but Ruby will never run as fast as a compiled binary, so use that to your advantage. The static Web server is usually configured with its mod_rewrite to only pass appropriate requests to the Mongrel cluster. If you are running a fully cached site, for example, this kind of setup will never even need to call Rails.
4.2.3.1. Static Server Options
Apache has been frowned upon by many Rails developers because of its flaky support for FastCGI, which was previously the least-horrible way to run a Rails application. FastCGI was pretty buggy, requiring scripts like script/spawner and script/reaper to kill and start FastCGI processes on the fly. Since Mongrel eliminates this problem, Apache has become a preferred option among those running Rails sites. We provide an example configuration with Apache in Section 5.
4.2.3.2. What about LightTPD?
When FastCGI was the best option out there, LightTPD (aka Lighty) was considered a top choice for a static server, sometimes preferred over Apache. At the moment Lighty’s mod_proxy module has a bug that will not properly connect to Mongrel processes if they go down and come back. This problem will be fixed in Lighty 1.5.0 with the mod_proxy_core module. Keep an eye out for Lighty announcements. Once this issue is resolved, Lighty will likely return to the shortlist.
4.3. Hit the Ground Running: Example Configurations
In this section we will cover two example configurations that will let you run a cluster of Mongrels behind a fast static Web server.
4.3.1. Apache Has Returned: Apache + mod_proxy_balancer + Mongrel
With the advent of Mongrel, Apache has risen from its ashes to once again become a preferred configuration option among those using Mongrel in production. The 2.2 version of Apache includes a new module called mod_proxy_balancer that will allow you to reverse-proxy, something that mod_proxy does not allow.
Apache is a jungle of configuration, so in this example we will use a simple approach to avoid confusion and minimize heartburn. If you already use Apache and have a preferred method for organizing your files, you should know how to adjust the following examples.
4.3.1.1. Install Apache 2.2
We’re going to download and compile Apache from source. If you have trouble getting Apache to run and compile, you will find many excellent resources online. We are going to include some common modules.
4.3.1.2. Set Up Your Mongrel Cluster Config
We’re going to use a simple cluster of two Mongrels, using mongrel_cluster. Here we simply run the cluster::configure command, then start the cluster.
4.3.1.3. Modify the Default Apache Config
We will add one line to the default Apache config http.conf (look in /usr/local/apache2/conf)
# Include an external config for our examples
Include /usr/local/apache2/conf/duck.conf
For the purpose of this example, we’re going to put all new configuration details in a single file called duck.conf in the default Apache configuration directory (/usr/local/apache2/conf/).
4.3.2. From Russia, with Love: Nginx[2]
One of the chieftains of the Rails deployment world, Ezra Zygmunowicz, found a Russian Web server that happens to be mature, feature-complete, and fast called Nginx (think “Engine X”). It has a low memory footprint, and the proxying is faster than Apache’s mod_proxy_balancer. He worked with some fellow developers and managed to get the configuration worked out. There is a wiki for Nginx English Documentation (http://wiki.codemongers.com/Nginx) to help guide you through any changes you’d like to make for your own setup. You’ll want to set up mongrel_cluster the same way we did in the previous section for Apache.
4.3.2.1. Install Nginx
Installing Nginx is straightforward. This will install it into /usr/local/nginx.
4.3.2.2. Set Up the Nginx Config
Now we can use a nice configuration that Ezra has honed to a sharp edge. In this example we are saving this in our Rails application’s config directory as nginx.conf.
You can test the configuration like so:
$ sudo /usr/local/sbin/nginx -t -c config/nginx.conf
Starting is the same as the testing command, without the -t option.
$ cd ~/code/examples/duck
$ sudo /usr/local/sbin/nginx -c config/nginx.conf
Stop using kill
$ kill -15 pid
4.3.2.3. Other Static Server Configurations
There are other Web server configurations and tools that will work well with Mongrel, including Pen, Pound, Litespeed, and others. You can find more details at the Mongrel Web site (http://mongrel.rubyforge.org).