WebKit Install Guide

Table of Contents


WebKit provides an application server that runs on both UNIX and Windows as a persistent application (i.e., an application that stays running over the span of multiple requests).

This install guide takes you through the installation process while showing you what options are available and how you would use them. There are notes for specific operating systems and web servers preceded with tags such as UNIX, WinNT, IIS, etc.





Quick Start

Posix (Linux, BSD, etc)

If you just want to get to a working configuration fast, and your setup is fairly conventional, here's a minimal set of instructions for Posix systems:

$ cd /path/to/Webware/
$ python install.py
(enter password, etc)
$ cd WebKit/Adapters/wkcgi
$ make
$ cp wkcgi /path/to/cgi-bin/wkcgi.cgi
$ cd ../..
(you're now in WebKit/)
$ ./AppServer


You should now be able to go to your browser and open up the URL for wkcgi.cgi. (see above where you copied wkcgi. A typical URL might be http://localhost/cgi-bin/wkcgi.cgi). The wkcgi.cgi program connects to the AppServer -- Webware isn't a CGI script, but a small CGI script can be used as a gateway to the AppServer (you can't normally connect to the AppServer itself).

If you get an Internal Error, the most likely case is you can't run CGI scripts wherever you put wkcgi.cgi -- check your error logs (often in /var/log/httpd/error_log, or replace httpd with apache). If it takes a long time to get an error message, or you get a message about not being able to connect to the AppServer, then you probably forgot to start the AppServer.


(@@: someone needs to check this)

Here's what to do on Windows:

> cd \path\to\Webware
> python install.py
(enter password)
> cd WebKit
> AppServer.bat

\path\to\cgi-bin should be wherever Apache looks for cgi-bin scripts. (@@: default location?)

This copies the adapter that that Apache can find it, and starts the AppServer. The AppServer is a program that must be running anytime you want to access your servlets or PSP files.

You should now be able to go to your browser and open up http://localhost/cgi-bin/WebKit.exe -- the WebKit.exe program connects to the AppServer -- Webware isn't a CGI script, but a small CGI script can be used as a gateway to the AppServer (you can't normally connect to the AppServer itself).

If you get an Internal Error, the most likely case is you can't run CGI scripts wherever you put WebKit.exe -- check your error logs. If it takes a long time to get an error message, or you get a message about not being able to connect to the AppServer, then you probably forgot to start the AppServer.



Webware of course requires Python. It has been tested with Python 2.0, 2.1, and 2.2. Python 1.5.2 isn't supported anymore. If you get an error message about the version, you're probably unwittingly running the wrong version of Python. Change the AppServer or AppServer.bat scripts, giving the full path to the correct Python interpreter.



Web Server

While Webware includes an experimental built-in web server, for any realistic situation you will want to use Webware in concert with another web server.

Any web server that supports CGI should be possible to use with Webware. Apache is the best supported platform, both on Posix and Windows systems. There is some experimental support for Xitami. For all other web servers (IIS included) you should expect to use CGI to interface with the AppServer.


Apache is the best supported web server, both on Posix and Windows systems. The mod_webkit is the fastest way to connect to Webware, and is only supported for Apache. CGI is also available to Apache users through wkcgi. For Windows users compiled versions of mod_webkit and wkcgi (named WebKit.exe) are also available. There are also other adapter options, see Adapters.

Most of the Webware developers use Apache.



For IIS 4.0, configure it to handle PATH_INFO and PATH_TRANSLATED according to the CGI specification, by running the following command:

> cscript adsutil.vbs SET W3SVC/1/AllowPathInfoForScriptMappings 1

This is lightly documented in http://support.microsoft.com/support/kb/articles/Q184/3/20.ASP

CGI adapter, written in C, is available in WebKit/Adapters/wkcgi/WebKit.exe. The standard Python CGI adapter also works, but you must either configure IIS to run Python CGI scripts, or you must use Gordon McMillan's Standalone utility (part of his Installer package) or some other program to create an executable from the Python.




The PyWX project aims to meld Python and AOLserver and as part of that, they created an AOLserver "stay resident" WebKit adapter for tighter integration. More information can be found at http://pywx.idyll.org . If you find that this adapter does not work with the latest release of Webware, please notify the PyWX project.



Other Servers

Other servers should work using a CGI adapter.

Built-In Web Server

There is a built-in web server in Webware. It's somewhat experimental, and certainly not meant for production use. It can be run in a separate process from Webware, or in the same process.

To run the server in a separate process, run the script WebKit/Adapters/HTTPAdapter.py -- it takes the options --port=N, --host=IP and --daemon. This will start a small Python-based web server, that will forward all requests to the Webware AppServer (so you must also start the AppServer!).

The run the server in the same process, edit the AppServer or AppServer.bat script, replacing ThreadedAppServer with NewThreadedAppServer. Then start the AppServer like:

# Posix:
$ ./AppServer http
# Windows:
> AppServer.bat http

There isn't much in the way of configuration for these servers -- they're still experimental.

Webware Version

Unless you just downloaded Webware (and therefore WebKit), you should check to see if you have the latest version. This version you are looking at is 0.8.1. You can check for the latest version at http://webware.sf.net.

If you're feeling adventurous, you can get the latest in-development source code from the public repository. Instructions are located at the Webware CVS page. You can find more information about CVS in general at http://www.cvshome.org. The CVS version of Webware is generally fairly stable.

Operating Systems

WebKit actively supports Posix (Linux, BSD, Mac OS X, Solaris, etc) and Windows (95/98/NT/2000), and their various flavors.


What follows are some OS specific notes:

Windows 9x:



  • '/All/Web'
  • 'C:/All/Web'
  • 'C:\\All\\Web'
  • 'C:\All\Web'


Installing Webware





The WebKit architecture involves three main entities at the top level:




The key to installing WebKit is to get the web server and app server talking to each other. For this purpose, you must use a WebKit adapter.



$ cd path/to/Webware/WebKit
$ sudo -u webkit ./AppServer


  • Cache
  • ErrorMsgs
  • Logs
  • Sessions

The easiest way to do this is to make these directories writeable by all (on UNIX, that would be cd Webware/WebKit; chmod -R a+rwX Cache ErrorMsgs Logs Sessions).




There are several adapters for Webware. However, it is highly recommended that you either use wkcgi or mod_webkit. Mod_webkit is the fastest adapter, but requires you to use Apache and usually to have root access to the computer. Wkcgi uses CGI, and so is easy to install. Because it's small and written in C, wkcgi is still very fast.

All the adapters:

These adapters are not really recommended:

CGI-based Adapters



wkcgi, WebKit.exe

wkcgi is a CGI-based adapter written in C. It's very small and is good at it's one and only job of connecting to the AppServer. While a CGI-based adapter is the only option for some configurations, wkcgi is not a bad compromise -- it's quite fast. The only other adapter that is enough faster to be interesting is mod_webkit. You should choose one of these options.


$ make





Host = localhost
Port = 8086
MaxConnectAttempts = 10
ConnectRetryDelay = 1

(@@ special Windows instructions?)

Python CGI Adapter


Otherwise, follow the instructions for wkcgi. There is no configuration, and WebKit.cgi should be able to find the host and port of the AppServer automatically.




The source code and a README file describing how to configure and build mod_webkit are located in the Webware/WebKit/Adapters/mod_webkit directory.

There are two versions, mod_webkit and mod_webkit2 -- mod_webkit2 is for use with Apache 2.0. The other version is for Apache 1.3. Each is in its own directory.

Posix Installation

To install:

$ cd /path/to/Webware/WebKit/Adapters/mod_webkit # or mod_webkit2 for Apache 2.0 $ make $ make install


  • /usr/bin/apxs
  • /usr/local/bin/apxs
  • /usr/local/sbin/apxs





Windows Installation

Copy WebKit/Adapters/mod_webkit/mod_webkit.dll (or the file from mod_webkit2 if you are using Apache 2) into your module directory for Apache (usually C:\Program Files\Apache Group\Apache\modules).

Edit httpd.conf to include the line:

LoadModule webkit_module modules/mod_webkit.dll

As well adding the configuration below.

Apache Configuration

You must also add a line like this to your httpd.conf:

<Location /WK>
    WKServer localhost 8086
    SetHandler webkit-handler

Then any URL that starts with /WK/ will be directed to the AppServer on 8086. You can also use:

AddHandler psp-handler .psp


Action py-serverpages /WK/
AddType py-serverpages .py

Which will run Python servlets from any location.



LRWP Adapter (for Xitami)






Note that to date, we have only gotten this to work on UNIX.




This has been tested on both UNIX and Windows. On Windows you should use mod_python 2.7.4 or later because there is a bug in earlier versions of mod_python for Windows that can cause Apache to crash or return incorrect responses under heavy load.




This adapter is similar to ModPython, but written for the mod_snake apache module. mod_snake is another method of embedding a python interpreter into apache. mod_snake may be preferable over mod_python if you need to work with Apache 2.0.






If you use OneShot, do not launch the AppServer separately.



Renaming Adapters


Adapter Problems (not CGI)











Activity Log

Three options let you control:


See Configuration in the User's Guide for more information.

E-mail Errors


See Configuration in the User's Guide for more information.











Creating a Working Directory


$ python Webware/bin/MakeAppWorkDir -l --cvsignore -c context DIRECTORYNAME

This will create a directory DIRECTORYNAME that will contain a directory structure for your application. The options are:

Create a lib/ directory which will be added to the Python path.
Create .cvsignore files.
Use CONTEXTNAME for the application context instead of MyContext (there will be a directory CONTEXTNAME/ in the work dir).

When you do this, you'll see this directory structure:

404Text.txt  Cache/       ErrorMsgs/   Logs/        WebKit.cgi   lib/
AppServer*   Configs/     Launch.py    Sessions/    context/

Here's what the files and directories are for:

The text when a page is not found (actually the HTML from <body> to </body>).
Configuration files for the application. These files are taken from WebKit/Configs, but are specific to this application/AppServer.
Called by the AppServer script to launch the AppServer.
Logs of accesses.
The directory (given with the -c switch) for your default context. This is where you put your servlets.
An application-specific library package, created if you give the -l switch. Import from this like from lib.SitePage import SitePage

AppServer Notes


Stopping the App Server



On UNIX, a running appserver may be stopped from a terminal by typing ./AppServer stop.


On UNIX if you don't have access to the terminal window of the app server (perhaps because you used rlogin, telnet or ssh to remotely access the machine), and "AppServer stop" doesn't work, you can use ps -ax | grep AppServer to get the pid and kill <pid> to effect a Control-C.

Reloading Servlets




The line:

'AutoReload':      0,



Launching the AppServer at UNIX boot up

The script WebKit/webkit is a UNIX shell script launching WebKit at boot time through the standard "init" mechanisms.

To start WebKit at boot time, make the necessary variable modifications in the script, like so:



Now put this script in /etc/rc.d/init.d and do this:

# cd /etc/rc.d/init.d
# chmod a+rx webkit
# chkconfig webkit reset

That takes care of getting it started for future boots, but this first time you need to jump start it:

# ./webkit start

You can use chkconfig to put this in at the right runlevels. By default, it is set up properly for the default Apache install, which is to say that the AppServer starts up before Apache and shuts down after Apache.

By default, the script is in runlevels 2-5 at start priority 75, stop priority 25.


Now put this script in /etc/init.d and do this:

# cd /etc/rc.d/init.d
# chmod a+rx webkit
# update-rc.d webkit defaults


# ./webkit start

You can use update-rc.d to put this in at the right runlevels. See man update-rc.d for more information.

Other Sytems

@@ someone check this

You should put the webkit script either in /etc/rc.d/init.d/ or /etc/init.d/ depending on what you system has. For the example we'll assume /etc/rc.d/init.d/. You should then make symbolic links, like:

# cd /etc/rc0.d
# ln -s ../rc.d/init.d/webkit K75webkit
(repeat for rc1.d and rc6.d)
# cd /etc/rc2.d
# ln -s ../rc.d/init.d/webkit S25webkit

Additional Notes

You will notice the variables PYTHONPATH and PYTHON_PATH which are both set to blank. The first prevents inheriting PYTHON_PATH from the environment (as security paranoia). You can comment this out if you prefer to inherit the Python path. The second allows you specify additional Python path components (regardless of whether or not you inherited the path).

Running ThreadedAppServer as a Windows NT/2000 Service


ThreadedAppServerService requires the Python win32all extensions to have been installed.

To see the options for installing, removing, starting, and stopping the service, just run ThreadedAppServerService.py with no arguments. Typical usage is to install the service to run under a particular user account and startup automatically on reboot with:

> python ThreadedAppServerService.py --username mydomain\myusername \
  --password mypassword --startup auto install

(@@: can you use a to continue a line in Windows?)

Then, you can start the service from the Services applet in the Control Panel, where it will be listed as "WebKit Threaded Application Server". Or, from the command line, it can be started with either of the following commands:

> net start WebKit
> python ThreadedAppServerService.py start

The service can be stopped from the Control Panel or with:

> net stop WebKit
> python ThreadedAppServerService.py stop


> python ThreadedAppServerService.py remove


Bad Marshal Data





That requires that web server and app server are set up to talk to each other. And that's what the next section is all about...