Running as an Apache module

Like the SCGI interface option, running Woof! as an Apache module has the benefit of greatly improved performance compared to CGI. Unlike SCGI, running as an Apache module entails running the Woof! Tcl interpreter within the Apache processes themselves as opposed to within a separate server process. Compared to CGI, responses are an order of magnitude or more faster as it avoids all the startup costs associated with the latter, such as process creation, interpreter initialization, loading of application code and re-establishing database connections.

Running Woof! in this mode requires installation of the mod_websh Apache module written by Ronnie Brunner. This is a part of the Websh application which like Woof! is also a server side web application development environment. However, for portability to other web servers, Woof! does not make use of any Websh features other than the Apache interface.

Because it requires the installation of a non-standard Apache module, this method of running Woof! may not be possible with some service providers. It requires to have full control over your Apache configuration.

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.

Step 1 - install mod_websh

TBD - where to download mod_websh from. For Windows systems, you can download prebuilt binaries from the Woof! download page.

After building, the mod_websh.so module and the associated DLL mod_webshVERSION.dll should be copied to the Apache modules directory. Then add the following line to the httpd.conf to load the module.

LoadModule websh_module modules/mod_websh.so

Step 2 - install Woof!

The next step is to install Woof! for Apache and SCGI using wag.

~/woof-dist> tclsh scripts/wag.tcl install apache websh -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. The file websh_server.tcl will be loaded by the mod_websh module in Apache to create the Tcl interpreter for handling client requests. The other files in the directory, including subdirectories, are intended to be directly served by Apache without going through Woof! as detailed below.

In addition, the directory config/websh will also be created to contain mod_websh configuration. The files here need not be modified but are simply referenced from the Apache configuration files as shown in subsequent steps.

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</pre>

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 mod_websh

The main Apache configuration file httpd.conf has to be edited to pass requests to the mod_websh module.

<Directory "/var/myapp/public">
   AllowOverride All
   Order allow,deny
   Allow from all
   AddHandler websh .tcl
   RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteRule ^(.*)$ websh_server.tcl [QSA,L]
</Directory>

WebshConfig "/var/myapp/config/websh/websh.conf"

The AddHandler registers mod_websh as the handler for Tcl files; in particular, requests for the public/websh_server.tcl file will be handled by it.

The Rewrite directives are needed for the same reason they were required for CGI - we want all requests to be handled by the Woof! without having to specify the handler in the request URL. Without these directives, URL's of the form http://www.mysite.com/websh_server.tcl ... would have to be used to access the Woof! application. The RewriteEngine directive enables URL rewriting. The RewriteRule directive is what channels all URL's to our Woof! mod_websh module. However, we need to make one exception - images, stylesheets and other static files should be served without going through the additional Woof! overhead. The RewriteCond directive takes care of this situation. It stipulates that the following RewriteRule will only have effect if the requested file name does not exist. Thus requests for files within the public directory tree will be served without Woof! being invoked. For other requests, the URL is rewritten as a request for websh_server.tcl resulting in mod_websh handling the request. For more details on how rewriting works, refer to the Apache documentation.

Completing the installation

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