Shared CGI on Apache

Assumptions

This scenario makes the following assumptions:

• The application is being served in a shared hosting environment so we have no control over the main Apache configuration files.
• The hosting service provider has created a virtual server for our domain www.mysite.com and has set the our site document root to point to public_html in our home directory.
• The service provider has enabled the Apache mod_rewrite and mod_cgi modules (this is usually the case) and has also enabled .htaccess file support for per-directory configuration.
• The Woof! application is only one part of our own site with its root URL http://www.mysite.com/myapp.

Again, we use the Common Gateway Interface (CGI) adapter. CGI has the advantage that most hosting service providers have already configured their servers for CGI access but not necessarily for any of the more efficient methods we describe in later sections.

Step 1 - install Woof!

The first step is to install Woof! for Apache and CGI using installer - installation utility as described in the previous section.

~/woof-dist> tclsh scripts/installer.tcl install apache cgi -installdir ~/myappdir

See the previous section for details on what this command does. The only difference here is that the install target directory is myappdir under your home directory.

Step 2 - Route requests for /myapp URL tree

The document root for our virtual server is set to point to ~/public_html so any requests to http://www.mysite.com will be targeted to that directory. Since the root for the Woof! application will be http://www.mysite.com/myapp we create a link as follows:

~/woof-dist> ln -s ~/myappdir/public ~/public_html/myapp

All requests to http://www.mysite.com/myapp will now be routed to ~/myappdir/public. Note that the link was created to the public subdirectory of our Woof! installation, not to the Woof! root directory myappdir. This is because only the content under public should be exposed to the web server for security reasons. This is also the reason why we did not directly put the Woof! installation under the virtual server's document root.

When the Woof! application is not rooted at / we also need to tell Woof! the application root URI, /myapp in our case. For this purpose, we add the line below to the Woof! application configuration file, which in our example will reside at ~/myappdir/config/application.cfg.

set url_root /myapp

This will allow Woof! to correctly decode and generate URL's for the Woof! application.

Step 3 - configure CGI

The next step is to configure Apache to run our cgi_server.tcl script whenever the client requests a URL under the application root URL. Because this is a shared host, the main Apache configuration file cannot be modified. Instead we have to modify the .htaccess file in ~/myappdir/public directory (which is the document root for our virtual host). See the Apache documentation for details about this file but in a nutshell, this file allows a subset of Apache directives to be applied to the directory where the file resides.

The content of the .htaccess file are shown below.

AddHandler cgi-script .tcl
Options +ExecCGI
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ cgi_server.tcl/$1 [QSA,L]

# In case Woof! experiences terminal errors
# Instead of displaying this message you can supply a file here which will be rendered instead
# 
# Example:
#   ErrorDocument 500 /500.html
ErrorDocument 500 "<h2>Application error</h2>Woof application failed to start properly"

The content above is very similar to the changes made to the httpd.conf file in the previous section. See the description there for an explanation of the directives.

Completing the installation

That completes Apache configuration. You can now move on to completing the installation.