Installation steps for OS X Server 10.3.4 (which runs on our XServe at work), are identical to those for standard OS X 10.3.4. 02-15-05 Update: The following steps work perfectly under OS X 10.3.8 (incl. OS X Server) running Apache 1.3.33.

OS: OS X 10.3.4 & 10.3.8 (Panther)
Webserver: Apache/1.3.29 & 1.3.33 (Darwin)
Python: 2.3
Webware: 0.8.1

OS: OS X 10.4.2 (Tiger)
Webserver: Apache/1.3.33 (Darwin)
Python: 2.3.5
Webware: 0.8.1

Note 1: In OS X 10.3.x (and later), the pre-installed Python fulfills version and threading requirements for the installation of Webware.

Note 2: Some of the steps here (such as creating directories in the protected /usr/local directory and changing ownership of files and directories) must be done as root, so make sure whatever regular user is going to do most of the work is also allowed to "Administer" the computer (in the Security pane of that User's account in System Preferences).

Update: If you plan to install Webware in your own home directory, the only steps that require root (using sudo) are:

• Copying the .cgi script to the CGI-Executables directory
• The "make install" step for mod_webkit
• Editing the httpd.conf file
• Restarting Apache
• Creating the "appserver.plist" file in mach_init.d

Note 3: If you plan to use WebKit's Apache-native module mod_webkit, you will have to have Apple's Developer Tools (a.k.a. XCode) installed on your system, as the installation procedure requires a gcc compiler. The default OS X 10.3.x (and later) install already includes apxs, which is also required for mod_webkit installation.

Download the latest version of Webware from webwareforpython.org. In the following examples, I've chosen to install everything in the /usr/local directory. Of course, you'll have to change the directions here to account for your installation location of choice, and your username on the system.

For clarity: All command prompts in typed examples will be represented as:

imac1:~ garyp$ 

... so ignore them, basically. I'll include proper "cd" commands to make sure you understand in which directories things are being done.

Copy the tarball to the desired location and unpack the archive.

imac1:~ garyp$ cd /usr/local
imac1:~ garyp$ sudo cp ~/Webware-0.8.1.tar.gz ./
imac1:~ garyp$ sudo tar xzf Webware-0.8.1.tar.gz 

That will create a directory named Webware-0.8.1. (still in /usr/local)

imac1:~ garyp$ ls -l
total 1480
drwxr-xr-x  20 1001   100       680  1 Aug  2003 Webware-0.8.1
-rw-r--r--   1 garyp  wheel  755544  2 Aug 12:36 Webware-0.8.1.tar.gz

At this point, it's okay to delete the tarball. (still in /usr/local)

imac1:~ garyp$ rm Webware-0.8.1.tar.gz

Change the ownership of your new directory to cut down on the number of things you'll have to do as root. The '-R' flag will also change ownership of everything the directory contains, recursively. (still in /usr/local)

imac1:~ garyp$ sudo chown -R garyp:wheel Webware-0.8.1/

Drop into the directory and perform the initial installation. During the installation, you will be asked for an administrative password. This IS NOT the administrative password for your system, it is merely a password to access WebKit's administration pages after everything is up and running.

imac1:~ garyp$ cd /usr/local/Webware-0.8.1/
imac1:~ garyp$ python install.py

You'll then get a huge scroll [shown here], which pauses only to ask you for the aforementioned password. Now, go make a "runtime" directory and make sure its ownership will allow you to dump a lot of stuff inside. (While the script will attempt to create the directory for you, I elected to have my runtime dir. under /usr/local, which requires root permission to create a new directory, so the script may fail without manually creating the runtime dir. ahead of time.)

imac1:~ garyp$ cd /usr/local                  
imac1:~ garyp$ sudo mkdir webwarerun
imac1:~ garyp$ sudo chown -R garyp:wheel webwarerun/

Head into the bin directory under your Webware installation and call the "MakeAppWorkDir" script, passing the name of your previously-created runtime directory as the argument.

imac1:~ garyp$ cd /usr/local/Webware-0.8.1/bin
imac1:~ garyp$ ./MakeAppWorkDir.py /usr/local/webwarerun/

You'll get another scroll [shown here] including instructions on what to do next, starting with copying the WebKit.cgi CGI script (which is already configured for you and resides in your runtime directory) into the proper location, which is owned by root in OS X.

imac1:~ garyp$ cd /Library/WebServer/CGI-Executables/
imac1:~ garyp$ sudo cp /usr/local/webwarerun/WebKit.cgi ./

Next, start up Webkit's application server in your runtime directory. The ampersand (&) ensures that it runs as a background process.

imac1:~ garyp$ cd /usr/local/webwarerun/
imac1:~ garyp$ ./AppServer &

Once the application server launches, you'll see another big scroll [shown here].

Now, launch a browser and load the URL: http://localhost/cgi-bin/WebKit.cgi to see if things are working. If you do not receive and "Internal Server Error", you should see the "Welcome to Webware!" page.

All the information in the scroll, and the capabilities of the page you're presented with in the browser are all based on WebKit's default installation and contexts. You'll need to customize the configuration and contexts to your liking and, start developing your own dynamically-generated information in Python.

If that's all you want, then you're done with installation. Except: All your WebKit pages will have to go through the WebKit.cgi adapter, and you will have to manually start the application server each time your system starts up.

Back to the command line. If your application server is still running from the WebKit.cgi test above, press enter once to regain the command line (the AppServer was run as a background process, remember?). Stop the application server:

imac1:~ garyp$ cd /usr/local/webwarerun/
imac1:~ garyp$ kill `cat ./appserverpid.txt`

Note: In the above command, those are single backward quotes. The "./AppServer stop" command does not work as expected, because it looks for the process ID text file in a location where it doesn't exist. I've found the best way to reliably kill the application server process is to issue the above command in the runtime directory.

WebKit comes with the ability to use Apache-native modules for either 1.x or 2.x series Apache webservers. These modules offer a considerable performance boost over the WebKit.cgi adapter, and provide a bit of flexibility in URL-space. In OS X 10.3.4, the default Apache installation is 1.3.29, so the following examples work with the 1.x series adapter, mod_webkit.

As Note 3 above describes, you will need to have Apple Developer Tools installed on your system to use the mod_webkit module, because the gcc compiler is required to build it.

Under your installation directory (not the runtime directory), drop into the WebKit/Adapters/mod_webkit subdirectory, and take a look at the "README" file.

imac1:~ garyp$ cd /usr/local/Webware-0.8.1/WebKit/Adapters/mod_webkit
imac1:~ garyp$ less README

The README will provide simple instructions on how to build and install the adapter.

Run the "make" command: (still in /usr/local/Webware-0.8.1/WebKit/Adapters/mod_webkit)

imac1:~ garyp$ make

[small scroll of compile messages]

Then, as root, run the "make install" command: (still in /usr/local/Webware-0.8.1/WebKit/Adapters/mod_webkit)

imac1:~ garyp$ sudo make install

/usr/sbin/apxs -i -a -n 'webkit' mod_webkit.so
[activating module `webkit' in /private/etc/httpd/httpd.conf]
cp mod_webkit.so /usr/libexec/httpd/mod_webkit.so
chmod 755 /usr/libexec/httpd/mod_webkit.so
cp /private/etc/httpd/httpd.conf /private/etc/httpd/httpd.conf.bak
cp /private/etc/httpd/httpd.conf.new /private/etc/httpd/httpd.conf
rm /private/etc/httpd/httpd.conf.new

Note the line stating "activating module" in the Apache config. file.

Update 8/29/07: Installed Webware 0.9.4 on an Intel iMac (running Apache 1), and it did not automatically add the proper LoadModule and AddModule directives to the Apache config. file. See below for the proper syntax.

Although the "make install" step does alter the Apache config. file, still more changes are required to fully utilize the mod_webkit module. OS X 10.3.4's Apache config. file resides at /etc/httpd/httpd.conf, but verify this location by running:

imac1:~ garyp$ httpd -V

... and look for the line starting "-D SERVER_CONFIG_FILE". Locate and edit the Apache configuration file.

imac1:~ garyp$ cd /etc/httpd
imac1:~ garyp$ sudo pico httpd.conf

I use pico because I'm all hardcore and shit. You will use your editor of choice.

Update 8/29/07: Search the config. file for "webkit". If using Apache 1, look for LoadModule and AddModule lines like those shown here. If they don't exist, you need to add them in the right places.

LoadModule webkit_module    libexec/httpd/mod_webkit.so

AddModule mod_webkit.c

Add a single "Location" directive to the config file:

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

... where the "whatever" string above can be replaced with... um... whatever you want. Remember, though, it will be part of the URL when visiting any WebKit-generated pages.

Restart the Apache webserver.

imac1:~ garyp$ sudo apachectl restart
/usr/sbin/apachectl restart: httpd restarted

Launch the application server.

imac1:~ garyp$ cd /usr/local/webwarerun/
imac1:~ garyp$ ./AppServer &

Launch your browser and load the URL: http://localhost/whatever/... making sure to use the same string as in the Apache config. file. You should see the "Welcome to Webware!" page.

Now, you're using the Apache-native adapter, and have some control of the the URL-space of your Webware/WebKit installation. You can stop here and start developing if you like, but you will still have to manually launch the AppServer every time your system starts up.

DO NOT mess around with Apple's StartupItems junk; you'll go crazy trying to figure out why the AppServer won't run at system boot. Instead, get the AppServer to launch on startup using the procedure described in "Bootstrap Daemons".

In a nutshell, here's how I got it to work. Create a file named "appserver.plist" in the directory /etc/mach_init.d. Inside, specify a little bit of XML:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" 
	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>ServiceName</key>
        <string>com.apple.Webware.appserver</string>
        <key>Command</key>
        <string>/usr/local/webwarerun/AppServer</string>
        <key>OnDemand</key>
        <false/>
</dict>
</plist>

Then, make sure it's owned by root, group wheel, 644 permissions, so it looks like this:

imac1:~ garyp$ cd /etc/mach_init.d
imac1:~ garyp$ ls -l app*
-rw-r--r--  1 root  wheel  396  3 Aug 09:58 appserver.plist

Actual mileage may vary... since the ServiceName string is randomly made up. Also, I don't know how well the AppServer will operate (if at all) if you trip the "OnDemand" boolean to "true".

Finally, you must tweak your AppServer executable in your runtime directory to use absolute paths instead of relative paths. This is probably due to an environment PATH issue. After the default installation, your AppServer executable will look like this:

#!/bin/sh

# as long as the appserver returns a 3, it wants to be restarted

retcode=3
while test $retcode -eq 3; do
    /usr/bin/env python Launch.py ThreadedAppServer $*
    retcode=$?
done

Simply change the path to the Python binary and Launch.py files, like so (changes in red):

#!/bin/sh

# as long as the appserver returns a 3, it wants to be restarted

retcode=3
while test $retcode -eq 3; do
    /usr/bin/python /usr/local/webwarerun/Launch.py ThreadedAppServer $*
    retcode=$?
done

Restart the machine and hit the URL in your browser. That should do it.