[kpax-devel] Installation and Configuration of mod_lisp

[Sven Van Caekenberghe]

Installation and Configuration of mod_lisp

KPAX is a framework that allows you to write Web Applications in  
Common Lisp that can be deployed in different contexts. The preferred  
production context is to use apache with mod_lisp. KPAX strictly  
separates static from dynamic content. Apache handles static content  
directly, while dynamic content goes through mod_lisp that passes it  
to your common lisp system.

To install and run the Lisp code for KPAX, see elsewhere. This part  
is about installing and configuring apache and mod_lisp to deploy  
KPAX web applications. It might be usefull to first test running your  
webapps under the simpler s-http-server context to make sure the Lisp  
part is OK.

mod_lisp is an apache module to forward request handling from apache  
to arbitrary application servers, in casu KPAX. Please refer to  
general mod_lisp documentation if necessary.

First you need to install mod_lisp from its source file:

$ apxs -i -c mod_lisp.c

this will compile and install the module where apache expects it.

Next you need to change some apache config files, first by loading  
and adding the mod_lisp module
in your main apache config file (httpd.conf) in /etc/httpd/ (or where  
apache expects them)

LoadModule lisp_module libexec/httpd/mod_lisp.so

AddModule mod_lisp.c

Make these additions at the end of the existing LoadModule and  
AddModule directive lists.

We place the rest of the configuration in a seperate file named  
kpax.conf, so we have to include that file in the
main httpd.conf:

Include /etc/httpd/kpax.conf

The contents of the kpax specific include file (the exact location  
could be different on your system) might look like this:

<IfModule mod_lisp.c>

LispServer 127.0.0.1 2001 "kpax"

<Location /kpax/dynamic/>
         SetHandler lisp-handler
</Location>

Alias /kpax/static/ "/my/path/to/kpax-static/"

<Directory "/my/path/to/kpax-static/">
         Options FollowSymLinks
         AllowOverride None
         Order allow,deny
         Allow from all
</Directory>

</IfModule>

So if mod_lisp is present, we configure the lisp server by specifying  
the host address, port and extra identification
string of the kpax server; then we set up two main handlers: one for  
the dynamic content and one for the static content. The default  
location (directory) for static content (for the examples) is the  
directory 'static' in the 'example' subdirectory of the KPAX source  
code distribution. In most cases, the alias directive alone will be  
sufficient.

Finally restart apache using

apachectl restart

In lisp, start KPAX using

KPAX-USER 1 > (start-kpax)
...

And visit a webapp URL like http://localhost/kpax/dynamic/helloworld1  
or http://localhost/kpax/dynamic/pi

Provided you have installed the KPAX examples as described elsewhere.

Both apache and apache2 (mod_lisp and mod_lisp2) are supported. Note  
that KPAX is normally configured to only allow mod_lisp requests from  
an apache running on the same machine (localhost) - this can be  
overridden.

Note that when experimenting with configuration options it is  
sometimes necessary to restart apache or KPAX or both (connections  
between apache's mod_lisp and KPAX are kept alive).


Sven

PS: All feedback is welcome.

--
Sven Van Caekenberghe - http://homepage.mac.com/svc
Beta Nine - software engineering - http://www.beta9.be

"Lisp isn't a language, it's a building material." - Alan Kay