[kpax-devel] Runnning KPAX

[Sven Van Caekenberghe]

Runnning KPAX

KPAX is a framework that allows you to write Web Applications in  
Common Lisp that can be deployed in three different contexts:
  - behind apache using mod_lisp
  - behind portable allegro server
  - standalone using s-http-server
KPAX strictly separates static from dynamic content. In the first  
context, apache handles static content directly, while dynamic  
content goes through mod_lisp that passes it to your common lisp  
system - this is the preferred production setup. In the second and  
third context, both the static and the dynamic content are handled by  
your common lisp system - might be easier during development and is  
certainly easier

There is one internal ASDF system called kpax-core that contains most  
of the framework's code but none of the execution contexts. Three  
ASDF systems corresponding to each of the three contexts, called kpax- 
mod-lisp, kpax-paserve and kpax-s-http-server, allow you to load only  
the code you really need. The main ASDF system called kpax simply  
loads both the kpax-mod-lisp and kpax-s-http-server systems.

There is one additional ASDF system called kpax-examples that loads  
KPAX together with a large number of examples (but not all of the  
examples that ship with the distribution). The examples demonstrate  
and test various features of KPAX.

Once you have installed KPAX as described elsewhere, the best way to  
start is to load the kpax-examples ASDF system, run, try and study them.

The easiest way to run KPAX is using the standalone s-http-server  
context.

CL-USER 1 > (asdf:operate 'asdf:load-op :kpax-examples)
...
CL-USER 2 > (in-package :kpax-user)
...
KPAX-USER 3 > (start-kpax :server-class 's-http-server)
;; S-HTTP-SERVER: Started a new server on port 2001
#<S-HTTP-SERVER :RUNNING 10072E37>

KPAX-USER 4 > (start-web-app :helloworld1)
;; KPAX 20060204T141819 INFO Started #<WEB-APP :HELLOWORLD1 104885A3>
:STARTED

Starting a web application is necessary to host the static content.  
There are two kinds of static content: there is server and webapp  
scoped static content. Most webapps are only using server scoped  
static content. It is sufficient to start one webapp to host all  
server scoped static content for all other webapps. Once you are  
developing interactively, both KPAX itself as well as all webapps  
keep on running and don't have to be manipulated any further.

Now vist the URL http://localhost:2001/kpax/dynamic/helloworld1

The following output will appear where *standard-output* goes to  
(probably your Common Lisp listener):

;; S-HTTP-SERVER: [1] Handling #<S-HTTP-SERVER:HTTP-REQUEST GET "/ 
kpax/dynamic/helloworld1" 100A776F>
;; S-HTTP-SERVER: Running KPAX s-http-server-handler
;; KPAX 20060204T141828 INFO handling /kpax/dynamic/helloworld1
;; KPAX 20060204T141828 INFO created new session 7PD7MUCY1YBY  
[1014097705201358350]
;; KPAX 20060204T141828 INFO replied 552 bytes with status OK
;; S-HTTP-SERVER: [1] Handling #<S-HTTP-SERVER:HTTP-REQUEST GET "/ 
kpax/static/nx.css" 100B3743>
;; S-HTTP-SERVER: Serving #P"/Users/sven/.asdf-install-dir/site/kpax/ 
example/static/nx.css"
;; S-HTTP-SERVER: [2] Handling #<S-HTTP-SERVER:HTTP-REQUEST GET "/ 
kpax/static/helloworld1/kpax-movie-poster.jpg" 100BFEFF>
;; S-HTTP-SERVER: Serving #P"/Users/sven/.asdf-install-dir/site/kpax/ 
example/static/helloworld1/kpax-movie-poster.jpg"
;; S-HTTP-SERVER: [3] Handling #<S-HTTP-SERVER:HTTP-REQUEST GET "/ 
favicon.ico" 100C28A7>
;; S-HTTP-SERVER: [3] No handler found for #<S-HTTP-SERVER:HTTP- 
REQUEST GET "/favicon.ico" 100C28A7>

As you can see, there are two kinds of logging going on: both KPAX  
itself as well as S-HTTP-SERVER are logging what they are doing. Once  
you have static content hosting debugged, you might want to switch of  
S-HTTP-SERVER logging:

KPAX-USER 5 > (setf (s-http-server:get-log-stream (get-s-http-server  
*web-app-server*)) nil)

There is one special webapp called PI that is somewhat like a debug  
interface to KPAX, to access it visit the URL http://localhost:2001/ 
kpax/dynamic/pi

Log in using the username 'admin' and the password 'trustno1'. The PI  
webapp shows a list of all available web applications.

Out of the box, KPAX runs in debug mode which means that all errors  
(unhandled conditions) result in the debugger being invoked in your  
running common lisp system. Clicking on one of the inspect buttons  
will show an inspector in your running Lisp environment.

Running KPAX under mod_lisp is even easier, just call #'START-KPAX.  
However, apache and mod_lisp have to be configured first (see  
elsewhere).

Running KPAX in the context of portable allegro server is left as an  
exercise (but is similar to the s-http-server context).


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