************************************************************************** * Copyright 1995-2001 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: $Date$ * * $Id: //guest/perforce_software/webkeeper/README.WEBKEEP#3 $ * ************************************************************************** PERFORCE SOFTWARE WEBKEEPER NOTES Warning: This is a demo, 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.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 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) Fix up the EXTRA_INCLUDES line in Makefile.tmpl to reflect the path to the Perforce API you unpacked in step 1. 4) Fix up the LIBS line in libwebkeep.module to reflect the path to the Perforce API you unpacked in step 1. 5) 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 6) Once comfortable with the build, install. % cd /path/to/apache/src % make install 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. 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 indexing is still not yet supported. EXAMPLE WEBKEEPER CONFIGURATIONS Most Basic ========== # Uncomment the following two lines are only necessary if WebKeeper is being # used as a loadable module. # LoadModule webkeep_module libexec/libwebkeep.so # AddModule mod_webkeep.c # 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 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. WebKeepPort perforce:1666 WebKeepUser perforce_user WebKeepAlias / //depot/htdocs/ WebKeepDirectoryIndex index.html DefaultType text/html Sync to Disk to Allow Processing (Red Hat Apache configuration) =============================================================== LoadModule webkeep_module libexec/libwebkeep.so # The following must come after the ClearModuleList directive AddModule mod_webkeep.c WebKeepPort perforce:1666 WebKeepUser perforce_user WebKeepAlias / //depot/htdocs/ WebKeepDirectoryIndex index.html WebKeepClient my_client WebKeepSync On TESTED ON Red Hat Linux 6.2 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO Red Hat Linux 7.0 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO Red Hat Linux 7.1 x86, Apache 1.3.19, p4api r00.1/bin.linux60x86, static & DSO FreeBSD 3.5.1 x86, Apache 1.3.16, p4api r00.2/bin.freebsd, static & DSO