README.WEBKEEP #5

**************************************************************************
* Copyright 1995-2008 Perforce Software.  
*
* This file is part of WebKeeper, a perforce client apache module.
*
* License is hereby granted to use this software and distribute it
* freely, as long as this copyright notice is retained and modifications
* are clearly marked.
*
* ALL WARRANTIES ARE HEREBY DISCLAIMED.
*
* Last updated: February 15, 2008
*
* $Id: //guest/matt_attaway/webkeeper/README.WEBKEEP#5 $
*
**************************************************************************

PERFORCE SOFTWARE WEBKEEPER NOTES

    Warning:

	This is an open-source project, not a product.

WHAT YOU HAVE

    This directory contains the generic componentry to build an Apache
    Web Server with a Perforce WebKeeper module.  This directory includes:

	Makefile.apxs     makefile for stand-alone apxs build
	Makefile.libdir   signal to APACI configure
	Makefile.tmpl     makefile template for APACI configure
	README.WEBKEEP	  this file
	libwebkeep.module module definition for APACI configure
	mod_webkeep.c	  the WebKeeper Apache module, C half
	mod_webkeep2.cc	  the WebKeeper Apache module, C++ half
	mod_webkeep.h	  glue between the C and C++ halves
	webkeeper.sln     solution file for building on Windows( VS 2003 )
	webkeeper.vcproj  project file for build on Windows

    You will also need a Perforce header file and link libraries and
    for your platform.  They can be found at:

	ftp.perforce.com/pub/perforce/r??.?/bin.*/p4api.tar

    There may be link dependencies on your operating system/compiler version
    and the Perforce API version.  Be sure to get the most appropriate build
    for your platform.  For example, for Linux 6.X and 7.X, get the Perforce
    API tarball from bin.linux60x86, rather than from bin.linux52x86.  The
    usual sign of an incorrect version is unresolved symbols at server link
    time.

TO BUILD THE APACHE SERVER

    1) Unpack the Perforce libraries.

	% cd /usr/local/src # or your favorite location
	% mkdir perforce
	% cd perforce
	% tar xvf /path/to/p4api.tar

       Note that there are source files in the p4api.tar ball
       that are not related to webkeeper.

    2) Unpack the webkeeper module

	% cd /path/to/apache/src/module
	% tar xvf /path/to/webkeeper/webkeep.tar
	% cd webkeep

    3) Determine how you wish to build WebKeeper.  You can build it as part
       of a full Apache build, either statically or as a loadable module
       using apxs, which is particularly useful on systems such as Red Hay Linux
       with binary distributions and custom enhancements to the source base.

       3.1) If you plan to build a full Apache tree, do the following:

       3.1.1) Fix up the EXTRA_INCLUDES line in Makefile.tmpl to reflect the
          path to the Perforce API you unpacked in step 1.

       3.1.2) Fix up the LIBS line in libwebkeep.module to reflect the path to
          the Perforce API you unpacked in step 1.

       3.1.3) Build apache.  Any other configuration directives should be added
          to the configure command if necessary.  If you wish to build WebKeeper
          as a shared module, add '--enable-shared=webkeep' to the configure
          line, resulting in libwebkeep.so as the loadable module.

	   % cd /path/to/apache
	   % ./configure --activate-module=src/modules/webkeep/libwebkeep.a
	   % cd src
	   % make

       3.1.4) Once comfortable with the build, install.

	   % cd /path/to/apache/src
           % make install

       3.2) If you plan to build WebKeeper using apxs, follow these
          instructions.  On Red Hat, this requires the apache-devel RPM.

       3.2.1) Fix up the P4API definitions in Makefile.apxs to reflect the path
          to the Perforce API you unpacked in step 1.

       3.2.2) Build the module with

           % make -f Makefile.apxs

       3.2.3) Either copy mod_webkeep.so to your Apache modules directory and
          manually modify the httpd.conf, or use apxs to do this with:

	   % apxs -i -a -n webkeep mod_webkeep.so

	  This will both install the DSO in your modules directory and modify
	  httpd.conf to load the module.  Note that it does not add the HAVE_*
	  macro guards used with Red Hat.

TO USE WEBKEEPER

    1)  Do the necessary steps to get a Perforce server running.  See
    	the admin section of the Perforce manual.

    2)	Edit the Apache httpd.conf file.  These are the directives:

		WebKeepPort host:port

		    Gives the address of the Perforce server.  
		    Default is $P4PORT or host 'perforce', port 1666.

		WebKeepUser username

		    Gives the Perforce user name.  
		    Default is $P4USER or $USERNAME.

		WebKeepPasswd password

		    Gives the user's password.
		    No default.

		WebKeepClient clientname

		    Gives the Perforce client name.
		    Default is $P4CLIENT or hostname.

		WebKeepAlias uri perforcePath

		    If the URI begins with uri, strips the intial uri,
		    replaces it with perforcePath, and then treats the
		    URI as a WebKeeper request.

		WebKeepSync On|Off

		    "On" causes files to be synced to the client and let's
		    Apache handle everything else.  Useful to allow other
		    modules to handle the content, particularly if they
		    are dynamic, such as PHP.

		WebKeepDirectoryIndex indexfile [...]

		    Lists the file names to be tried, in order, for directory
		    requests, exactly analogous to DirectoryIndex.  In fact,
		    this list should be an exact copy of the list supplied to
		    DirectoryIndex for consistency.

		WebKeepRefresh perforcePath [...]

		    Causes each perforcePath listed to be synced before the
		    handling of each request.  This should be used to ensure
		    that files that are required but that never are requested
		    directly, such as PHP includes and SSI files, are always
		    available and fresh.  Requires a client to be specified.
		    Client namespace is recommended for perforcePath.

	For example:

		WebKeepAlias /$ //depot/index.html
		WebKeepAlias / //depot/

	Maps the URI / to //depot/index.html and the rest of the web
	namespace into the corresponding Perforce namespace under //depot.
	The $ is necessary to distinguish between initial substring 
	matches and exact matches.

	The '/' at the end of the directory tree mapping is required.
	Otherwise, the file name will be appended to the depot name.

	You can also use //client/ where client is the name of your
	client.  If you use //client/, it will map the name through your
	client view.  You don't have to map the whole namespace.  You
	could say:

		WebKeepAlias /foo/ //depot/

	To map only files under /foo/... to the Perforce namespace.

	You can have multiple alias lines.

	If you test your server and the raw HTML is displayed, it may also
	be useful to add

		DefaultType text/html

	to your configuration.

Notes:

    Directory listing is still not yet supported.


EXAMPLE WEBKEEPER CONFIGURATIONS

# Uncomment the following line if WebKeeper is being used as a loadable module.
# LoadModule webkeep_module   modules/mod_webkeeper.so

# The following configuration for WebKeeper assumes the following:
#
#   o that your Perforce server is on host 'perforce' in the local domain
#     and listening on the standard port 1666
#   o that the web content that you wish to show is located in the depot
#     under //depot/htdocs.
#   o that a user 'perforce_user' without a password has at least read
#     permission to this portion of the depot.
#
# The <IfModule> directive ensures that this configuration is safe,
# although not functional as a Webkeeper server, regardless of whether
# mod_webkeep has been built or loaded into apache.


MOST BASIC
========================================
WebKeepPort   perforce:1666
WebKeepUser   perforce_user
WebKeepAlias  /p4/  //depot/htdocs
WebKeepDirectoryIndex index.html

<Location /p4>
    <IfModule webkeep_module>
    	SetHandler webkeep
        DefaultType text/html
    </IfModule>
</Location>

# With the above configuration, a URL of http://localhost/p4/test.html would
# map to //depot/htdocs/test.html


Sync to Disk to Allow Processing
========================================

<IfModule webkeep_module>
	WebKeepPort  perforce:1666
	WebKeepUser  perforce_user
	WebKeepAlias /  //depot/htdocs/
	WebKeepDirectoryIndex index.html
	WebKeepClient my_client
	WebKeepSync On
</IfModule>


TESTED ON
Windows XP SP2, Apache 2.2.4, p4api r06.2/bin.ntx86, DSO
FreeBSD 6.3, Apache 2.2.4, p4api r07.3/bin.ntx86, DSO
FreeBSD 5.4, Apache 2.2.4, p4api r07.3/bin.ntx86, DSO