Next: , Previous: Building and Using Compiled Web Applications, Up: Working With Web Applications


5.1.5 Deploying on Apache

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.

Enabling mod_rewrite

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

Copying the Web Application to the FastCGI Binary Directory

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.

Adding the Web Application to the Apache Configuration

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>
Technical Note About mod_rewrite

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.

Adding the Application Itself

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.

Troubleshooting

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.