Installing & Configuring Webware on Linux

I recently upgraded a pre-existing installation of Webware/WebKit on one of our Linux webservers at work, and installed Webware/WebKit on a system with no previous installation on another server.

I kept a detailed record of the installation procedures so it would be easier for me to remember exactly what to do next time I need it.

System Specs

Red Hat Linux 7.0 on x86
Apache 1.3.14
Python 2.2.1c1
Webware 0.7beta2

SuSE Linux 7.1 on x86
Apache 1.3.14
Python 2.1
Webware 0.6

Got a different Linux distro or a different version of Webware? No problem, the installation & configuration procedure should be the same.

You must have Python (v2.0 or above) pre-installed with threading enabled, which is the default for v2.x.

To ensure threads are enabled:

$> python

Python (version) (build date) (compiled-by info)
Copyright (year) Stichting Mathematisch Centrum, Amsterdam
>>> 
>>> import thread

... if you don't get an error, you're good to go. CTRL+d to exit the Python interpreter.

Download, Unpack & Install

Just so you know... green text is stuff you type (changing paths to fit your system's setup), and red text is stuff that you'll see on the screen.

First, download the Webware tarball from http://webware.sourceforge.net/, and place it in the desired directory on your system, keeping in mind that unpacking the archive file will create a "Webware" subdirectory therein (for me, that was /opt).

You may have to perform some of these steps as root, depending on your system setup.

Ready? Unpack the archive (assuming v0.6):

box:/opt $> tar -xzvf Webware-0.6.tar.gz

... which creates the "Webware" subdirectory. Get on in there, and run the install script:

box:/opt $> cd Webware
box:/opt/Webware $> python install.py

... which will churn for a bit while installing. If you're installing Webware v0.7 (or above?), the install script will ask you for an administrative password. You can change it later, and that procedure is covered below.

At this point, I should make the distinction between "Webware" and "WebKit". "WebKit" is a subset of the entire body of functionality named "Webware"; and, so far, WebKit is the only piece of Webware that I've used.

The RunTime Working Directory for WebKit

After the installation is done, it's a good idea to use WebKit's "working directory" option; you'll be able to keep your Python modules in a separate directory that will not be affected by later Webware/WebKit installations or upgrades. The script is located in the "bin" directory under your Webware directory (for me, that was /opt/Webware/bin).

box:/opt/Webware $> cd bin
box:/opt/Webware/bin $> ./MakeAppWorkDir.py /path/to/workingdir

You can either let the script create the directory (/path/to/workingdir) for you, or you can do so yourself beforehand; it doesn't matter. I created the directory first (mine was /opt/gary/webware), so here's the script's output (keep an eye on the <<, I'll cover them below):

Creating directory tree at /opt/gary/webware
        /opt/gary/webware already exists.
        /opt/gary/webware/Cache created.
        /opt/gary/webware/Cans created.
        /opt/gary/webware/Configs created.
        /opt/gary/webware/ErrorMsgs created.
        /opt/gary/webware/Logs created.
        /opt/gary/webware/Sessions created.

Copying files.
        /opt/gary/webware/404Text.txt
        /opt/gary/webware/AppServer
        /opt/gary/webware/AppServer.bat
        /opt/gary/webware/OneShot.cgi<<
        /opt/gary/webware/WebKit.cgi<<

Creating launcher scripts.
        /opt/gary/webware/Launch.py created.
        /opt/gary/webware/NTService.py created.
        /opt/gary/webware/OneShot.cgi updated.<<
        /opt/gary/webware/WebKit.cgi updated.<<

Creating default context.<<
Updating config for default context.<<

Congratulations, you've just created a runtime working directory for
Webware.  To start the app server you can run these commands:

        cd /opt/gary/webware
        ./AppServer

Copy WebKit.cgi to your web server's cgi-bin directory, or
anywhere else that it will execute CGIs from.  Then point your browser
to http://localhost/cgi-bin/WebKit.cgi/ .  The page you
see is generated from the code in the MyContext directory and is
there for you to play with and to build upon.

If you see import errors, then you may need to modify the permissions
on your Webware directory so that the WebKit.cgi script can
access it.

There are also several adapters in the Webware/WebKit directory that
allow you to connect from the web server to the WebKit AppServer
without using CGI.

Have fun!

So, as you can see, this script pretty much does everything for you... except for starting the AppServer. You gotta do that on your own. More on that below.

Configuring the CGI Scripts: You Don't Have To!

Unlike previous versions of WebKit, the script pre-configures your ".cgi" scripts to use the newly-installed Webware and WebKit runtime directories for you; all you have to do is copy them into your live CGI directory.

On both the SuSE and RedHat machines, Apache was installed using the default package installation from the CDs.

Live CGI Directories:
SuSE: /usr/local/httpd/cgi-bin
RedHat: /var/www/cgi-bin

Apache Configuration File:
SuSE: /etc/httpd/httpd.conf
RedHat: /etc/httpd/conf/httpd.conf

So, assuming SuSE:

box:/opt/Webware/bin $> cd /usr/local/httpd/cgi-bin
box:/usr/local/httpd/cgi-bin $> cp /opt/gary/webware/WebKit.cgi ./
box:/usr/local/httpd/cgi-bin $> cp /opt/gary/webware/OneShot.cgi ./

Note, also, that the script creates a "default context" for you, and updates the WebKit configuration to reflect it. More on this in a bit.

Start 'em Up!

Before we start serving up WebKit-based content... a word regarding permissions. If you're confident that you've set up Webware/WebKit properly, but things just don't seem to be working correctly... always remember to check your user/group ownership and permissions. Check them for your install stuff (e.g., /opt/Webware), your runtime directory (e.g., /opt/gary/webware), and especially consider that the default user/group that Apache runs under is user "wwwrun" and group "nogroup". Also consider your Python path. I'll cover that at the end, as it was an obvious oversight on my part during the post-server-configuration tinkerings.

Enough of that, eh? For now, let's check the CGI-based interface; we'll look at the faster mod_webkit Apache module immediately afterward. Start the AppServer from your runtime directory.

box:/usr/local/httpd/cgi-bin $> cd /opt/gary/webware
box:/opt/gary/webware $> ./AppServer &

Note: The ampersand (&) is important, since it tells to OS to run the process as a "background" process; it will allow you to regain the command line and logout without ctrl-c'ing and interrupting the AppServer process itself.

After running "./AppServer &", you'll see a big text scroll:

box:/opt/gary/webware # WebKit AppServer 0.6
part of Webware for Python
Copyright 1999-2001 by Chuck Esterbrook. All Rights Reserved.
WebKit and Webware are open source.
Please visit:  http://webware.sourceforge.net

... lots of crazy stuff here ...

Listening on ('127.0.0.1', 8086)
Creating 10 threads..........
Ready

This is the good stuff. If you get a Python error upon running "./AppServer &", that usually(?) means you have another process running on port 8086 (WebKit's default). If it's Zope for some reason... backup your ~/Zope/Extensions directory, your ~/Zope/var/Data.fs file, and rm -rf ~/Zope. That's a joke. Don't really do that if you don't wanna. (Sorry, DigiC.)

Now, provided no error message, if you open your favorite browser and visit:

http://whatever/cgi-bin/OneShot.cgi/

... or:

http://whatever/cgi-bin/WebKit.cgi/

... where "whatever" is "localhost" if you're ON the box running Apache/WebKit, or the "hostname.domain.tld" or straight-out IP address of the box you're remotely accessing.

If there aren't any ownership, permissions, or Python path issues, you should be presented with the standard WebKit welcome message.

If everything's cool, then shut down the AppServer so we can install the mod_webkit Apache module:

box:/opt/gary/webware $> ./AppServer stop &

If you get an error saying the "appserverpid.txt" file can't be found... then I'm not the only one! For some reason, mine was looking in /opt/Webware/WebKit, when my runtime directory was /opt/gary/webware... which happened to contain the elusive "appserverpid.txt" file instead.

No big, you can always check the "appserverpid.txt" file in your runtime directory to get the process ID, and kill the process... Kinda' like this:

box:/opt/gary/webware $> kill `cat appserverpid.txt`

Again, you might have to do that as root.

Installing the mod_webkit Apache Module

Your alternative to using CGI, and greatly increasing your server's performance is to use the mod_webkit Apache module. The installer is located in the WebKit/Native/mod_webkit directory of your default Webware installation (for me it was /opt/Webware/WebKit/Native/mod_webkit). So go there.

box:/opt/gary/webware $> cd /opt/Webware/WebKit/Native/mod_webkit

Before you compile the installer, be sure to check the "README" file for info on how to configure your Apache server to use the module (see below). Now, you've gotta have a C compiler installed on your system, but chances are you've got gcc so no biggie, eh? Update: You'll also need apxs on your system, usually available with the apache developer tools.

box:/opt/Webware/WebKit/Native/mod_webkit $> make

... some stuff...

box:/opt/Webware/WebKit/Native/mod_webkit $> make install

... some stuff...

[activating module `webkit' in (config file location)]

Configuring Apache to Use mod_webkit

Now, you gotta edit your Apache configuration file. Mine is located at /etc/httpd/httpd.conf on the SuSE box, and at /etc/httpd/conf/httpd.conf on the RedHat box. Didja' check that README file before? Even if you didn't, I'm in no way an Apache expert... but it's totally easy... so grab your favorite editor (I use "pico" 'cuz I'm all hardcore and shit ;) and let's dig in.

Once you're in, find the spot where the LoadModule directives are grouped and add this one:

LoadModule webkit_module modules/mod_webkit.so

Then find the spot where the AddModule directives are grouped and add this one:

AddModule mod_webkit.c

Then drop in your Location directive (I put mine right after the directive that specifies the CGI root directory, to ensure it's not unwittingly nested inside another directive).

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

Note that whatever you specify as <Location /whatever> is going to be part of the URL visited by your users. For example, if you use "/webkit", then your dynamic WebKit stuff will be accessed through:

http://hostname.domain.tld/webkit

Okay... being the trooper you are (we're almost done!), restart Apache.

On the SuSE box:

box:wherever $> /etc/rc.d/apache restart &

On the RedHat box:

box:wherever $> /etc/rc.d/init.d/httpd restart &

If you killed your WebKit AppServer before, you should start it up again. Then, open your favorite browser and visit:

http://whatever/webkit

... where "whatever" is "localhost" if you're ON the box running Apache/WebKit, or the "hostname.domain.tld" or the straight-out IP address of the box you're remotely accessing.

If there aren't any ownership, permissions, or Python path issues, you should be presented with the standard WebKit welcome message, and a lot quicker than your CGI tests above.

That Damned Python Path

You're getting "Internal Server Errors"? Try adding your WebKit working directory to your Python path. I did it by adding a "webware.pth" file to my /usr/lib/python/site-packages directory that contains the path to that runtime directory, e.g., /opt/gary/webware .

Configure Your Default Context!

Remember when I mentioned that the installation process created a "MyContext" default context? Of course you do. You can change that if you want to. Simply edit the Application.config file in the Configs directory under your WebKit runtime directory (e.g., /opt/gary/webware/Configs/Application.config).

The whole Application.config file is just a big Python dictionary, so do your thing and edit it.

Note that the first key:value pair is the password. If you don't like the password you entered during the installation, change it here.

Now, add a key:value pair in the value of the 'Contexts' key reflecting what you want to call the directory from which you'll store your Python modules (.py files) as such:

'whatever': 'whatever',

Then, change the 'default' key to what you just specified...

'default': 'whatever',

... and create a directory under your WebKit runtime directory with the same name... remember it's all Case-Sensitive.

Now you're ready to start writing some Python code. Let your brain rest for a minute. Go get a beer, find a hockey game on TV, and read the "Programming Your Own WebKit Application" page after the end of the third period.