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.
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.2
# 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.
# 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 :
# 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
httpd.conf.default file for details of more available directives.
Configuring Postgres for templates
A number of Whitebeam templates store their data in the open source PostgreSQL database.
Before you use these templates you have to create a PostgreSQL database with the
The Whitebeam source directory contains the following file that can be used with
Postgres to create such a database:
If you've installed Whitebeam, either through 'make install' or via the RPM,
this file will also be available in the install directories (default /var/whitebeam/conf).
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.4.19, 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
This will create a Whitebeam database called 'whitebeam' and a Postgres user (role) also
Note: Postgres does not need to be running on the server you're using for your
Apache web-server and Whitebeam Presentation Engine. It can be good practice to place the
database on a separate server behind additional firewall protection.
This section assumes you'll be using all the standard Whitebeam templates.
Note: If you installed Whitebeam on a RedHat (RHEL, CentSO, Fedora) using the RPM we provide then
you can start all the standard templates with "service whitebeam start".
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 :
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
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 &
In the above script the following parameters applie :
- The "-o" flag causes the template to run in an operational, "quiet" mode.
Leave this off for more trace output, and add "-v" to see verbose
- :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.)
- 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.
- If pages are displaying, but you are unsure about template communications, start the templates using the "-v" flag mentioned above.
- Help and advice can be sought through the Whitebeam message-boards