Apache 1

The following assumes you have Apache 1 installed in /usr/local/apache. Adjust paths as necessary.

Install FastCGI

There are two FastCGI modules for Apache:

mod_fastcgi (reportedly faster)
mod_fcgid, a binary-compatible alternative with "a new process management strategy, which concentrates on reducing the number of fastcgi server, and kick[ing] out the corrupt fastcgi server as soon as possible"

Package installation

Check if your distro has a FastCGI binary. For example, Ubuntu has libapache2-mod-fastcgi.

To install it on Ubuntu 10.04 (Lucid), do this:

Verify that /etc/apt/sources.list contains these two lines:

deb http://archive.ubuntu.com/ubuntu/ lucid main restricted multiverse deb-src http://archive.ubuntu.com/ubuntu lucid main restricted multiverse

apt-get update
apt-get install libapache2-mod-fastcgi

Compiling from source

First, download the FastCGI source from the FastCGI Apache module downloads page. You want "mod_fastcgi-current.tar.gz". Unpack that to a directory and follow the instructions in INSTALL. If your Apache is already built the easiest option is probably "option 3" in that document.

Check that you have mod_so:

$ /usr/local/apache/bin/httpd -l
[...]
mod_so.c
[...]

If you don't have mod_so.c compiled in you'll have to use option 1 or 2 as described in the FastCGI INSTALL file.

Otherwise, you can do this:

$ cd mod_fastcgi-2.4.6   # where you unpacked mod_fastcgi
$ /usr/local/apache/bin/apxs -o mod_fastcgi.so -c *.c
$ sudo /usr/local/apache/bin/apxs -i -a -n fastcgi mod_fastcgi.so

Configure Apache

Assuming apxs installed mod_fastcgi.so into /usr/local/apache/libexec, add the following to an Apache .conf file:

LoadModule fastcgi_module libexec/mod_fastcgi.so
<IfModule mod_fastcgi.c>
  FastCgiExternalServer /tmp/myapp.fcgi -host myhost:8081
  Alias /myapp/    /tmp/myapp.fcgi/
</IfModule>

Explanation of parameters:

The first argument after the FastCgiExternalServer directive must be to a directory that does exist, and is readable by the user Apache is running under. Generally, /tmp fulfills these requirements.
Even though the path must exist, the file is essentially bogus -- it's just used as a hook within mod_fastcgi. So there is no such file as /tmp/myapp.fcgi. Same for Alias.
Always add ".fcgi" to the end of the path. Odd things happen without it. In particular, Catalyst can become confused about what your URI root is so $c->uri_for() will start generating broken URLs.
The option above configures Catalyst to talk to your MyApp FastCGI server on port 8081 on the machine "myhost". Change hostname and port as appropriate.
If you're running Apache and your Catalyst application on the same server use the -socket <filename> directive instead of -port <n> to use UNIX domain sockets. Using -host will still work (either use hostname "localhost" or user -port and specify only the port) but carries more overhead than you need.

FastCGI server modes

You FastCGI server can be run in three modes:

external (using the FastCgiExternalServer directive) - the most flexible, but you need to manage your application's process
static (using FastCgiServer) - Apache calls your .pl script for you (which means your application will run as the user that runs Apache), but less flexible
dynamic ('SetHandler')

See Catalyst::Engine::FastCGI for pros and cons of each mode, and the mod_fastcgi documentation for details.

Run your app as a FastCGI process

Assuming you chose external mode, you'll need to launch your application:

$ cd myapp  # where your app is installed
$ ./script/myapp_fastcgi.pl -l :8081 -n 3 -p /tmp/myapp.pid -d

The command above will create a FastCGI process that will run your Catalyst application. It will listen on port 8081 and run 3 parallel instances. It will save its process ID in "/tmp/myapp.pid".

The "-d" option runs the application in the background. Add an "-e" to direct STDOUT to the console -- otherwise it goes to your Apache error_log.

You will probably want an init script to start/stop/restart your FastCGI application. See deployment#Managing FastCGI Processes for example init scripts.

Apache 2

The instructions are very similar for Apache 2 as for Apache 1. Only the installation should be different. See INSTALL.AP2 in the mod_fastcgi directory for install instructions.

FastCGI at Root and Somewhere Else

If you would like to install a fastcgi application both at the root of your web server and somewhere else it's important to configure the Aliases in the correct order. The root configuration should come last. For example, one can put the following in their httpd.conf:

 # Demo MyApp
Alias /demo/static /opt/my.domain/myapp/share/skin/default/web
FastCgiExternalServer /tmp/demoapp.fcgi -host fastcgi.demohost.org:3005 -idle-timeout 600
Alias /demo /tmp/demoapp.fcgi/

 # Production MyApp
Alias /static /opt/my.domain/myapp/share/skin/default/web
FastCgiExternalServer /tmp/myapp.fcgi -host fastcgi.prodhost.org:3005 -idle-timeout 600
Alias / /tmp/myapp.fcgi/

FAQ

Where are the environment variables?

Apache's startup environment isn't passed to FastCGI apps. Consider first getting the information you need from $c->request, $c->engine etc. If all that fails, use $c->engine->env.

Why is my application so slow, serving blank pages, and/or acting unexpededly?

mod_fastcgi and mod_deflate do not coexist well under certain versions of apache (Debian Lenny stock packages for example). A workaround is to not load the deflate module. An alternative solution is to build and install a recent snapshot version of mod_fastcgi (found at http://www.fastcgi.com/dist/). Snapshot versions (and possible future release versions) from November 2008 or later are compatible with mod_deflate and other output filters.

In most cases, the interaction between mod_deflate and buggy mod_fastcgi will appear as page loads "hanging" for 15 seconds or more, but instances of Chrome displaying blank white pages have also been reported.

Why is my server response suddenly truncated on Ubuntu 8.04 (or newer) + FastCGI (mod_fastcgi)?

See above: the shipped versions of mod_fastcgi and mod_deflate are incompatible. There is a known bug, confirmed for packages: libapache_mod_fastcgi 2.4.6 and mod_deflate from apache2 2.2.8

Why does Apache claim myapp_fastcgi.pl doesn't exist when it does?

If you get this error:

FastCGI: can't start server "/tmp/myapp/script/myapp_fastcgi.pl" (pid 15460), execle() failed: No such file or directory

when the file is there, and its owner is nobody, that's just a bad error message from Apache. The real cause is that the shebang line in myapp_fastcgi.pl could not be executed.

"client denied by server configuration"?

Check the access allowed by your conf file. A simple example is below:

<Location />
    order allow,deny
    allow from all
</Location>

Why do I get a DBD::SQLite error "unable to open database file"?

This happens if your application is run in static FastCGI mode. myapp_fastcgi.pl is spawned by Apache and will inherit its user (usually nobody run ps -ef | grep httpd to determine it). If that user can't write to the directory where your SQLite database file is, you will get this permission error. Set permissions accordingly (the MyApp directory may also need write permission if your application writes in its own directory), or pass -user and -group to FastCgiServer in conjunction with FastCgiWrapper

apache fastcgi