1Catalyst::Manual::DeploUysmeerntC:o:nAtCpraaitcbahulety:es:dtF:aP:seMtraClnGuIDa(ol3c:)u:mDeenptlaotyimoennt::Apache::FastCGI(3)
2
3
4

NAME

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

AUTHORS

169       Catalyst Contributors, see Catalyst.pm
170
172       This library is free software. You can redistribute it and/or modify it
173       under the same terms as Perl itself.
174
175
176
177perl v5.36.0                  Cata2l0y2s3t-:0:1M-a2n0ual::Deployment::Apache::FastCGI(3)
Impressum