3 Catalyst::Manual::Deployment::Apache::FastCGI - Deploying Catalyst with FastCGI on Apache
7 =head3 1. Install Apache with mod_fastcgi
9 mod_fastcgi for Apache is a third party module, and can be found at
10 L<http://www.fastcgi.com/>. It is also packaged in many distributions,
11 for example, libapache2-mod-fastcgi in Debian. You will also need to install
12 the L<FCGI> module from cpan.
14 Important Note! If you experience difficulty properly rendering pages,
15 try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'.
17 =head2 Apache 1.x, 2.x
19 Apache requires the mod_fastcgi module. The same module supports both
22 There are three ways to run your application under FastCGI on Apache: server,
25 =head3 Standalone server mode
27 FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket
28 Alias /myapp/ /tmp/myapp.fcgi/
31 Alias / /tmp/myapp.fcgi/
33 # Optionally, rewrite the path when accessed without a trailing slash
34 RewriteRule ^/myapp$ myapp/ [R]
37 The FastCgiExternalServer directive tells Apache that when serving
38 /tmp/myapp to use the FastCGI application listenting on the socket
39 /tmp/mapp.socket. Note that /tmp/myapp.fcgi B<MUST NOT> exist --
40 it's a virtual file name. With some versions of C<mod_fastcgi> or
41 C<mod_fcgid>, you can use any name you like, but some require that the
42 virtual filename end in C<.fcgi>.
44 It's likely that Apache is not configured to serve files in /tmp, so the
45 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
46 FastCGI application. The trailing slashes are important as their use will
47 correctly set the PATH_INFO environment variable used by Catalyst to
48 determine the request path. If you would like to be able to access your app
49 without a trailing slash (http://server/myapp), you can use the above
50 RewriteRule directive.
54 The term 'static' is misleading, but in static mode Apache uses its own
55 FastCGI Process Manager to start the application processes. This happens at
56 Apache startup time. In this case you do not run your application's
57 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
58 FastCGI script to run your application.
60 FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
61 Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
63 FastCgiServer tells Apache to start three processes of your application at
64 startup. The Alias command maps a path to the FastCGI application. Again,
65 the trailing slashes are important.
69 In FastCGI dynamic mode, Apache will run your application on demand,
70 typically by requesting a file with a specific extension (e.g. .fcgi). ISPs
71 often use this type of setup to provide FastCGI support to many customers.
73 In this mode it is often enough to place or link your *_fastcgi.pl script in
74 your cgi-bin directory with the extension of .fcgi. In dynamic mode Apache
75 must be able to run your application as a CGI script so ExecCGI must be
76 enabled for the directory.
78 AddHandler fastcgi-script .fcgi
80 The above tells Apache to run any .fcgi file as a FastCGI application.
82 Here is a complete example:
85 ServerName www.myapp.com
86 DocumentRoot /path/to/MyApp
88 # Allow CGI script to run
89 <Directory /path/to/MyApp>
93 # Tell Apache this is a FastCGI application
94 <Files myapp_fastcgi.pl>
95 SetHandler fastcgi-script
99 Then a request for /script/myapp_fastcgi.pl will run the
102 For more information on using FastCGI under Apache, visit
103 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
105 =head3 Authorization header with mod_fastcgi or mod_cgi
107 By default, mod_fastcgi/mod_cgi do not pass along the Authorization header,
108 so modules like C<Catalyst::Plugin::Authentication::Credential::HTTP> will
109 not work. To enable pass-through of this header, add the following
110 mod_rewrite directives:
112 RewriteCond %{HTTP:Authorization} ^(.+)
113 RewriteRule ^(.*)$ $1 [E=HTTP_AUTHORIZATION:%1,PT]
116 =head4 2. Configure your application
118 # Serve static content directly
119 DocumentRoot /var/www/MyApp/root
120 Alias /static /var/www/MyApp/root/static
122 FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -processes 3
123 Alias /myapp/ /var/www/MyApp/script/myapp_fastcgi.pl/
125 # Or, run at the root
126 Alias / /var/www/MyApp/script/myapp_fastcgi.pl/
128 The above commands will launch 3 app processes and make the app available at
131 =head3 Standalone server mode
133 While not as easy as the previous method, running your app as an external
134 server gives you much more flexibility.
136 First, launch your app as a standalone server listening on a socket.
138 script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -p /tmp/myapp.pid -d
140 You can also listen on a TCP port if your web server is not on the same
143 script/myapp_fastcgi.pl -l :8080 -n 5 -p /tmp/myapp.pid -d
145 You will probably want to write an init script to handle starting/stopping
146 of the app using the pid file.
148 Now, we simply configure Apache to connect to the running server.
150 # 502 is a Bad Gateway error, and will occur if the backend server is down
151 # This allows us to display a friendly static page that says "down for
153 Alias /_errors /var/www/MyApp/root/error-pages
154 ErrorDocument 502 /_errors/502.html
156 FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket
157 Alias /myapp/ /tmp/myapp.fcgi/
159 # Or, run at the root
160 Alias / /tmp/myapp.fcgi/
164 L<Catalyst::Manual::Deployment::FastCGI>.
168 Catalyst Contributors, see Catalyst.pm
172 This library is free software. You can redistribute it and/or modify it under
173 the same terms as Perl itself.