Cleaned up INSTALL.txt and WEBSERVER.txt, adding new instructions on

how to use ZServer with PCGI.

doc/INSTALL.txt

@@ -15,30 +15,16 @@ Important notes
 
 Running Zope
 
-  You have a number of options for running Zope. (Too Many? ;)
-
   - You can use ZServer, the integration of Zope and Medusa.  You must
-    use ZServer if you want to use ZODB 3 and use multiple concurrent
-    threads. ZServer is currently in beta, so this may not be a good
-    choice for production systems.
+    use ZServer if you want to use multiple concurrent threads.
+    ZServer is currently in beta, so this may not be a good choice for
+    production systems.
 
   - You can use the PCGI publisher with an existing web server. 
     This is currently the recommended way to run Zope for production
-    systems. 
-
-Choosing your database
-
-  We currently support two Zope databases, ZODB 2 and ZODB 3. 
-  ZODB 3 is the default database.  To use ZODB 2:
-
-    - You can use ZODB 2 with ZServer and the z2.py script
-      described below by providing the -2 command-line option to
-      z2.py. 
-
-    - You can use ZODB 2 with the PCGI publisher by editing Zope.cgi
-      (after running the installer) changing the published module to
-      'Main' and changing 'Zope' to 'Main' in the PCGI_MODULE_PATH
-      setting.
+    systems, however this will force Zope into single threaded mode.
+    See the WEBSERVER.txt file in the doc/ directory for details on
+    using Zope with an existing webserver.
 
 Quick Start
 
@@ -173,20 +159,6 @@ Setting permissions on the var directory.
   of the var directory and the files in it to allow Zope to read and write
   under its changed userid.
 
-Using ZServer
-
-  Zope comes with a ZServer startup script, z2.py, for starting
-  ZServer::
-
-    python z2.py
-
-  Look at the documentation string or run the script with
-  the -h option to get information on available options.  You can edit
-  this script to change defaults, or you can create a Unix shell
-  script or DOS BAT file to run the script with arguments.  The second
-  approach is preferred to avoid having to reconfigure the z2.py script
-  after a software update. 
-
 Starting Zope with an existing web server
 
   See the WEBSERVERS.txt file for more information about configuring Zope
@@ -197,3 +169,6 @@ Starting Zope with an existing web server
     * If you wish to use ZServer with PCGI use z2.py's '-p' switch to specify
       a PCGI info file.
   
+
+
+

doc/WEBSERVER.txt

@@ -5,6 +5,56 @@ Using Zope with an existing web server
   existing web server. Use Persistent CGI (PCGI) to allow your existing
   web server to work with Zope on Unix and Windows.
 
+  Roughly, PCGI is a protocol for translating CGI requests from a web
+  server into Zope requests.  CGI requests are traditionally one shot
+  events; the web server handles a request for a CGI script by
+  spawning a new process to handle the requests, returning the results 
+  of the request when the process dies.
+
+  Zope is a long running process, which means that it does not start
+  up and die on each request like traditional CGI programs (if it did, 
+  each request would take far too long due to the time to start and
+  stop an application as large as Zope).  In order to gateway 
+
+Using Zope in multi threaded mode with ZServer
+----------------------------------------------
+
+  ZServer is a general purpose TCP server for publishing Zope objects
+  over various transport protcols.  For Zope to run multi-threaded,
+  you must run ZServer.
+
+  ZServer is based on Sam Rushing's medusa software.  The benefit of
+  using medusa as the ZServer core is that it is not protocol specific 
+  (medusa provides libraries to program for any protocol) and it is
+  easily extensible.  Because medusa is written in Pyhton, is extremly 
+  high performance by design, and comes with an HTTP and FTP server,
+  we chose it for the Zope core.
+
+  It is not necesary, however, for ZServer to actually listen for
+  incomming HTTP requests.  If you want Apache to do the actual
+  listening and serving, then you can use ZServer's PCGI component to
+  communcate with Apache.
+
+  To run ZServer with PCGI, you must specify the -p option to the
+  z2.py startup script.  From the top level Zope directory, you can:
+
+    bash% python1.5.2 z2.py -p
+
+  Note, you must have gone through the directions in INSTALL.txt for
+  this to work. 
+
+  This command will start ZServer up with PCGI (by default, it will
+  also start up an HTTP and FTP server).  For PCGI to work, the
+  webserver and apache must agree on a PCGI resource file.  If this
+  file is not named 'Zope.cgi' and is not in the same directory as
+  z2.py, then you can specify the file name after the '-p', like:
+
+    bash% python.1.5.2 z2.py -p /path/to/PCGI/resource/file
+
+  Now the Zope long running process is started up, and the PCGI
+  component is loaded and ready to recieve CGI requests from your
+  webserver.  
+
   The installation process should create a 'Zope.cgi' PCGI file. Copy the
   'Zope.cgi' file to your web server's cgi-bin directory.
   
@@ -30,29 +80,43 @@ Using Zope with an existing web server
   You should be prompted to enter a username and password. Enter the Zope
   "super manager" name and password.
 
-  Two ways to support PCGI
 
-    There are two ways to handle PCGI requests with Zope.
+  Note: Apache requires some tricky configuration to get it to pass
+  the HTTP authentication header information to Zope.  See the section 
+  'Zope authentication with existing web servers'.
+
 
-    Using PCGI Publisher
+Using Zope in single threaded mode with pcgi_publisher
+------------------------------------------------------
 
-      By default, accessing Zope.cgi from your web server will
-      automatically cause a Python script, pcgi_publisher, to run.
-      This is a single-threaded application that serves PCGI requests
-      one at a time.  The script will run as whatever user (and with
-      whatever group) your web server uses to run CGI requests.
+  The installation process should create a 'Zope.cgi' PCGI file. Copy the
+  'Zope.cgi' file to your web server's cgi-bin directory.
   
-    Using ZServer
+  On Unix you can also create a symbolic link to 'Zope.cgi' from your cgi-bin
+  directory. For example::
 
-      The Zope 2 start script, z2.py will run ZServer and serve PCGI
-      requests by default.  ZServer is a multi-threaded server that
-      can simultaneously support multiple protocols, including PCGI,
-      HTTP, and FTP.  If Zope is started by root (on Unix) with z2.py,
-      then the Server will run as nobody, otherwise it will run as
-      whatever user ran z2.py. You can configure ZServer to run as a
-      specific userid using the '-u' switch.
+    ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope
 
-  Zope authentication with existing web servers.
+  At this point you should perform any other steps you web server
+  requires to install and configure a CGI script.
+
+  Note: For more information on PCGI check out Jeff Bauer's "PCGI pages", 
+  http://starship.skyport.net/crew/jbauer/persistcgi/.
+
+  When your Zope.cgi file is correctly configured as a CGI script with
+  your web server, you are ready to access Zope through the web. You should
+  point your browser at:
+
+    'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage'
+
+  (Your URL maybe be different depending on how your web server is configured.)
+
+  You should be prompted to enter a username and password. Enter the Zope
+  "super manager" name and password.
+
+
+Zope authentication with existing web servers
+---------------------------------------------
 
   Zope normally performs both authentication and authorization of users.
   Some web servers don't pass authentication information to CGI scripts.
@@ -62,6 +126,17 @@ Using Zope with an existing web server
 
   Tricking Apache to pass authentication headers
 
+    Before attempting to use your own Apache with Zope, it is highly
+    recommended that you look at Zap.  Zap is a preconfigured and
+    precompiled version of Apache for Linux that drops right into Zope
+    with no hassles.  Even if you want to use your own Apache, or if
+    you use it on a different platform than Linux, it is very helpful
+    to have Zap's .conf file to guide you through configuring Apache.
+
+    Zap can be found on the Zope website at:
+
+      http://www.zope.org/Download/Releases/Zap-1.1.0
+
     If you are using Apache you will need to trick Apache into passing
     authentication headers to Zope. The easiest way to do this with 
     Apache 1.3 and above is to use mod_rewrite. Here is an example of
@@ -173,3 +248,15 @@ Using Zope with an existing web server
 
       * An ISAPI module to support PCGI is under development.
 
+
+
+
+
+
+
+
+
+
+
+
+