[Zope-Checkins] CVS: Zope/doc - INSTALL.txt:1.36 WEBSERVER.txt:1.22

Fred L. Drake, Jr. fred@zope.com
Tue, 18 Mar 2003 16:19:11 -0500


Update of /cvs-repository/Zope/doc
In directory cvs.zope.org:/tmp/cvs-serv24380

Modified Files:
	INSTALL.txt WEBSERVER.txt 
Log Message:
Update documentaion from the new-install-branch.

=== Zope/doc/INSTALL.txt 1.35 => 1.36 ===
--- Zope/doc/INSTALL.txt:1.35	Thu Nov 14 15:02:18 2002
+++ Zope/doc/INSTALL.txt	Tue Mar 18 16:19:10 2003
@@ -1,136 +1,123 @@
-Building and installing Zope from source
-----------------------------------------
 
-  This document describes building and installing Zope on Unix.
-  We will provide Windows instructions in later releases. We
-  will also provide binary releases for some platforms.
+*** These instructions pertain to the new-install-branch! ***
+
 
-Important notes
+Building and installing Zope from source
+----------------------------------------
 
-   Starting with Zope 2.7, Zope *REQUIRES* Python 2.2.2 or later.
-   This is done to ease code sharing with Zope 3.
+  This document describes building and installing Zope on UNIX and
+  Linux.
 
-   See CHANGES.txt for important notes on this version of Zope.
+System requirements when building from source
 
+   bash or another Bourne shell variant
+   Python 2.2.2 or later installed somewhere in the system PATH
+   GNU make
+   A C compiler (gcc recommended)
 
 Quick Start
 
+  It is best to install Zope as a non-root user.
+
   If you are impatient, the following commands should get you up and
-  running with Zope 2 using ZServer and ZODB 3 on Unix::
+  running on any UNIX that meet the system requirements::
+
+    $ gunzip -c Zope-2.7.X-src.tar.gz | xar xvf
+    $ cd Zope-2.7.X
+    $ ./configure --prefix=/where/to/install/zope
+    $ make
+    $ make instance
+
+  These commands locate an appropriate version of Python, build Zope,
+  and create a usable Zope "instance" in the directory in which the
+  software was un-tarred.  The last of these commands will prompt you
+  to provide a user name and password for an administrator's account.
 
-    python w_pcgi.py  # Note, this must be Python 2.2.2 or later
-    ./start
+  You can now start Zope by running::
 
-  The first command builds and adjusts Zope.  Take note of the user
-  name and password output at the end of this command.  You will need
-  these to manage Zope.
+    $ ./bin/runzope
 
   If you get errors indicating that addresses are in use, then you
-  will have to supply arguments to z2.py to change the ports used for
-  HTTP or FTP. The default HTTP and FTP ports used by ZServer are 8080
-  and 8021 respectively. (See the help for the z2.py script by running
-  z2.py with the -h option for more information on how to specify
-  different ports)
+  will have to supply arguments to runzope to change the ports used
+  for HTTP or FTP. The default HTTP and FTP ports used by Zope are
+  8080 and 8021 respectively. You can change the ports used by
+  specifying the "port-base" parameter to runzope.  For example, to
+  run Zope on ports 9080 and 9021:
+
+    $ ./bin/runzope -X port-base=1000
 
-  You can then connect to Zope 2 by directing your browser to::
+  You can then connect to Zope by directing your browser to::
 
      http://yourhost:8080/manage
 
-  where yourhost is the name or address of the machine running Zope 2.
-  If you changed the HTTP port with the -w option to z2.py, then use
-  it rather than 8080.
+  .. where 'yourhost' is the DNS name or IP address of the machine
+  running Zope.  If you changed the HTTP port as described, use a port
+  number of 8080 + the port-base value.
 
   You will be prompted for a user name and password. Use the user name
-  and password output above.
+  and password you provided in response to the prompts issued during
+  the "make instance" process.
 
-  Now you're off and running! You should be looking at the Zope management
-  screen which is divided into two frames. On the left you can navigate
-  between Zope object and on the right you can edit them by selecting
-  different management functions with the tabs at the top of the frame.
-
-  If you haven't used Zope before, you should head to the Zope web site
-  and read some documentation. The Zope Manager's Guide is a good place
-  to start. You can access the Zope site at:
+  Now you're off and running! You should be looking at the Zope
+  management screen which is divided into two frames. On the left you
+  can navigate between Zope objects and on the right you can edit them
+  by selecting different management functions with the tabs at the top
+  of the frame.
+
+  If you haven't used Zope before, you should head to the Zope web
+  site and read some documentation. The Zope Book is a good place to
+  start. You can access the Zope Book at:
 
-    'http://www.zope.org/'
+    http://www.zope.org/Documentation/Books/ZopeBook
 
   Have fun!
 
 Building Zope
 
-  There are some python scripts in the top-level directory that should
-  help you get started. You must run these scripts from the top-level
-  directory.
+  If you want to try out Zope in the simplest fashion, then run the
+  conventional UNIX build sequence::
 
-  If you want to try out Zope in the simplest fashion using ZServer,
-  then run the script wo_pcgi::
+    ./configure --prefix /where/to/install/zope
+    make
+    make install
 
-    python wo_pcgi.py
+  Next, you need to create an "instance home", which contains
+  configuration and data for a Zope server process:
 
-  If you want to use PCGI and an existing web server run w_pcgi::
+    /where/to/install/zope/bin/mkzopeinstance /location/of/zope/instance
 
-    python w_pcgi.py
+  The Zope server can now be started using this command:
+
+    /location/of/zope/instance/bin/runzope
 
   Notes
 
-    * You should be using Python 2.2.2 or later to run the build scripts.
+    * You need to be using Python 2.2.2 or later to run the build
+      scripts; the ./configure script will attempt to locate the best
+      available interpreter.  All future invocations of Zope will use
+      that Python interpreter.
 
-    * The python you run Zope with *must* have threads compiled in,
+    * The Python you run Zope with *must* have threads compiled in,
       which is the case for a vanilla build.  Warning: Zope will not
       run with a Python version that uses libpth.  You *must* use
       libpthread.
 
-    * To build python extensions you need to have Python configuration
+    * To build Python extensions you need to have Python configuration
       information available. If your Python comes from an RPM you may
-      need the python-devel package installed too. If you built Python
-      from source all the configuration information should already be
-      there.
+      need the python-devel (or python-dev) package installed too. If
+      you built Python from source all the configuration information
+      should already be available.
 
     * If you just want to use Zope components it's not necessary to
       build Zope but it's a good idea since it will compile Python C
       extensions for you.
 
-    * You can use PCGI and an existing web server if you use ZServer.
-
-Starting Zope with an existing web server
-
-  See the WEBSERVERS.txt file for more information about configuring Zope
-  with an existing web server. See also the pcgi/README file for further
-  informations on the installation of PCGI.
-
-Running Zope
-
-  There are two ways to run Zope:
-
-  - You can use ZServer, the integration of Zope and Medusa.  You must
-    use ZServer if you want to use multiple concurrent threads.
-    ZServer is a server application that supports multiple protocols:
-
-      o HTTP -- ZServer is a Web server
-
-      o FTP -- ZServer is a file-transfer protocol server.  This
-        allows you to use FTP-enabled publishing systems with Zope.
-
-      o PCGI -- PCGI is a lightweight protocol for forwarding
-        requests from other web servers, like Apache or Netscape, to
-        Zope. This makes it possible to use web server features like
-        connection encryption or logging with Zope.
-
-      o monitor -- ZServer has the capability to allow you to access
-        the Python interpreter directly over a network channel.  If
-        you intend to use this, please read the 'DEBUGGING.txt'
-        document for more information.
-
-    With ZServer, you must start Zope manually using the z2.py script.
-    Typically, the command used to run the z2.py script will be put in
-    system startup scripts.
+    * See CHANGES.txt for important notes on this version of Zope.
 
-    ZServer is the prefered way to run Zope.
+Integrating Zope with an existing webserver
 
-  - If you *only* want to use PCGI and you don't need multi-threaded
-    operation, you can have a special program, the pcgi_publisger,
-    start Zope for you.  See the WEBSERVER.txt file for details on
-    using Zope with an existing webserver.
+  Zope doesn't require any existing webserver to run, but you can
+  integrate it with other webservers as necessary.  See the
+  WEBSERVERS.txt file for more information about configuring Zope with
+  an existing web server.
 
-  If you wish to enable Zope logging you must specify options on the
-  command line.  See LOGGING.txt in the doc directory.


=== Zope/doc/WEBSERVER.txt 1.21 => 1.22 ===
--- Zope/doc/WEBSERVER.txt:1.21	Wed Mar  5 14:05:56 2003
+++ Zope/doc/WEBSERVER.txt	Tue Mar 18 16:19:10 2003
@@ -45,24 +45,23 @@
 
  PCGI
 
-  To install PCGI, please read the pcgi/README file.
+  To install PCGI, please get the PCGI support package from XXX, and
+  read the pcgi/README.txt file from that package.
 
-  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% python2.2 z2.py -p
+  To run ZServer with PCGI, you must configure Zope with a PCGI
+  server.  You can do this by adding a section to the etc/zope.conf
+  file like this::
+
+    <pcgi-server>
+      address /path/to/PCGI/resource/file
+    </pcgi-server>
 
   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 Zope 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% python2.2 z2.py -p /path/to/PCGI/resource/file
+  This command will cause Zope to start with a PCGI server as well as
+  any other servers you specify in the zope.conf file.  For PCGI to
+  work, the webserver and Zope must agree on a PCGI resource file.
 
   Now the Zope long running process is started up, and the PCGI
   component is loaded and ready to receive CGI requests from your
@@ -113,13 +112,9 @@
   comes with straightforward instructions.  You will need to download
   the mod_fastcgi module from FastCGI.com:
 
-    http://www.fastcgi.com
-
-  A version more recent than 2.2.2 is needed.  If 2.2.3 or greater is
-  not yet available, get one of the snapshots from October 6th or
-  later:
+    http://www.fastcgi.com/
 
-    http://www.fastcgi.com/dist/
+  A version more recent than 2.2.2 is needed.
 
   Extract the archive and follow the directions in its 'INSTALL' file.
   Using the 'DSO' method is usually easiest.
@@ -144,35 +139,24 @@
   write to the socket.  For illustrative purposes, I will use
   '/tmp/zope.soc'.
 
-  The option to configure this is '-F (port #|socket filename)'.  Edit
-  your 'start' script.  It's found in the root of your Zope
-  installation, and it will look something like this::
-
-#! /bin/sh
-reldir=`dirname $0`
-PYTHONHOME=`cd $reldir; pwd`
-export PYTHONHOME
-exec /usr/bin/python \
-     $PYTHONHOME/z2.py \
-     -D "$@"
-
-  Insert a line after '$PYTHONHOME/z2.py \'.  If you are using
-  a TCP port, it will look like this::
-
-     -F 8889 \
+  This can be configured by adding a fcgi-server section in your
+  etc/zope.conf file.  The section should look like this for a TCP
+  port::
 
-  If you are using a socket, the line will look like this::
+    <fcgi-server>
+      address localhost:8889
+    </fcgi-server>
 
-     -F /tmp/zope.soc \
+  To use a Unix domain socket instead, specify the path of the socket
+  file instead of a [hostname:]port::
 
-  The trailing backslash is significant!  You can start Zope at this
-  point by running the 'start' script::
+    <fcgi-server>
+      address /tmp/zope.soc
+    </fcgi-server>
 
-$ ./start
+  You can start Zope at this point by running the 'runzope' script::
 
-  Note that by default the start script starts Zope in debug mode, and
-  so this command will not come back to a shell prompt until Zope
-  exits.
+$ ./bin/runzope
 
   Next, Apache must be set up to pass FastCGI requests to Zope.  This
   is done with a 'FastCgiExternalServer' directive in Apache's
@@ -431,33 +415,35 @@
 
       * An ISAPI module to support PCGI is under development.
 
-      * IIS 4.0 throws away Zope's error messages by default. This 
-        behavior can create quite a few problems, including authentication 
-        problems.
-
-      Microsoft prides itself on the clear error messages that IIS 4.0 
-      presents, when the user makes a mistake. These error messages are 
-      implemented in the form of Custom Error handlers, that return a file, 
-      or URL to a user when a certain error occurs.
-
-      This means, that when you forget to fill in an Id when you want to 
-      create, say, a new SQL Method, Zope's clear error message is replaced 
-      by IIS's totally irrelevant error message. Also, it completely breaks 
-      authentication when the user uses IE5.0 when trying to log into a secure 
-      area of the server. These Custom Error handlers are enabled by default.
+      * IIS 4.0 throws away Zope's error messages by default. This
+        behavior can create quite a few problems, including
+        authentication problems.
+
+      Microsoft prides itself on the clear error messages that IIS 4.0
+      presents, when the user makes a mistake. These error messages
+      are implemented in the form of Custom Error handlers, that
+      return a file, or URL to a user when a certain error occurs.
+
+      This means, that when you forget to fill in an Id when you want
+      to create, say, a new SQL Method, Zope's clear error message is
+      replaced by IIS's totally irrelevant error message. Also, it
+      completely breaks authentication when the user uses IE5.0 when
+      trying to log into a secure area of the server. These Custom
+      Error handlers are enabled by default.
 
       Luckily, the handlers can quite easily be switched off:
 
-      Open the IIS website in the Management Console, and navigate to the 
-      folder you put the PCGI executable in. If you named your Zope installation 
-      'Zope', it will be called 'Zope.exe'. Double-click on that file. A property 
-      page will appear. Select the 'Custom Errors' tab. Now, select every HTTP 
-      Error code in the listbox that doesn't have type 'Default', and click on 
-      the 'Set to Default' button for each one. This will disable IIS overriding 
-      the error message returned by Zope.
+      Open the IIS website in the Management Console, and navigate to
+      the folder you put the PCGI executable in. If you named your
+      Zope installation 'Zope', it will be called
+      'Zope.exe'. Double-click on that file. A property page will
+      appear. Select the 'Custom Errors' tab. Now, select every HTTP
+      Error code in the listbox that doesn't have type 'Default', and
+      click on the 'Set to Default' button for each one. This will
+      disable IIS overriding the error message returned by Zope.
 
-      Click OK, and voila, Zope is allowed to tell the world what it thinks went
-      wrong.
+      Click OK, and voila, Zope is allowed to tell the world what it
+      thinks went wrong.