Section 3: Getting Started
Now that you know what Mongrel is all about, let’s start using it. You can install it with a single command and configure it with just one more. This section will walk you through the basic usage. We’ll dig into configurations in Section 4.
These examples assume you will be using Mongrel to serve a Rails application. If that’s not the case, and you’re using one of the other supported frameworks or plan to use Mongrel for your own custom application, you’ll still want to follow along and pay close attention. Even though Mongrel is framework-agnostic, most of the community currently uses it to run Rails applications, so the best-tested and most mature commands, handlers, filters, and plugins are all Rails-related. The other supported frameworks follow similar patterns to get Mongrel running. If you’re planning to extend Mongrel yourself (it’s easy!) see Section 6.
In our examples we also assume you are using a flavor of Unix. Mongrel is fully supported on Windows, so in most cases the examples will work without modification. Please see Section 3.3 and the Mongrel Web site (http://mongrel.rubyforge.org) for details on Win32-specific limitations or differences.
3.1. Installing Mongrel
Installing Mongrel is a snap. The only prerequisites are Ruby 1.8.4 or greater and RubyGems. If you don’t have these already, you’ll have a hard time running Ruby at all. For help with installing these on your system, please refer to the Ruby Web site (http://www.ruby-lang.org/en/), but in most cases you will want to install it.
You can install Mongrel in one step from your command line:
$ sudo gem install mongrel --include-dependencies
This will install the Mongrel gem and its dependencies, which are gem_plugin and, depending on your platform, either daemons or win32-service. If you’re not on Windows you’ll see Mongrel build the C extension during the gem install. Check the mailing list and Web site if you run into any issues, as it’s probably caused by a funky Ruby installation.
3.1.1. Mongrel Pre-Releases
If you are the risk-taking type (you are using Ruby after all, aren’t you?), then you can install and help test Pre-Release gems from Mongrel’s Pre-Release repository. Like most pre-release code, these gems typically include new features and/or bugfixes that need some platform testing, and overall they’re pretty stable. Ruby tends to introduce some interesting system-level differences, so testing on different platforms is extra important.
$ sudo gem install mongrel --source mongrel.rubyforge.org/releases
3.2. Using Mongrel
Now that you’ve installed Mongrel (and probably spent twice as long reading about it), you can take a look at what it gives you. Mongrel uses commands to do business with your application. You can see which commands come with Mongrel out of the box:
You’ll notice we’re calling the mongrel_rails executable. This is just a Ruby script that comes with Mongrel and includes the three basic commands you need to run a Rails application: start, stop and restart. Each command takes optional configuration parameters, which default to values that will be familiar to Rails developers and are similar to what you’ll see available in Rails’ script/server command. We’ll get into the details of how you can use these options in Section 4. For now, let’s just see what the options for the start command are.
We want to just get our vanilla Rails application running on Mongrel, so all we need to do is run:
You can see Mongrel loads Rails in the following way:
- Start the HttpServer, listening on port 3000
- Load the Rails-specific configuration values and plugins, then mount the Rails application at “/”
- Set up the signals
A common practice is to daemonize Mongrel so it runs in the background, and use that same terminal to tail the Rails development log. You can stop it using the stop command. Once you get Mongrel running, you can configure it to suit your particular needs.
3.2.1. Where Mongrel Puts Files
When running a Rails app, Mongrel will store its log and PID file in RAILS_ROOT/log by default. Mongrel’s log file mongrel.log stores Mongrel-related messages only. It is not intended to replace a request log (e.g., apache.log) or the Rails’ logs (e.g., development.log). See Section 7 for more info about enabling robust logging features.
3.3. Supported Platforms
Here you will find a description of the support and limitations of the various operating systems Mongrel runs on.
3.3.1. Unix
Mongrel runs on most flavors of Unix. Debian and SuSE have packages, and FreeBSD has ports. Other flavors of linux, OSX, OSX Server, and Solaris can install and run it. If your OS is not listed, you should try to install it anyway.
3.3.2. Windows
Mongrel is supported on Windows and with a few exceptions will work the same as it does on Unix. The major differences to note are:
Mongrel will not run daemonized (mongrel_start -d). You can run it as a service using the mongrel_service plugin.
Stop and restart commands are fickle.
Mongrel is not as fast as it is on Unix. This is because Ruby itself is much slower on Windows, but if you are familiar with the speed difference already, then Mongrel will be a huge step forward.
For details on Mongrel on Windows, see the Mongrel Web site (http://mongrel.rubyforge.org).
3.4. Supported Frameworks
If you are using one of the popular Ruby application frameworks, Mongrel may already support it. More developers are writing handlers to load their own frameworks, so if you use a framework or library that is not listed here, take a look at how handlers work in Section 6.
3.4.1. Ruby on Rails
Mongrel has excellent Ruby on Rails support. Most Mongrel users are Rails developers, so the best plugins, handlers, and documentation are all for Rails applications and deployments. See the Mongrel Web site (http://mongrel.rubyforge.org) for details on any limitations or caveats with Rails.
3.4.2. Iowa
Iowa is supported on Mongrel. See the Iowa Web site (http://enigo.com/projects/iowa/index.html) for details.
3.4.3. Camping
Camping, the micro-framework for Ruby Web applications, is supported (and is fed fresh salmon weekly) on Mongrel. See the Camping Web site (http://camping.rubyforge.org) for more details.
3.4.4. Og/Nitro
Nitro is supported on Mongrel. See the Nitro Web site (http://www.nitroproject.org/) for more details.