Section 4.1. Configuring Mongrel

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.

---

[Pages 22 - 23]

Option	Config File Param	Description	Default
-e, environment ENV	:environment	Configures your Rails environment to what you need.	development
-d, daemonize	:daemon	If given (no options) then Mongrel will run in the background (not on Windows).	false
-p, port PORT	:port	Port to bind to when listening for connections.	3000
-a, address ADDR	:host	Address to bind to when listening for connections.	0.0.0.0 (every interface)
-l, log	:log_file	Where to dump log messages in daemon mode. Use an absolute path (not on Windows).	$PWD/log/mongrel.log
-P, pid	:pid_file	Where to write the PID file so start and stop commands know the Process ID. Use absolute paths.	$PWD/log/mongrel.pid
-n, num-procs INT	:num_processors	Maximum number of concurrent processing threads before Mongrel starts denying connections and trying to kill old threads.	1,024
-t, timeout TIME	:timeout	Time to pause between accepting clients. Used as a throttle mechanism.	0
-m, mime PATH	:mime_map	A YAML file that maps from file extensions to MIME types for static files. It's important that if you are using page caching or you have a different language setting like UTF8, then you have to configure this. Read more below.	not set
-c, chdir PATH	:chdir	Directory to change prior to starting Mongrel. cwd means "change working directory."	. (current directory)
-r, root PATH	:root	Document root where Mongrel should serve files from. If you are putting Mongrel under a different base URI, and you want it to serve files out of a different directory, then you need to set this.	public
-B, debug	:debug	Turns on a debugging mode, which traces objects, threads, files request parameters, and logs accesses, writing them to log/ mongrel_debug. This option makes Mongrel very slow.	false
-C, config FILE	:config_script	Takes whatever options you've set for Mongrel, plus the current defaults, and then writes them to a YAML file suitable for use with the -C option.	N/A
-S, script PATH	N/A	A special Ruby file that is run after Rails is configured to give you the ability to change the configuration with Ruby. This would be where you can load customer Mongrel handlers, extra libraries, or set up additional Ruby code. This option is fairly advanced, so use with caution.	not set
-G, generate PATH	N/A	Takes whatever options you've set for Mongrel, plus the current defaults, and then writes them to a YAML file suitable for use with the -C option.	not set
user USER	:user	Changes to this user if you are starting Mongrel as root and need extra security.	not set
group GROUP	:group	Must be combined with user as it changes the group as well.	not set
prefix URI	:prefix	The URI prefix for all generated URLs from your Rails application, must start with / and not end in /.	not set

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.

$ mongrel_rails start -d -p 3001 -G config/bam.yml ** Writing config to config/bam.yml ** Finished. Re-run without -G and WITH -C using your new config file.

The content of your config file should look like this:

--- :config_script: :debug: false :pid_file: log/mongrel.pid :num_processors: 1024 :docroot: public :user: :host: 0.0.0.0 :mime_map: :prefix: :group: :port: '3001' :daemon: true :cwd: /Users/matt/examples/bam :config_file: :includes: - mongrel :environment: development :timeout: 0 :log_file: log/mongrel.log

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.