[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.