From: Andy Grundman Date: Fri, 9 Dec 2005 18:37:24 +0000 (+0000) Subject: FastCGI doc updates X-Git-Tag: 5.7099_04~780 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Runtime.git;a=commitdiff_plain;h=d7d72ad91cc796713d84c256e08ef9b1a6473542 FastCGI doc updates --- diff --git a/Changes b/Changes index 60e4eac..68e48e1 100644 --- a/Changes +++ b/Changes @@ -11,6 +11,7 @@ This file documents the revision history for Perl extension Catalyst. - Added REDIRECT_URL support for applications running behind a RewriteRule in Apache. (Carl Franks) - Fixed FastCGI engine under win32. (Carl Franks) + - FastCGI doc updates (Bill Moseley) - Bugfix for $c->model and friends (defined). 5.61 2005-12-02 00:00:00 diff --git a/lib/Catalyst/Engine/FastCGI.pm b/lib/Catalyst/Engine/FastCGI.pm index af96ca3..56eec8b 100644 --- a/lib/Catalyst/Engine/FastCGI.pm +++ b/lib/Catalyst/Engine/FastCGI.pm @@ -161,38 +161,132 @@ __END__ =head1 WEB SERVER CONFIGURATIONS -=head2 Apache 1.x, 2.x +=head2 Standalone FastCGI Server + +In server mode the application runs as a standalone server and accepts +connections from a web server. The application can be on the same machine as +the web server, on a remote machine, or even on multiple remote machines. +Advantages of this method include running the Catalyst application as a +different user than the web server, and the ability to set up a scalable +server farm. -Apache requires the mod_fastcgi module. The following config will let Apache -control the running of your FastCGI processes. +To start your application in server mode, install the FCGI::ProcManager +module and then use the included fastcgi.pl script. - # Launch the FastCGI processes - FastCgiIpcDir /tmp - FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -idle-timeout 300 -processes 5 + $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 - - ScriptAlias / /var/www/MyApp/script/myapp_fastcgi.pl/ - +Command line options for fastcgi.pl include: + + -d -daemon Daemonize the server. + -p -pidfile Write a pidfile with the pid of the process manager. + -l -listen Listen on a socket path, hostname:port, or :port. + -n -nproc The number of processes started to handle requests. -You can also tell Apache to connect to an external FastCGI server: +See below for the specific web server configurations for using the external +server. - # Start the external server (requires FCGI::ProcManager) - $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 +=head2 Apache 1.x, 2.x + +Apache requires the mod_fastcgi module. The same module supports both +Apache 1 and 2. + +There are three ways to run your application under FastCGI on Apache: server, +static, and dynamic. + +=head3 Standalone server mode + + FastCgiExternalServer /tmp/myapp -socket /tmp/myapp.socket + Alias /myapp/ /tmp/myapp/ + + # Or, run at the root + Alias / /tmp/myapp/ + + # Optionally, rewrite the path when accessed without a trailing slash + RewriteRule ^/myapp$ myapp/ [R] + +The FastCgiExternalServer directive tells Apache that when serving /tmp/myapp +to use the FastCGI application listenting on the socket /tmp/mapp.socket. +Note that /tmp/myapp does not need to exist -- it's a virtual file name. + +It's likely that Apache is not configured to serve files in /tmp, so the +Alias directive maps the url path /myapp/ to the (virtual) file that runs the +FastCGI application. The trailing slashes are important as their use will +correctly set the PATH_INFO environment variable used by Catalyst to +determine the request path. If you would like to be able to access your app +without a trailing slash (http://server/myapp), you can use the above +RewriteRule directive. + +=head3 Static mode + +The term 'static' is misleading, but in static mode Apache uses its own +FastCGI Process Manager to start the application processes. This happens at +Apache startup time. In this case you do not run your application's +fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the +FastCGI script to run your application. + + FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3 + Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/ - # Note that the path used in FastCgiExternalServer can be any path - FastCgiIpcDir /tmp - FastCgiExternalServer /tmp/myapp_fastcgi.pl -socket /tmp/myapp.socket +FastCgiServer tells Apache to start three processes of your application at +startup. The Alias command maps a path to the FastCGI application. Again, +the trailing slashes are important. - - ScriptAlias / /tmp/myapp_fastcgi.pl/ +=head3 Dynamic mode + +In FastCGI dynamic mode, Apache will run your application on demand, +typically by requesting a file with a specific extension (e.g. .fcgi). ISPs +often use this type of setup to provide FastCGI support to many customers. + +In this mode it is often enough to place or link your *_fastcgi.pl script in +your cgi-bin directory with the extension of .fcgi. In dynamic mode Apache +must be able to run your application as a CGI script so ExecCGI must be +enabled for the directory. + + AddHandler fastcgi-script .fcgi + +The above tells Apache to run any .fcgi file as a FastCGI application. + +Here is a complete example: + + + ServerName www.myapp.com + DocumentRoot /path/to/MyApp + + # Allow CGI script to run + + Options +ExecCGI + + + # Tell Apache this is a FastCGI application + + SetHandler fastcgi-script + + +Then a request for /script/myapp_fastcgi.pl will run the +application. For more information on using FastCGI under Apache, visit L =head2 Lighttpd -This configuration was tested with Lighttpd 1.4.7. +These configurations were tested with Lighttpd 1.4.7. + +=head3 Standalone server mode + + server.document-root = "/var/www/MyApp/root" + + fastcgi.server = ( + "" => ( + "MyApp" => ( + "socket" => "/tmp/myapp.socket", + "check-local" => "disable" + ) + ) + ) + +=head3 Static mode server.document-root = "/var/www/MyApp/root" @@ -209,28 +303,18 @@ This configuration was tested with Lighttpd 1.4.7. ) ) -You can also run your application at any non-root location. +Note that in newer versions of lighttpd, the min-procs and idle-timeout +values are disabled. The above example would start 5 processes. - fastcgi.server = ( - "/myapp" => ( - "MyApp" => ( - # same as above - ) - ) - ) +=head3 Non-root configuration -You can also use an external server: - - # Start the external server (requires FCGI::ProcManager) - $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 - - server.document-root = "/var/www/MyApp/root" +You can also run your application at any non-root location with either of the +above modes. fastcgi.server = ( - "" => ( + "/myapp" => ( "MyApp" => ( - "socket" => "/tmp/myapp.socket", - "check-local" => "disable" + # same as above ) ) ) @@ -255,6 +339,10 @@ Christian Hansen, Andy Grundman, +=head1 THANKS + +Bill Moseley, for documentation updates and testing. + =head1 COPYRIGHT This program is free software, you can redistribute it and/or modify it under diff --git a/lib/Catalyst/Helper.pm b/lib/Catalyst/Helper.pm index 49122a4..9c83a9c 100644 --- a/lib/Catalyst/Helper.pm +++ b/lib/Catalyst/Helper.pm @@ -734,7 +734,7 @@ pod2usage(1) if $help; (requires -listen) -d -daemon daemonize (requires -listen) -M -manager specify alternate process manager - (FCGI::ProcessManager sub-class) + (FCGI::ProcManager sub-class) or empty string to disable =head1 DESCRIPTION