Installing Whitebeam (release 0.9.34 on)

Site Map
Application Guide
Contact Whitebeam
Whitebeam Users

Installing Whitebeam (release 0.9.34 on)

Whitebeam 1.3.23 is currently available as a source code distribution for Unix. There is also an older binary distribution for Microsoft Windows platforms that is not currently being actively maintained.

Upgrading from earier versions of Whitebeam

From version 0.9.35 we've modified the Postgres database schema slightly. The most significant change from previous versions is that we no longer use Postgres Large Objects to hold file objects. This is a requirements to support replication (we've not found a replication system that can deal with Large Objects!).

This does mean that old databases must be migrated to the new schema. This is fairly straightforward, We've put together some notes to help you

UNIX Installation

What we're building

These instructions will build a shared object for the Apache web-server (version 1.3.x or 2.x) and will install . the Whitebeam Apache module and the associated application modules (templates).

Note the build instructions from version 0.9.35 have been significantly simplified from previous versions.

The instructions use specific versions of various components to illustrate the entire build process. You should adjust these instructions for more recent versions as necessary!

Things you'll need

download or otherwise obtain the following modules:

You will need the following applications installed on you server. For most operating systems the standard distributions will include suitable versions of these applications. If necessary download and build...

Apache web serverApache 1.3.33
Apache 2.0.53
Apache organisation
Postgres databasePostgres 8.0.2PostgreSQL Global Development Group

Your Apache installation can of course include other Apache modules. We'd recommend including SSL if it's not already present.

With Apache and Postgres installed on your system, you'll also need to download the Whitebeam source tree:

Whitebeam is written in C/C++ and to build you'll also need a GNU C++ tool chain. Again this is generally available as part of your standard Linux distribution.


Quick Instructions

    #   Assuming Apache and Postgres are installed

    # Extract Whitebeam
    $ tar zxcfp whitebeam_0_9_37.tar.gz
    $ cd whitebeam_0_9_37

    # Now with the rest of the build. 
    # Note: You need to have the Postgres server include files available under the standard
    # Postgres include directory in order to build native Postgres support (--enable-pgsql).
    # Some binary installations include these, and they appear to be included in a standard
    # build of PostreSQL version 8 Beta releases. For version 7.4.x, you may need to build
    # from source and include all header files using :
    #     gmake install-all-headers
    # If you don't have these headers or do not want native Postgres supoport in Whitebeam 
    # then leave --enable-pgsql from the configure line.
    # Configure Whitebeam with native Postgres functionality built into the system. If configure
    # fails to find the necessary files use ./configure --help
    $ ./configure --enable-pgsql
    # Build Whitebeam
    $ gmake
    # Change to 'root' to install Whitebeam
    $ su
    $ ****
    $ gmake install
    # The standard install path for Whitebeam is /var/whitebeam. The Apache shared object file 
    # will be installed into /var/whitebeam/lib, which can be referenced from httpd.conf
    # DONE!

In detail

Building on any UNIX like platform uses a GNU autoconf configure script to configure the distribution. In theory, this means Whitebeam should build on a wide range of platforms.

  1. Ensure you have the GNU Make utility on your system - On Linux systems this will likely be the default make utility, on BSD systems it may need to be installed seperately, and will probably be called "gmake".
  2. You need to have a recent copy of openSSL installed on your system. If you haven't then see the link earlier in this document.
  3. In a convenient working directory untar Whitebeam
    $ tar zxvfp whitebeam_0_9_37.tar.gz
    $ cd whitebeam_0_9_37
  4. Configure Whitebeam, including native Postgres support:
    $ ./configure --enable-pgsql

    Whitebeam should find Apache and Postgres. In this case we asume Postgres is in it's default installation directory. Alternatively you can use the options --with-apache=<path to Apache> and --with-pgsql=<path to postgres> to locate the source tree without having to build Postgres.

    Note: You need to have the Postgres server include files available under the standard Postgres include directory in order to build native Postgres support (--enable-pgsql). Some binary installations include these, and they appear to be included in a standard build of PostreSQL version 8 Beta releases. For version 7.4.x, you may need to build from source and include all header files using :

    gmake install-all-headers

    If you don't have these headers or do not want native Postgres supoport in Whitebeam then leave --enable-pgsql from the configure line.

  5. Make the Whitebeam libraries and binaries. This will build Apache - but we need to do this again to build the shared object for Whitebeam.
    $ gmake
  6. Next, you will probably need to su to root in order to install the Whitebeam files in your local system directories:
    $ su
    # gmake install

The build/install sequence will by default install all of Whitebeam into /var/whitebeam. This directory has the following sub-directories:

  • /var/whitebeam/bin
    Contains the executable binaries for the Whitebeam templates and for the Whitebeam replication engine
  • /var/whitebeam/conf
    Contains XML syntax definition files for XML based template communications, for the Presentation Engine markup and for HTML itself.
  • /var/whitebeam/conf/template
    Contains XML service specifications for the various template services.
  • /var/whitebeam/lib
    Contains static link Whitebeam libraries and the shared library Apache module. You can directly reference the shared library from the Apache httpd.,conf file using /var/whitebeam/lib/ (for Apache 1.3.x)

If your attempt to build Whitebeam fails, please tell us, including the exact version of the OS, the ouput of configure and make.

A full version of Apache, including an httpd.conf.default configured with Whitebeam configuration directives, and a copy of the Whitebeam htdocs tree should have been installed in the configured Apache ServerRoot.

For further details see the Getting Started page.

Windows Installation

An OLDER version of Whitebeam is currently available as a binary distribution for Microsoft Windows platforms (Windows 98, ME, 2000, XP). Whitebeam is a dynamically loaded module in the windows environment.

The primary target for the Whitebeam module is Unix, the windows distribution is a port of that environment. The Windows distribution has not had the same level of use or testing as the Unix environment and as such should be considered an evaluation environment only at this time.

We're not currently making Whitebeam binaries available for Windows - primarily because of a lack of skill in this area. We'd love a little help from someone with some time available to get a cygwin environment build!

What you need....

To install the Windows version of Whitebeam you will need to download the following files.

Installing Windows Binary Distribution

  • Install the Apache binary installation by executiong the downloaded file. Install this in the default locations (c:\program files\Apache Group).
  • Unzip the Whitebeam archive into the same directory that you installed Apache. The archive adds the additional Whitebeam files to the Apache tree. So if you installed Apache in "c:\program files\Apache Group" - the default location - then unzip into that directory.
  • If you've unzipped the archive to the right location there will be a directory called 'whitebeam' directly under the Apache install directory. i.e. c:\program files\Apache Group\Apache\Whitebeam.

Configuring Apache with Whitebeam

Whitebeam under Windows operates as a dynamically loaded Apache module. The module is configured through the standard Apache configuration file (conf/httpd.conf by default). The Whitebeam archive installs a default httpd.conf with the following characteristics:

  1. Correctly load the Whitebeam module.
  2. Configures Apache to attach to port 8080
  3. Adds a handler for '.rhtm' files. All files with this extension are handled by the Whitenbeam module.
  4. Configures Whitebeam to attach to the context server on the local machine - on port 9501.
IF you install in a non default directory then you will have to modify the 'ServerRoot' and 'DocumentRoot' paths in httpd.conf

If you want to keep the contents of the current httpd.conf then you must copy it before you overlay the Whitebeam archive.

If you have an existing httpd.conf file you want to use then the following modifications will configure it to use the Whitebeam module:

  1. Add the following 'LoadModule' directive:
    LoadModule whitebeam-module modules/
  2. To operate the Whitebeam module requires a context template to execute on some machine on your network. For a simple environment this can be the same machine as that running Apache. The Whtebeam module needs to know where the context template is executing! Add the following directive to the httpd.conf file:
    RBTemplate context tcp ""

    This tells Whtiebeam that the context server is running on the local machine - attached to port 9501.
  3. Whitebeam has separate configuration for each virtual server. Each virtual server must have an RBClient directive. For each existing virtual server (and the default server) add the following directive :
    RBClient xxxxxx 1

    where xxxxxx is a unique client name. The '1' is the Whitebeam 'mode' for this server - either '0' for operational or '1' for test. Generally each client will have two seperate servers - one test - one operational. The Whitebeam module works slightly differently in each mode, for example more rigorous XML rules are applied in test mode, page failure is treated differently. For evaluation purposes - use the test instance.

Context Server

The whitebeam module provides session tracking facilities. This functionality makes use of a 'context template' that stores the session data independently of the machine running Apache - which in turn means multiple Apache servers can use a single context store - imrpoving the scaleablity of a solution using Whitebeam.

In the windows environment the Context Template is available as 'context.exe' - installed in Apache/whitebeam/context.exe. To run the context sever execute the following command from a Windows command prompt.

  • cd apache/whitebeam
  • context :9501
  • '9501' is the TCP port number on which the server will listen for Apache/Whitebeam requests. This number must match the port specified in the httpd.conf RBTemplate directive.

    To make sure the template is working, use the '-v' option. This will cause the template to display information about each request it receives from Apache.

    By default the context server deletes session data that has not been accessed within 30 minutes. This timeout can be altered on the command line by specifying '-ct=minutes' where 'minutes' is the timeout. For example:

    context -v -ct=120 :9501

    will execute the context server on port 9501 - with a session timeout period of 2 hours.

    The windows implementation of the context server stores all context information in the processors memory - relying on virtual memory to store information. This is fine for small sites - and certainly for evaluation. For a largedata centre this strategy is limited and a better solution is to implement the context interface to store context information on disk. Whitebeam includes a context implementation for Unix that does this using the DBM libraries - at the present time we have not ported this to Windows (Any volunteers?).

    Testing Whitebeam

    At one command prompt start the context server with the command:

  • cd apache/whitebeam
  • context -v :9501
  • The Default installation over-writes the standard httpd.conf with a Whitebeam example file. This creates a single server on the machine running Apache - connected to TCP port 8080. The contents of this server are in Apache/htdocs - the document root for the default (and only) server. On the machine running Apache - start a web browser and open:

  • http://localhost:8080/index.rhtm
  • This should bring up the Whitebeam homepage. If it does then Apache is correctly executing mod_whitebeam. If so the Contratulations. If not then check the contents of the Apache configuration file.

    Whitebeam release 1.3.36
    View XML source of this page
    (loadtime : 16ms)