Commit | Line | Data |
1d2376f3 |
1 | =head1 NAME |
2 | |
3 | Catalyst::Manual::Deployment::Apache::FastCGI - Deploying Catalyst with FastCGI on Apache |
4 | |
5 | =head2 Setup |
6 | |
7 | =head3 1. Install Apache with mod_fastcgi |
8 | |
5abded07 |
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 |
12 | install the L<FCGI> module from CPAN. |
1d2376f3 |
13 | |
14 | Important Note! If you experience difficulty properly rendering pages, |
15 | try disabling Apache's mod_deflate (Deflate Module), e.g. 'a2dismod deflate'. |
16 | |
45b58a85 |
17 | =head2 Apache 1.x, 2.x |
18 | |
19 | Apache requires the mod_fastcgi module. The same module supports both |
20 | Apache 1 and 2. |
21 | |
22 | There are three ways to run your application under FastCGI on Apache: server, |
23 | static, and dynamic. |
24 | |
25 | =head3 Standalone server mode |
26 | |
27 | FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket |
28 | Alias /myapp/ /tmp/myapp.fcgi/ |
29 | |
30 | # Or, run at the root |
31 | Alias / /tmp/myapp.fcgi/ |
32 | |
33 | # Optionally, rewrite the path when accessed without a trailing slash |
34 | RewriteRule ^/myapp$ myapp/ [R] |
35 | |
36 | |
37 | The FastCgiExternalServer directive tells Apache that when serving |
5abded07 |
38 | /tmp/myapp to use the FastCGI application listening on the socket |
45b58a85 |
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>. |
43 | |
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. |
51 | |
52 | =head3 Static mode |
53 | |
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. |
59 | |
60 | FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3 |
61 | Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/ |
62 | |
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. |
66 | |
67 | =head3 Dynamic mode |
68 | |
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. |
72 | |
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. |
77 | |
78 | AddHandler fastcgi-script .fcgi |
79 | |
80 | The above tells Apache to run any .fcgi file as a FastCGI application. |
81 | |
82 | Here is a complete example: |
83 | |
84 | <VirtualHost *:80> |
85 | ServerName www.myapp.com |
86 | DocumentRoot /path/to/MyApp |
87 | |
88 | # Allow CGI script to run |
89 | <Directory /path/to/MyApp> |
90 | Options +ExecCGI |
91 | </Directory> |
92 | |
93 | # Tell Apache this is a FastCGI application |
94 | <Files myapp_fastcgi.pl> |
95 | SetHandler fastcgi-script |
96 | </Files> |
97 | </VirtualHost> |
98 | |
99 | Then a request for /script/myapp_fastcgi.pl will run the |
100 | application. |
101 | |
102 | For more information on using FastCGI under Apache, visit |
103 | L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html> |
104 | |
105 | =head3 Authorization header with mod_fastcgi or mod_cgi |
106 | |
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: |
111 | |
112 | RewriteCond %{HTTP:Authorization} ^(.+) |
113 | RewriteRule ^(.*)$ $1 [E=HTTP_AUTHORIZATION:%1,PT] |
114 | |
115 | |
1d2376f3 |
116 | =head4 2. Configure your application |
117 | |
118 | # Serve static content directly |
119 | DocumentRoot /var/www/MyApp/root |
120 | Alias /static /var/www/MyApp/root/static |
121 | |
122 | FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -processes 3 |
123 | Alias /myapp/ /var/www/MyApp/script/myapp_fastcgi.pl/ |
124 | |
125 | # Or, run at the root |
126 | Alias / /var/www/MyApp/script/myapp_fastcgi.pl/ |
127 | |
128 | The above commands will launch 3 app processes and make the app available at |
129 | /myapp/ |
130 | |
131 | =head3 Standalone server mode |
132 | |
133 | While not as easy as the previous method, running your app as an external |
134 | server gives you much more flexibility. |
135 | |
136 | First, launch your app as a standalone server listening on a socket. |
137 | |
138 | script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 -p /tmp/myapp.pid -d |
139 | |
140 | You can also listen on a TCP port if your web server is not on the same |
141 | machine. |
142 | |
143 | script/myapp_fastcgi.pl -l :8080 -n 5 -p /tmp/myapp.pid -d |
144 | |
145 | You will probably want to write an init script to handle starting/stopping |
146 | of the app using the pid file. |
147 | |
148 | Now, we simply configure Apache to connect to the running server. |
149 | |
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 |
152 | # maintenance" |
153 | Alias /_errors /var/www/MyApp/root/error-pages |
154 | ErrorDocument 502 /_errors/502.html |
155 | |
156 | FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket |
157 | Alias /myapp/ /tmp/myapp.fcgi/ |
158 | |
159 | # Or, run at the root |
160 | Alias / /tmp/myapp.fcgi/ |
161 | |
162 | =head3 More Info |
163 | |
0191b435 |
164 | L<Catalyst::Manual::Deployment::FastCGI>. |
1d2376f3 |
165 | |
166 | =head1 AUTHORS |
167 | |
168 | Catalyst Contributors, see Catalyst.pm |
169 | |
170 | =head1 COPYRIGHT |
171 | |
172 | This library is free software. You can redistribute it and/or modify it under |
173 | the same terms as Perl itself. |
174 | |
175 | =cut |
176 | |