SCGI on Apache using mod_scgi

The Simple Common Gateway Interface (SCGI) is a standard for communication between web servers and application servers on the back end. It has several performance advantages over CGI. This chapter describes configuring Apache to use SCGI to communicate with a Woof! application server on the back end using the mod_scgi module. The process of running Woof! as a SCGI application server is described in Running as an SCGI server.

SCGI is not a standard part of the Apache distribution and you need to install the mod_scgi Apache module to support it. Some service providers may not have it available and may not be willing to install it. A workaround is described later.

The steps below assume you are installing on a Linux or Unix system. Installation on Windows is substantially identical except for path differences.

Assumptions

This scenario makes the following assumptions:

• This is a dedicated server and you have full control over the Apache configuration files.
• The server only hosts the Woof! application and nothing else.
• The application is rooted at the top level, i.e. http://www.mysite.com is the entry point into the application.
• You have the means to modify the system configuration so that the Woof! SCGI server is started automatically either at boot time or when Apache is started.

Step 1 - install mod_scgi

The SCGI source code can be downloaded from the SCGI home page. Follow the instructions in the README.txt file in the apache2 directory in the SCGI distribution to build and install the module. Note this requires you to have the Apache build tools on your system. For Windows systems, you can either build using Visual C++ or you can download prebuilt binaries from the Woof! download page.

After installation, the mod_scgi.so module should reside in the Apache modules directory. The final SCGI installation step is to add the following line to the httpd.conf or equivalent.

LoadModule scgi_module modules/mod_scgi.so

Step 2 - install Woof!

The next step is to install Woof! for Apache and SCGI using the installer script.

~/woof-dist> tclsh scripts/installer.tcl install apache scgi -installdir /var/myapp

This will create the Woof! directory structure under /var/myapp. In particular, the /var/myapp/public will contain the publically accessible directory tree that will be the document root for the dedicated web server. Its subdirectories are intended to be directly served by Apache without going through Woof! as detailed below.

Step 3 - set the document root

Since this is the only application on the server, the document root for Apache must be changed to point to the Woof! public directory by editing the definition of DocumentRoot in httpd.conf.

DocumentRoot /var/myapp/public
<Directory "/var/myapp/public">
    Order allow,deny
    Allow from all
</Directory>

Note that the document root points to the public subdirectory, not the Woof! root directory. By default, Apache will now look under the /var/myapp/public directory to locate URL resources.

Step 4 - configure SCGI

Apache has to be told the SCGI server by adding the following to httpd.conf:

SCGIMount / 127.0.0.1:9999
<LocationMatch "/stylesheets|images|js|html/">
    SCGIHandler Off
</LocationMatch>

The SCGIMount directive has two purposes. First, it tells Apache that all URL's starting at the root / are to be passed to the SCGI server. Second, it indicates that the Woof! SCGI server is to be contacted on port 9999 on the local system. The LocationMatch directive is used to disable SCGI for requests under /stylesheets and /images so that static files are served by Apache without going through the Woof! SCGI server.

If instead of having the Woof! application root at / we had /myapp as the application root URL, the above lines would need to be changed as follows:

AliasMatch /myapp/((stylesheets|images)/.*) "/var/myapp/public/$1"
SCGIMount /myapp 127.0.0.1:9999
<LocationMatch "/myapp/stylesheets|images/">
    SCGIHandler Off
</LocationMatch>

Note that both SCGIMount as well as the LocationMatch lines have to be modified when the application root URL is changed. In addition, AliasMatch and Directory directives are needed to point to the Woof! public directory in order to retrieve static files.

Step 5 - starting the SCGI server

The Woof! SCGI server script that handles connections passed by Apache needs to be started whenever Apache runs. This step is actually independent of the web server and is described in Running as an SCGI server.

Completing the installation

Once the steps described there are done, configuration is complete. You can now move on to completing the installation.

Using SCGI in a shared hosting environment

Using SCGI as described above is not possible in a shared hosting environment if your service provider is not willing to add the SCGI module to the Apache configuration. In this case, you may be able to use the cgi2scgi adapter that comes with mod_scgi.