Getting Started with Whitebeam

This document concentrates on confguring a Unix Apache system to use Whitebeam. The details also apply to the Windows system, but pathnames will need adjusting to suit your installed environment.

Initial configuration

If this is a fresh installation, then the Apache installer will have placed a default httpd.conf into your selected Apache configuration directory. This file is almost ready to go.

If you have updated an existing installation, then the Apache installer will have avoided overwriting your existing configuration, and you will need to transfer the basic configuration directives from httpd.conf.default into your existing file. SAVE YOUR WORKING CONFIG BEFORE CONTINUING.

The basic, required configuration directives for Whitebeam are:

# Whitebeam is loaded as a shared object library. The following directive
# tells Apache how to load the library
LoadModule whitebeam_module /var/build/whitebeam/lib/libwhitebeam1.so.1.1

# Apache needs to know which types of file Whitebeam will run:
AddHandler whitebeam-handler .rhtm
AddHandler whitebeam-handler .whtm

# Make Apache serve up a default Whitebeam page for an incomplete directory 
# name if there is no static 'index.html' file.
DirectoryIndex index.html index.rhtm index.whtm


# Whitebeam can segregate data based on Virtual-Server
# The following line specifies a mandatory default value.
RBClient $Whitebeam$ 1

# Whitebeam comes with a collection of 'templates' - standalone applications
# that provide a range of common web-services to make application writing 
# easier. The following directives tell the Apache mod_whitebeam is to
# talk to the templates.
#
# In the following configuration the template executables are run on the
# local host. You can run them on another machine. In large installations
# you might have one machine dedicated to running Postgres and the database
# templates. Simply replace 'localhost' with the IP address of the machine
# running each template.
RBTemplate context    tcp "localhost:9501"
RBTemplate catalogue  tcp "localhost:9502"
RBTemplate contact    tcp "localhost:9503"
RBTemplate file       tcp "localhost:9506"
RBTemplate semaphore  tcp "localhost:9512"
RBTemplate counter    tcp "localhost:9514"
RBTemplate site       tcp "localhost:9516"
RBTemplate collection tcp "localhost:9517"
RBTemplate audit      tcp "localhost:9518"
RBTemplate chat       tcp "localhost:9519"

# If you are going to use the SmtpRequest object in Whitebeam you have to tell
# it how to find your sendmail programme. In this example it is again local.
RBsmtpServer localhost

# By default web-sites are *not* given raw access to the Postgres database. To
# allow this uncomment the following directive:
RBdbase allow  pgsql * * * *


# Generally most Apache installations with make use of 'virtual servers' - allowing
# Apache to serve multiple web-sites. The Whitebeam directives above can be repeated in
# each virtual server. Example :
<VirtualHost *:80>
    ServerAdmin admin@mysite.org
    DocumentRoot /var/www/sites/sitehome

# ALL virtual servers SHOULD include an RBClient directive. Each client identifies a
# different set of data. Multiple sites can share the same data set, altough it is 
# more usual for each virtual server to have a distinct client name.
#
# RBClient has two attributes : 
#  + the name of the client - a simple string
#  + a single character instance identifier. For live sites
#    this should be '0'. For test sites this should be '1'. Other 
#    values can be used, although are not common. Whitebeam reduces
#    debug data collection for the live instance of a site.
    RBClient mysite 0
    CustomLog "/usr/local/apache/logs/mysite-0" combined

    ServerName www.mysite.org
</VirtualHost>

See the httpd.conf.default file for details of more available directives.

Configuring Postgres for templates

The following templates store their data in the open source PostgreSQL database : catalogue, contact, file2, site, collection, audit, chat. Before you use these templates you have to create a PostgreSQL database with the correct schema.

The Whitebeam source directory contains the following file that can be used with Postgres to create such a database :

whitebeam/templates/pgsql/schema-file2.sql

To use this file assuming PostgreSQL is installed on your system simply start the PostgreSQL 'psql' tool as the database superuser (assuming you followed the standard PostgreSQL install instructions this will be user 'postgres') :

$ psql postgres template1
Welcome to psql 8.1.4, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help with psql commands
       \g or terminate with semicolon to execute query
       \q to quit

template1=# \i schema_file2.sql 
whitebeam=# \q
$

This will create a Whitebeam database called 'whitebeam' and a Postgres user (role) also called Whitebeam.

Starting templates

This section assumes you'll be using all the standard Whitebeam templates.

Before starting Apache all the templates you want to use should be started, on the machines and using the TCP port numbers identified in the httpd.conf file.

The following example shell script shows how the templates can be started :

#!/bin/sh

cd /var/whitebeam/logs

nohup ../bin/context_mem -o :9501 >RBcontext.log 2>&1 &
nohup ../bin/semaphore   -o :9512 >RBsema.log 2>&1 &
nohup ../bin/counter     -o :9514 >RBcounter.log 2>&1 &

su postgres -c "/bin/sh <<EOF

cd /var/whitebeam/logs
nohup ../bin/catalogue-pgsql  -o :9502 -Dwhitebeam -Uwhitebeam >RBcat.log 2>&1 &
nohup ../bin/contacts-pgsql   -o :9503 -Dwhitebeam -Uwhitebeam >RBcon.log 2>&1 &
nohup ../bin/file2-pgsql      -o :9506 -Dwhitebeam -Uwhitebeam >RBfile2.log 2>&1 &
nohup ../bin/site-pgsql       -o :9516 -Dwhitebeam -Uwhitebeam >RBsite.log 2>&1 &
nohup ../bin/collection-pgsql -o :9517 -Dwhitebeam -Uwhitebeam >RBcollection.log 2>&1 &
nohup ../bin/audit-pgsql      -o :9518 -Dwhitebeam -Uwhitebeam >RBaudit.log 2>&1 &
nohup ../bin/chat-pgsql       -o :9519 -Dwhitebeam -Uwhitebeam >RBchat.log 2>&1 &
EOF
" 

In the above script the following parameters applie :

• The "-o" flag causes the template to operate in an operational, "quiet" mode. Leave this off for more trace output, and add "-v" to see verbose trace information.
• :nnnn - TCP port numbers on which to listen for requests from the Apache module Presentation Engine. The port-numbers shown above are just suggestions, but match the shipped configuration file and the httpd.conf example above.
• The "-Dwhitebeam" parameter for the database templates indicates database name.
• "-U" and "-P" flags are available to override default username and password if needed. (The PostgreSQL default username/passwords are whitebeam/whitebeam.)

Problems ?

1. Apache can be started in a single-threaded verbose debugging mode:

   $ /usr/local/apache/bin/httpd -X 

   This provides much more information about what Apache is doing.
2. If pages are displaying, but you are unsure about template communications, start the templates using the "-v" flag mentioned above.
3. Help and advice can be sought through the Whitebeam message-boards