[DRE-commits] r1280 - packages-wip/mongrel/trunk/debian

[Filipe Lautert]

Author: filipe-guest
Date: 2007-02-06 18:50:15 +0100 (Tue, 06 Feb 2007)
New Revision: 1280

Modified:
   packages-wip/mongrel/trunk/debian/mongrel_rails.1
Log:
* Finally writing documentation.



Modified: packages-wip/mongrel/trunk/debian/mongrel_rails.1
===================================================================
--- packages-wip/mongrel/trunk/debian/mongrel_rails.1	2007-01-30 04:26:34 UTC (rev 1279)
+++ packages-wip/mongrel/trunk/debian/mongrel_rails.1	2007-02-06 17:50:15 UTC (rev 1280)
@@ -1,19 +1,126 @@
-.TH mongrel_rails 1 "2006-11-17" "Mongrel Rails"
+.TH MONGREL_RAILS 1 "2006-11-17" "Mongrel Rails"
 .SH NAME
-mongrel_rails \- Do something
+mongrel_rails \- Ruby Application Server
 .
 .SH SYNOPSIS
+.B mongrel_rails 
+.RI <command> 
+[options]
 .
 .SH DESCRIPTION
+Mongrel is a fast HTTP library and server for Ruby that is intended for hosting Ruby web applications of any kind using plain HTTP rather than FastCGI or SCGI. It is framework agnostic and already supports Ruby On Rails, Og+Nitro, Camping, and IOWA frameworks.
+.PP
+Mongrel turns out to be really nice for development since it serves files much faster than WEBrick. For example, to use it in development with Ruby on Rails is easy as this:
+.PP
+$ mongrel_rails start
+.PP
+Mongrel is a self-documenting program by giving you an extensive help listing for each command. If you think that this manual page is outdated, simply running 
+.B mongrel_rails start -h
+will print out each possible option and what it does.
+.PP
+These options are also used in the 
+.B -C config_file
+option to set them without using the command line. The name used in the config file is slightly different since it's a YAML file. .br
+Mongrel has a -G (generate) feature that will take any command line options you give it, generate the YAML file to replicate those options, and then exit. For example, you could make a config file like this:
+.PP
+.B mongrel_rails start -G mongrel_8080.yml -e production -p 8080
+.PP
+And it'll write all the options possible to mongrel_8080.yml, but with your specific changed for environment (-e production) and port (-p 8080). When you run a configuration file with -C, don't pass other options. Rather than have complex rules about whether a configuration file or command line option wins, mongrel_rails just uses configuration file and defaults, or command line options and defaults. Basically don't mix, it won't work.
 .
-This manpage is not yet written. Go away, pretend you didn't see this.
+.SH COMMANDS
+The following commands are supported by mongrel:
 .PP
-Y'know, there is a reason why this package is only uploaded to 
-.I experimental...
-No, really - I'll work on this. Promise.
+\fBstart\fP 				Starts the server.
+.br
+\fBstop\fP					Stops the server. Mongrel is very conservative when it shuts down, so it will wait up to 60 seconds for threads to exit before it finally exits gracefully.
+.br
+\fBstop --force [--wait n]\fP	Stops the server. This sends mongrel a kill -9 and then you must delete the .pid file. If the wait parameter is specified, mongrel will wait n seconds before it sends the kill sign.
+.br
+\fBrestart\fP				Restarts the server.
 .
+.SH OPTIONS
+Mongrel is extensible configurable, and it has the following configuration options (the name to use in configuration file is in parenthesis after the option name):
+.PP
+\fB-e, --environment ENV\fP (:environment)	Configures your Rails environment to what you need.
+.br
+.I									* Default: development
+.br
+\fB-d, --daemonize\fP (:daemon)			If given (no options) then Mongrel will run in the background.
+.br
+.I									* Default: false
+.br
+\fB-p, --port PORT\fP (:port)				Port to bind to when listening for connections.
+.br
+.I									* Default: 3000
+.br
+\fB-a, --address ADDR\fP (:host)			Address to bind to when listening for connections.
+.br
+.I									* Default: 0.0.0.0 (every interface)
+.br
+\fB-l, --log PATH\fP (:log_file)			Where to dump log messages in daemon mode - use an absolute path.
+.br
+.I									* Default: $PWD/log/mongrel.log
+.br
+\fB-P, --pid PATH\fP (:pid_file)			Where to write the PID file so start and stop commands know the Process ID - use absolute paths.
+.br
+.I									* Default: $PWD/log/mongrel.pid
+.br
+\fB-n,--num-procs PROCS\fP (:num_processors)	Maximum number of concurrent processing threads before Mongrel starts denying connections and trying to kill old threads.
+.br
+.I									* Default: 1024
+.br
+\fB-t, --timeout SEC\fP (:timeout)			Time to pause between accepting clients. Used as a throttle mechanism.
+.br
+.I									* Default: 0
+.br
+\fB-m, --mime PATH\fP (:mime_map)			A YAML file that lists additional MIME types.
+.br
+.I									* Default: not set.
+.br
+\fB-c, --chdir PATH\fP (:cwd)				Directory to change to prior to starting Mongrel.
+.br
+.I									* Default: . (current directory)
+.br
+\fB-r, --root PATH\fP (:docroot)			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.
+.br
+.I									* Default: public
+.br
+\fB-B, --debug\fP (: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.
+.br
+.I									* Default: false
+.br
+\fB-C, --config PATH\fP (NONE)				Specifies a configuration YAML file that sets options - use absolute paths.
+.br
+.I									* Default: no default
+.br
+\fB-S, --script PATH\fP (:config_script)		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 setup additional Ruby code. This option is fairly advanced so use with caution.
+.br
+.I									* Default: not set
+.br
+\fB-G, --generate PATH\fP (NONE)			Takes whatever options set for Mongrel, and the current defaults, and then writes them to a YAML file suitable for use with the -C option.
+.br
+.I									* Default: not set
+.br	
+\fB--prefix URI\fP						A URI to mount your Rails application at rather than the default /. This URI is stripped off all requests by Rails (not Mongrel) so it cannot end in /.
+.br
+.I									* Default: not set
+.br
+\fB--user USER\fP						Must have --group too. The user to change to right after creating the listening socket. Use this if you have to bind Mongrel to a low port like port 80, but don't want Mongrel to run as root.
+.br
+.I									* Default: not set
+.br
+\fB--group GROUP\fP						Must have --user too. The group to change to right after creating the listening socket.
+.br
+.I									* Default: not set
+.br
+\fB-h, --help\fP						Show help message
+.br
+\fB--version\fP							Show mongrel version
+.
+.SH SEE ALSO
+.BR pen (1), mongrel (1)
+.
 .SH AUTHOR
-Zed a. Shaw <zedshaw at zedshaw.com>
-.PP
-This manual page was written for the Debian system by Gunnar Wolf <gwolf at debian.org>. 
+Mongrel (http://mongrel.rubyforge.org/) was written by Zed Shaw.
+This manual page was written for the Debian system by Filipe Lautert <filipe at icewall.org>. 
 It might be used and redistributed under the same terms as the program itself.