From: Tomas Doran Date: Sat, 6 Aug 2011 16:18:56 +0000 (+0100) Subject: Rip the stuff out of Engine::FastCGI in master X-Git-Tag: 5.8901~8 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FCatalyst-Manual.git;a=commitdiff_plain;h=45b58a85a818703c790e8c09786cc449bad3506c Rip the stuff out of Engine::FastCGI in master --- diff --git a/lib/Catalyst/Manual/Deployment.pod b/lib/Catalyst/Manual/Deployment.pod index 48dd75e..0ce9147 100644 --- a/lib/Catalyst/Manual/Deployment.pod +++ b/lib/Catalyst/Manual/Deployment.pod @@ -15,375 +15,6 @@ L L -=head2 mod_perl Deployment - -mod_perl is not the best solution for many applications, but we'll list some -pros and cons so you can decide for yourself. The other (recommended) -deployment option is FastCGI, for which see below. - -=head3 Pros - -=head4 Speed - -mod_perl is fast and your app will be loaded in memory -within each Apache process. - -=head4 Shared memory for multiple apps - -If you need to run several Catalyst apps on the same server, mod_perl will -share the memory for common modules. - -=head3 Cons - -=head4 Memory usage - -Since your application is fully loaded in memory, every Apache process will -be rather large. This means a large Apache process will be tied up while -serving static files, large files, or dealing with slow clients. For this -reason, it is best to run a two-tiered web architecture with a lightweight -frontend server passing dynamic requests to a large backend mod_perl -server. - -=head4 Reloading - -Any changes made to the core code of your app require a full Apache restart. -Catalyst does not support Apache::Reload or StatINC. This is another good -reason to run a frontend web server where you can set up an -C page to report that your app is down for maintenance. - -=head4 Cannot run multiple versions of the same app - -It is not possible to run two different versions of the same application in -the same Apache instance because the namespaces will collide. - -=head4 Cannot run different versions of libraries. - -If you have two different applications which run on the same machine, -which need two different versions of a library then the only way to do -this is to have per-vhost perl interpreters (with different library paths). -This is entirely possible, but nullifies all the memory sharing benefits that -you get from having multiple applications sharing the same interpreter. - -=head4 Setup - -Now that we have that out of the way, let's talk about setting up mod_perl -to run a Catalyst app. - -=head4 1. Install Catalyst::Engine::Apache - -You should install the latest versions of both Catalyst and -Catalyst::Engine::Apache. The Apache engines were separated from the -Catalyst core in version 5.50 to allow for updates to the engine without -requiring a new Catalyst release. - -=head4 2. Install Apache with mod_perl - -Both Apache 1.3 and Apache 2 are supported, although Apache 2 is highly -recommended. With Apache 2, make sure you are using the prefork MPM and not -the worker MPM. The reason for this is that many Perl modules are not -thread-safe and may have problems running within the threaded worker -environment. Catalyst is thread-safe however, so if you know what you're -doing, you may be able to run using worker. - -In Debian, the following commands should get you going. - - apt-get install apache2-mpm-prefork - apt-get install libapache2-mod-perl2 - -=head4 3. Configure your application - -Every Catalyst application will automagically become a mod_perl handler -when run within mod_perl. This makes the configuration extremely easy. -Here is a basic Apache 2 configuration. - - PerlSwitches -I/var/www/MyApp/lib - PerlModule MyApp - - - SetHandler modperl - PerlResponseHandler MyApp - - -The most important line here is C. This causes mod_perl -to preload your entire application into shared memory, including all of your -controller, model, and view classes and configuration. If you have -Debug -mode enabled, you will see the startup output scroll by when you first -start Apache. - -For an example Apache 1.3 configuration, please see the documentation for -L. - -=head3 Test It - -That's it, your app is now a full-fledged mod_perl application! Try it out -by going to http://your.server.com/. - -=head3 Other Options - -=head4 Non-root location - -You may not always want to run your app at the root of your server or virtual -host. In this case, it's a simple change to run at any non-root location -of your choice. - - - SetHandler modperl - PerlResponseHandler MyApp - - -When running this way, it is best to make use of the C method in -Catalyst for constructing correct links. - -=head4 Static file handling - -Static files can be served directly by Apache for a performance boost. - - DocumentRoot /var/www/MyApp/root - - SetHandler default-handler - - -This will let all files within root/static be handled directly by Apache. In -a two-tiered setup, the frontend server should handle static files. -The configuration to do this on the frontend will vary. - -The same is accomplished in lighttpd with the following snippet: - - $HTTP["url"] !~ "^/(?:img/|static/|css/|favicon.ico$)" { - fastcgi.server = ( - "" => ( - "MyApp" => ( - "socket" => "/tmp/myapp.socket", - "check-local" => "disable", - ) - ) - ) - } - -Which serves everything in the img, static, css directories -statically, as well as the favicon file. - -Note the path of the application needs to be stated explicitly in the -web server configuration for both these recipes. - -=head2 Catalyst on shared hosting - -So, you want to put your Catalyst app out there for the whole world to -see, but you don't want to break the bank. There is an answer - if you -can get shared hosting with FastCGI and a shell, you can install your -Catalyst app in a local directory on your shared host. First, run - - perl -MCPAN -e shell - -and go through the standard CPAN configuration process. Then exit out -without installing anything. Next, open your .bashrc and add - - export PATH=$HOME/local/bin:$HOME/local/script:$PATH - perlversion=`perl -v | grep 'built for' | awk '{print $4}' | sed -e 's/v//;'` - export PERL5LIB=$HOME/local/share/perl/$perlversion:$HOME/local/lib/perl/$perlversion:$HOME/local/lib:$PERL5LIB - -and log out, then back in again (or run C<". .bashrc"> if you -prefer). Finally, edit C<.cpan/CPAN/MyConfig.pm> and add - - 'make_install_arg' => qq[SITEPREFIX=$ENV{HOME}/local], - 'makepl_arg' => qq[INSTALLDIRS=site install_base=$ENV{HOME}/local], - -Now you can install the modules you need using CPAN as normal; they -will be installed into your local directory, and perl will pick them -up. Finally, change directory into the root of your virtual host and -symlink your application's script directory in: - - cd path/to/mydomain.com - ln -s ~/lib/MyApp/script script - -And add the following lines to your .htaccess file (assuming the server -is setup to handle .pl as fcgi - you may need to rename the script to -myapp_fastcgi.fcgi and/or use a SetHandler directive): - - RewriteEngine On - RewriteCond %{REQUEST_URI} !^/?script/myapp_fastcgi.pl - RewriteRule ^(.*)$ script/myapp_fastcgi.pl/$1 [PT,L] - -Now C should now Just Work. Congratulations, now -you can tell your friends about your new website (or in our case, tell -the client it's time to pay the invoice :) ) - -=head2 FastCGI Deployment - -FastCGI is a high-performance extension to CGI. It is suitable -for production environments. - -=head3 Pros - -=head4 Speed - -FastCGI performs equally as well as mod_perl. Don't let the 'CGI' fool you; -your app runs as multiple persistent processes ready to receive connections -from the web server. - -=head4 App Server - -When using external FastCGI servers, your application runs as a standalone -application server. It may be restarted independently from the web server. -This allows for a more robust environment and faster reload times when -pushing new app changes. The frontend server can even be configured to -display a friendly "down for maintenance" page while the application is -restarting. - -=head4 Load-balancing - -You can launch your application on multiple backend servers and allow the -frontend web server to load-balance between all of them. And of course, if -one goes down, your app continues to run fine. - -=head4 Multiple versions of the same app - -Each FastCGI application is a separate process, so you can run different -versions of the same app on a single server. - -=head4 Can run with threaded Apache - -Since your app is not running inside of Apache, the faster mpm_worker module -can be used without worrying about the thread safety of your application. - -=head3 Cons - -You may have to disable mod_deflate. If you experience page hangs with -mod_fastcgi then remove deflate.load and deflate.conf from mods-enabled/ - -=head4 More complex environment - -With FastCGI, there are more things to monitor and more processes running -than when using mod_perl. - -=head3 Setup - -=head4 1. Install Apache with mod_fastcgi - -mod_fastcgi for Apache is a third party module, and can be found at -L. It is also packaged in many distributions, -for example, libapache2-mod-fastcgi in Debian. You will also need to install -the L module from cpan. - -Important Note! If you experience difficulty properly rendering pages, -try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'. - -=head4 2. Configure your application - - # Serve static content directly - DocumentRoot /var/www/MyApp/root - Alias /static /var/www/MyApp/root/static - - FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -processes 3 - Alias /myapp/ /var/www/MyApp/script/myapp_fastcgi.pl/ - - # Or, run at the root - Alias / /var/www/MyApp/script/myapp_fastcgi.pl/ - -The above commands will launch 3 app processes and make the app available at -/myapp/ - -=head3 Standalone server mode - -While not as easy as the previous method, running your app as an external -server gives you much more flexibility. - -First, launch your app as a standalone server listening on a socket. - - script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -p /tmp/myapp.pid -d - -You can also listen on a TCP port if your web server is not on the same -machine. - - script/myapp_fastcgi.pl -l :8080 -n 5 -p /tmp/myapp.pid -d - -You will probably want to write an init script to handle starting/stopping -of the app using the pid file. - -Now, we simply configure Apache to connect to the running server. - - # 502 is a Bad Gateway error, and will occur if the backend server is down - # This allows us to display a friendly static page that says "down for - # maintenance" - Alias /_errors /var/www/MyApp/root/error-pages - ErrorDocument 502 /_errors/502.html - - FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket - Alias /myapp/ /tmp/myapp.fcgi/ - - # Or, run at the root - Alias / /tmp/myapp.fcgi/ - -=head3 More Info - -L. - -=head2 Development server deployment - -The development server is a mini web server written in perl. If you -expect a low number of hits or you don't need mod_perl/FastCGI speed, -you could use the development server as the application server with a -lightweight proxy web server at the front. However, consider using -L for this kind of deployment instead, since -it can better handle multiple concurrent requests without forking, or can -prefork a set number of servers for improved performance. - -=head3 Pros - -As this is an application server setup, the pros are the same as -FastCGI (with the exception of speed). -It is also: - -=head4 Simple - -The development server is what you create your code on, so if it works -here, it should work in production! - -=head3 Cons - -=head4 Speed - -Not as fast as mod_perl or FastCGI. Needs to fork for each request -that comes in - make sure static files are served by the web server to -save forking. - -=head3 Setup - -=head4 Start up the development server - - script/myapp_server.pl -p 8080 -k -f -pidfile=/tmp/myapp.pid - -You will probably want to write an init script to handle stop/starting -the app using the pid file. - -=head4 Configuring Apache - -Make sure mod_proxy is enabled and add: - - # Serve static content directly - DocumentRoot /var/www/MyApp/root - Alias /static /var/www/MyApp/root/static - - ProxyRequests Off - - Order deny,allow - Allow from all - - - # Need to specifically stop these paths from being passed to proxy - ProxyPass /static ! - ProxyPass /favicon.ico ! - - ProxyPass / http://localhost:8080/ - ProxyPassReverse / http://localhost:8080/ - - # This is optional if you'd like to show a custom error page - # if the proxy is not available - ErrorDocument 502 /static/error_pages/http502.html - -You can wrap the above within a VirtualHost container if you want -different apps served on the same host. - =head1 AUTHORS Catalyst Contributors, see Catalyst.pm diff --git a/lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod b/lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod index a53af03..4640be2 100644 --- a/lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod +++ b/lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod @@ -14,6 +14,105 @@ the L module from cpan. Important Note! If you experience difficulty properly rendering pages, try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'. +=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.fcgi -socket /tmp/myapp.socket + Alias /myapp/ /tmp/myapp.fcgi/ + + # Or, run at the root + Alias / /tmp/myapp.fcgi/ + + # 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.fcgi B exist -- +it's a virtual file name. With some versions of C or +C, you can use any name you like, but some require that the +virtual filename end in C<.fcgi>. + +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/ + +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. + +=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 + +=head3 Authorization header with mod_fastcgi or mod_cgi + +By default, mod_fastcgi/mod_cgi do not pass along the Authorization header, +so modules like C will +not work. To enable pass-through of this header, add the following +mod_rewrite directives: + + RewriteCond %{HTTP:Authorization} ^(.+) + RewriteRule ^(.*)$ $1 [E=HTTP_AUTHORIZATION:%1,PT] + + =head4 2. Configure your application # Serve static content directly diff --git a/lib/Catalyst/Manual/Deployment/FastCGI.pod b/lib/Catalyst/Manual/Deployment/FastCGI.pod index 71e3a24..f966d8c 100644 --- a/lib/Catalyst/Manual/Deployment/FastCGI.pod +++ b/lib/Catalyst/Manual/Deployment/FastCGI.pod @@ -52,9 +52,29 @@ than when using mod_perl. XXX - FIXME, note not just apache! -=head3 More Info +=head2 Standalone FastCGI Server -L - XXX FIXME. +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. + +To start your application in server mode, install the FCGI::ProcManager +module and then use the included fastcgi.pl script. + + $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 + +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. + +See below for the specific web server configurations for using the external +server. =head1 AUTHORS diff --git a/lib/Catalyst/Manual/Deployment/IIS/FastCGI.pod b/lib/Catalyst/Manual/Deployment/IIS/FastCGI.pod new file mode 100644 index 0000000..91b9b09 --- /dev/null +++ b/lib/Catalyst/Manual/Deployment/IIS/FastCGI.pod @@ -0,0 +1,143 @@ +=head1 NAME + +Catalyst::Manual::Deployment::IIS::FastCGI - Deploying Catalyst with Microsoft IIS + +=head2 Microsoft IIS + +It is possible to run Catalyst under IIS with FastCGI, but only on IIS 6.0 +(Microsoft Windows 2003), IIS 7.0 (Microsoft Windows 2008 and Vista) and +hopefully its successors. + +Even if it is declared that FastCGI is supported on IIS 5.1 (Windows XP) it +does not support some features (specifically: wildcard mappings) that prevents +running Catalyst application. + +Let us assume that our server has the following layout: + + d:\WWW\WebApp\ path to our Catalyst application + d:\strawberry\perl\bin\perl.exe path to perl interpreter (with Catalyst installed) + c:\windows Windows directory + +=head3 Setup IIS 6.0 (Windows 2003) + +=over 4 + +=item Install FastCGI extension for IIS 6.0 + +FastCGI is not a standard part of IIS 6 - you have to install it separately. For +more info and download go to L. Choose +approptiate version (32-bit/64-bit), installation is quite simple +(in fact no questions, no options). + +=item Create a new website + +Open "Control Panel" > "Administrative Tools" > "Internet Information Services Manager". +Click "Action" > "New" > "Web Site". After you finish the installation wizard +you need to go to the new website's properties. + +=item Set website properties + +On tab "Web site" set proper values for: +Site Description, IP Address, TCP Port, SSL Port etc. + +On tab "Home Directory" set the following: + + Local path: "d:\WWW\WebApp\root" + Local path permission flags: check only "Read" + "Log visits" + Execute permitions: "Scripts only" + +Click "Configuration" button (still on Home Directory tab) then click "Insert" +the wildcard application mapping and in the next dialog set: + + Executable: "c:\windows\system32\inetsrv\fcgiext.dll" + Uncheck: "Verify that file exists" + +Close all dialogs with "OK". + +=item Edit fcgiext.ini + +Put the following lines into c:\windows\system32\inetsrv\fcgiext.ini (on 64-bit +system c:\windows\syswow64\inetsrv\fcgiext.ini): + + [Types] + *:8=CatalystApp + ;replace 8 with the identification number of the newly created website + ;it is not so easy to get this number: + ; - you can use utility "c:\inetpub\adminscripts\adsutil.vbs" + ; to list websites: "cscript adsutil.vbs ENUM /P /W3SVC" + ; to get site name: "cscript adsutil.vbs GET /W3SVC//ServerComment" + ; to get all details: "cscript adsutil.vbs GET /W3SVC/" + ; - or look where are the logs located: + ; c:\WINDOWS\SYSTEM32\Logfiles\W3SVC7\whatever.log + ; means that the corresponding number is "7" + ;if you are running just one website using FastCGI you can use '*=CatalystApp' + + [CatalystApp] + ExePath=d:\strawberry\perl\bin\perl.exe + Arguments="d:\WWW\WebApp\script\webapp_fastcgi.pl -e" + + ;by setting this you can instruct IIS to serve Catalyst static files + ;directly not via FastCGI (in case of any problems try 1) + IgnoreExistingFiles=0 + + ;do not be fooled by Microsoft doc talking about "IgnoreExistingDirectories" + ;that does not work and use "IgnoreDirectories" instead + IgnoreDirectories=1 + +=back + +=head3 Setup IIS 7.0 (Windows 2008 and Vista) + +Microsoft IIS 7.0 has built-in support for FastCGI so you do not have to install +any addons. + +=over 4 + +=item Necessary steps during IIS7 installation + +During IIS7 installation after you have added role "Web Server (IIS)" +you need to check to install role feature "CGI" (do not be nervous that it is +not FastCGI). If you already have IIS7 installed you can add "CGI" role feature +through "Control panel" > "Programs and Features". + +=item Create a new website + +Open "Control Panel" > "Administrative Tools" > "Internet Information Services Manager" +> "Add Web Site". + + site name: "CatalystSite" + content directory: "d:\WWW\WebApp\root" + binding: set proper IP address, port etc. + +=item Configure FastCGI + +You can configure FastCGI extension using commandline utility +"c:\windows\system32\inetsrv\appcmd.exe" + +=over 4 + +=item Configuring section "fastCgi" (it is a global setting) + + appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='d:\strawberry\perl\bin\perl.exe',arguments='d:\www\WebApp\script\webapp_fastcgi.pl -e',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='1000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost + +=item Configuring proper handler (it is a site related setting) + + appcmd.exe set config "CatalystSite" -section:system.webServer/handlers /+"[name='CatalystFastCGI',path='*',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='d:\strawberry\perl\bin\perl.exe|d:\www\WebApp\script\webapp_fastcgi.pl -e',resourceType='Unspecified',requireAccess='Script']" /commit:apphost + +Note: before launching the commands above do not forget to change site +name and paths to values relevant for your server setup. + +=back + +=back + +=head1 AUTHORS + +Catalyst Contributors, see Catalyst.pm + +=head1 COPYRIGHT + +This library is free software. You can redistribute it and/or modify it under +the same terms as Perl itself. + +=cut diff --git a/lib/Catalyst/Manual/Deployment/lighttpd/FastCGI.pod b/lib/Catalyst/Manual/Deployment/lighttpd/FastCGI.pod index 002c1d9..a9ba089 100644 --- a/lib/Catalyst/Manual/Deployment/lighttpd/FastCGI.pod +++ b/lib/Catalyst/Manual/Deployment/lighttpd/FastCGI.pod @@ -2,6 +2,61 @@ Catalyst::Manual::Deployment::lighttpd::FastCGI - Deploying Catalyst with lighttpd +=head2 Lighttpd + +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" + + fastcgi.server = ( + "" => ( + "MyApp" => ( + "socket" => "/tmp/myapp.socket", + "check-local" => "disable", + "bin-path" => "/var/www/MyApp/script/myapp_fastcgi.pl", + "min-procs" => 2, + "max-procs" => 5, + "idle-timeout" => 20 + ) + ) + ) + +Note that in newer versions of lighttpd, the min-procs and idle-timeout +values are disabled. The above example would start 5 processes. + +=head3 Non-root configuration + +You can also run your application at any non-root location with either of the +above modes. Note the required mod_rewrite rule. + + url.rewrite = ( "myapp\$" => "myapp/" ) + fastcgi.server = ( + "/myapp" => ( + "MyApp" => ( + # same as above + ) + ) + ) + +For more information on using FastCGI under Lighttpd, visit +L + + =head4 Static file handling Static files can be served directly by lighttpd for a performance boost. @@ -20,3 +75,13 @@ Static files can be served directly by lighttpd for a performance boost. Which serves everything in the img, static, css directories statically, as well as the favicon file. +=head1 AUTHORS + +Catalyst Contributors, see Catalyst.pm + +=head1 COPYRIGHT + +This library is free software. You can redistribute it and/or modify it under +the same terms as Perl itself. + +=cut \ No newline at end of file diff --git a/lib/Catalyst/Manual/Deployment/nginx/FastCGI.pod b/lib/Catalyst/Manual/Deployment/nginx/FastCGI.pod new file mode 100644 index 0000000..0987b46 --- /dev/null +++ b/lib/Catalyst/Manual/Deployment/nginx/FastCGI.pod @@ -0,0 +1,84 @@ +=head1 NAME + +Catalyst::Manual::Deployment::nginx::FastCGI - Deploying Catalyst with nginx + +=head nginx + +Catalyst runs under nginx via FastCGI in a similar fashion as the lighttpd +standalone server as described above. + +nginx does not have its own internal FastCGI process manager, so you must run +the FastCGI service separately. + +=head3 Configuration + +To configure nginx, you must configure the FastCGI parameters and also the +socket your FastCGI daemon is listening on. It can be either a TCP socket +or a Unix file socket. + +The server configuration block should look roughly like: + + server { + listen $port; + + location / { + fastcgi_param QUERY_STRING $query_string; + fastcgi_param REQUEST_METHOD $request_method; + fastcgi_param CONTENT_TYPE $content_type; + fastcgi_param CONTENT_LENGTH $content_length; + + fastcgi_param SCRIPT_NAME /; + fastcgi_param PATH_INFO $fastcgi_script_name; + fastcgi_param REQUEST_URI $request_uri; + fastcgi_param DOCUMENT_URI $document_uri; + fastcgi_param DOCUMENT_ROOT $document_root; + fastcgi_param SERVER_PROTOCOL $server_protocol; + + fastcgi_param GATEWAY_INTERFACE CGI/1.1; + fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; + + fastcgi_param REMOTE_ADDR $remote_addr; + fastcgi_param REMOTE_PORT $remote_port; + fastcgi_param SERVER_ADDR $server_addr; + fastcgi_param SERVER_PORT $server_port; + fastcgi_param SERVER_NAME $server_name; + + # Adjust the socket for your applications! + fastcgi_pass unix:$docroot/myapp.socket; + } + } + +It is the standard convention of nginx to include the fastcgi_params in a +separate file (usually something like C) and +simply include that file. + +=head3 Non-root configuration + +If you properly specify the PATH_INFO and SCRIPT_NAME parameters your +application will be accessible at any path. The SCRIPT_NAME variable is the +prefix of your application, and PATH_INFO would be everything in addition. + +As an example, if your application is rooted at /myapp, you would configure: + + fastcgi_param SCRIPT_NAME /myapp/; + fastcgi_param PATH_INFO $fastcgi_script_name; + +C<$fastcgi_script_name> would be "/myapp/path/of/the/action". Catalyst will +process this accordingly and setup the application base as expected. + +This behavior is somewhat different than Apache and Lighttpd, but is still +functional. + +For more information on nginx, visit: +L + +=head1 AUTHORS + +Catalyst Contributors, see Catalyst.pm + +=head1 COPYRIGHT + +This library is free software. You can redistribute it and/or modify it under +the same terms as Perl itself. + +=cut