lib/Catalyst/Manual/Deployment/Apache/FastCGI.pod

   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
   9 mod_fastcgi for Apache is a third-party module, and can be found at
  10 L<https://fastcgi-archives.github.io/>. 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.
  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
  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
  38 /tmp/myapp to use the FastCGI application listening 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>.
  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<https://fastcgi-archives.github.io/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 L<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
 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
 164 L<Catalyst::Manual::Deployment::FastCGI>.
 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