Next: Deploying On lighttpd, Previous: Building and Using Compiled Web Applications, Up: Working With Web Applications
These instructions explain how to deploy a compiled web application on the Apache web server. It is applicable to both Apache 1.3 and Apache 2.0.
Before following these instructions, please make sure that mod_fastcgi is enabled in Apache, as described here: Installing FastCGI.
You will need mod_rewrite, which is a standard module
distributed with Apache, enabled in your Apache server to deploy the
compiled web application. While Apache installations vary, you will
definitely need a LoadModule
line (the path might need to be
changed):
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
And you might also need an AddModule line (take a look to see if the other modules have one):
AddModule rewrite_module
It is typical to use the cgi-bin directory for FastCGI binaries. To find your cgi-bin directory, look for a line like the following in your Apache configuration. In this case, the cgi-bin directory would be /usr/lib/cgi-bin/:
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
The default cgi-bin directory for Apache 2 on Windows is C:/Program Files/Apache Group/Apache2/cgi-bin/. You will want to copy your compiled binary (and possibly the application library .dll file if you linked dynamically) to this directory.
On Unix you can use the cp command to copy the web application files to the cgi-bin directory:
cp myapp.fcgi libmyapp_u.so /usr/lib/cgi-bin/
TIP: If you are updating a web application that is already running, you may need to remove the previous version first, because your operating system won't let you change the contents of an executable that is currently running.
Your web application will need a “web root” directory where the static content such as images are stored. Even if your application has no static content, Apache requires that the directory be present. In the first example, we will use the directory /var/www/myapp/. If you are using Apache 2 in Windows, the directory would be, e.g. C:/Program Files/Apache Group/Apache2/htdocs/myapp/
We use the mod_rewrite module to grab all requests for PHP files in the application's web root directory and re-route them to the FastCGI binary. We also allow for an index.php file. This is an example Apache configuration section which says roughly “pass all requests for files that end in .php in the directory /var/www/myapp/ on to /cgi-bin/myapp.fcgi”:
<Directory /var/www/myapp/> RewriteEngine On RewriteRule ^(.+\.php)$ /cgi-bin/myapp.fcgi/$1 RewriteRule ^$ /cgi-bin/myapp.fcgi/index.php </Directory>
A similar example for Apache on Windows:
<Directory "C:/Program Files/Apache Group/Apache2/htdocs/myapp" > RewriteEngine On RewriteRule ^(.+\.php)$ /cgi-bin/myapp.fcgi/$1 RewriteRule ^$ /cgi-bin/myapp.fcgi/index.php </Directory>
The first argument to RewriteRule
is a regular expression which
will be matched against the request URL starting after the directory
in the Directory
tag. The second argument to RewriteRule
can use back references which expand into parenthesized sections of the
first argument. In the first example above, $1
is a
back reference which expands to the PHP filename that was requested.
For more on mod_rewrite, please see the Apache mod_rewrite documentation.
Finally, the most important step. This configuration section will tell Apache to start your web application, and will tell the web application where its web root is:
<IfModule mod_fastcgi.c> FastCgiServer cgi-bin/myapp.fcgi -initial-env PATH -initial-env WEB_DOC_ROOT=/var/www/myapp </IfModule>
A similar example for Apache on Windows:
<IfModule mod_fastcgi.c> FastCgiServer cgi-bin/myapp.fcgi -initial-env PATH -initial-env "WEB_DOC_ROOT=C:/Program Files/Apache Group/Apache2/htdocs/myapp" </IfModule>
For more detailed information about mod_fastcgi configuration, including additional options, please see http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html.
After making these changes, you are now ready to restart Apache and visit access your compiled application at, e.g. http://localhost/myapp/index.php.
If you're having trouble, first try adjusting the “LogLevel” directive in your Apache configuration to “info”. Then, rerun the application and check your error log.
One common error message that occurs is “premature end of script headers”. If you're getting this error, it may mean that Apache is trying to run the application with normal CGI and not FastCGI.
Please review the steps above and make sure that the directories are all correct. Visit the the mod_fastcgi site for more information on configuration and troubleshooting FastCGI applications.