Commit 0023415b authored by Fred Drake's avatar Fred Drake

Update documentaion from the new-install-branch.

parent c658c172
Building and installing Zope from source
----------------------------------------
This document describes building and installing Zope on Unix. *** These instructions pertain to the new-install-branch! ***
We will provide Windows instructions in later releases. We
will also provide binary releases for some platforms.
Important notes Building and installing Zope from source
----------------------------------------
Starting with Zope 2.7, Zope *REQUIRES* Python 2.2.2 or later. This document describes building and installing Zope on UNIX and
This is done to ease code sharing with Zope 3. 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 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 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 You can now start Zope by running::
./start
The first command builds and adjusts Zope. Take note of the user $ ./bin/runzope
name and password output at the end of this command. You will need
these to manage Zope.
If you get errors indicating that addresses are in use, then you 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 will have to supply arguments to runzope to change the ports used
HTTP or FTP. The default HTTP and FTP ports used by ZServer are 8080 for HTTP or FTP. The default HTTP and FTP ports used by Zope are
and 8021 respectively. (See the help for the z2.py script by running 8080 and 8021 respectively. You can change the ports used by
z2.py with the -h option for more information on how to specify specifying the "port-base" parameter to runzope. For example, to
different ports) run Zope on ports 9080 and 9021:
You can then connect to Zope 2 by directing your browser to:: $ ./bin/runzope -X port-base=1000
You can then connect to Zope by directing your browser to::
http://yourhost:8080/manage http://yourhost:8080/manage
where yourhost is the name or address of the machine running Zope 2. .. where 'yourhost' is the DNS name or IP address of the machine
If you changed the HTTP port with the -w option to z2.py, then use running Zope. If you changed the HTTP port as described, use a port
it rather than 8080. number of 8080 + the port-base value.
You will be prompted for a user name and password. Use the user name 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 Now you're off and running! You should be looking at the Zope
screen which is divided into two frames. On the left you can navigate management screen which is divided into two frames. On the left you
between Zope object and on the right you can edit them by selecting can navigate between Zope objects and on the right you can edit them
different management functions with the tabs at the top of the frame. 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 If you haven't used Zope before, you should head to the Zope web
and read some documentation. The Zope Manager's Guide is a good place site and read some documentation. The Zope Book is a good place to
to start. You can access the Zope site at: start. You can access the Zope Book at:
'http://www.zope.org/' http://www.zope.org/Documentation/Books/ZopeBook
Have fun! Have fun!
Building Zope Building Zope
There are some python scripts in the top-level directory that should If you want to try out Zope in the simplest fashion, then run the
help you get started. You must run these scripts from the top-level conventional UNIX build sequence::
directory.
./configure --prefix /where/to/install/zope
make
make install
If you want to try out Zope in the simplest fashion using ZServer, Next, you need to create an "instance home", which contains
then run the script wo_pcgi:: configuration and data for a Zope server process:
python wo_pcgi.py /where/to/install/zope/bin/mkzopeinstance /location/of/zope/instance
If you want to use PCGI and an existing web server run w_pcgi:: The Zope server can now be started using this command:
python w_pcgi.py /location/of/zope/instance/bin/runzope
Notes 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 which is the case for a vanilla build. Warning: Zope will not
run with a Python version that uses libpth. You *must* use run with a Python version that uses libpth. You *must* use
libpthread. 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 information available. If your Python comes from an RPM you may
need the python-devel package installed too. If you built Python need the python-devel (or python-dev) package installed too. If
from source all the configuration information should already be you built Python from source all the configuration information
there. should already be available.
* If you just want to use Zope components it's not necessary to * 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 build Zope but it's a good idea since it will compile Python C
extensions for you. extensions for you.
* You can use PCGI and an existing web server if you use ZServer. * See CHANGES.txt for important notes on this version of Zope.
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.
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 Zope doesn't require any existing webserver to run, but you can
operation, you can have a special program, the pcgi_publisger, integrate it with other webservers as necessary. See the
start Zope for you. See the WEBSERVER.txt file for details on WEBSERVERS.txt file for more information about configuring Zope with
using Zope with an existing webserver. 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.
...@@ -45,24 +45,23 @@ Using Zope in multi-threaded mode with ZServer ...@@ -45,24 +45,23 @@ Using Zope in multi-threaded mode with ZServer
PCGI 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 To run ZServer with PCGI, you must configure Zope with a PCGI
'z2.py' startup script. From the top level Zope directory, you server. You can do this by adding a section to the etc/zope.conf
can:: file like this::
bash% python2.2 z2.py -p <pcgi-server>
address /path/to/PCGI/resource/file
</pcgi-server>
Note, you must have gone through the directions in 'INSTALL.txt' for Note, you must have gone through the directions in 'INSTALL.txt' for
this to work. this to work.
This command will start ZServer up with PCGI (by default, it will This command will cause Zope to start with a PCGI server as well as
also start up an HTTP and FTP server). For PCGI to work, the any other servers you specify in the zope.conf file. For PCGI to
webserver and Zope must agree on a PCGI resource file. If this file work, the webserver and Zope must agree on a PCGI resource 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
Now the Zope long running process is started up, and the PCGI Now the Zope long running process is started up, and the PCGI
component is loaded and ready to receive CGI requests from your component is loaded and ready to receive CGI requests from your
...@@ -113,13 +112,9 @@ Using Zope in multi-threaded mode with ZServer ...@@ -113,13 +112,9 @@ Using Zope in multi-threaded mode with ZServer
comes with straightforward instructions. You will need to download comes with straightforward instructions. You will need to download
the mod_fastcgi module from FastCGI.com: the mod_fastcgi module from FastCGI.com:
http://www.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/dist/ A version more recent than 2.2.2 is needed.
Extract the archive and follow the directions in its 'INSTALL' file. Extract the archive and follow the directions in its 'INSTALL' file.
Using the 'DSO' method is usually easiest. Using the 'DSO' method is usually easiest.
...@@ -144,35 +139,24 @@ Using Zope in multi-threaded mode with ZServer ...@@ -144,35 +139,24 @@ Using Zope in multi-threaded mode with ZServer
write to the socket. For illustrative purposes, I will use write to the socket. For illustrative purposes, I will use
'/tmp/zope.soc'. '/tmp/zope.soc'.
The option to configure this is '-F (port #|socket filename)'. Edit This can be configured by adding a fcgi-server section in your
your 'start' script. It's found in the root of your Zope etc/zope.conf file. The section should look like this for a TCP
installation, and it will look something like this:: port::
#! /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 <fcgi-server>
a TCP port, it will look like this:: address localhost:8889
</fcgi-server>
-F 8889 \ To use a Unix domain socket instead, specify the path of the socket
file instead of a [hostname:]port::
If you are using a socket, the line will look like this:: <fcgi-server>
address /tmp/zope.soc
</fcgi-server>
-F /tmp/zope.soc \ You can start Zope at this point by running the 'runzope' script::
The trailing backslash is significant! You can start Zope at this $ ./bin/runzope
point by running the 'start' script::
$ ./start
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.
Next, Apache must be set up to pass FastCGI requests to Zope. This Next, Apache must be set up to pass FastCGI requests to Zope. This
is done with a 'FastCgiExternalServer' directive in Apache's is done with a 'FastCgiExternalServer' directive in Apache's
...@@ -431,33 +415,35 @@ Zope authentication with existing web servers ...@@ -431,33 +415,35 @@ Zope authentication with existing web servers
* An ISAPI module to support PCGI is under development. * An ISAPI module to support PCGI is under development.
* IIS 4.0 throws away Zope's error messages by default. This * IIS 4.0 throws away Zope's error messages by default. This
behavior can create quite a few problems, including authentication behavior can create quite a few problems, including
problems. authentication problems.
Microsoft prides itself on the clear error messages that IIS 4.0 Microsoft prides itself on the clear error messages that IIS 4.0
presents, when the user makes a mistake. These error messages are presents, when the user makes a mistake. These error messages
implemented in the form of Custom Error handlers, that return a file, are implemented in the form of Custom Error handlers, that
or URL to a user when a certain error occurs. 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 This means, that when you forget to fill in an Id when you want
create, say, a new SQL Method, Zope's clear error message is replaced to create, say, a new SQL Method, Zope's clear error message is
by IIS's totally irrelevant error message. Also, it completely breaks replaced by IIS's totally irrelevant error message. Also, it
authentication when the user uses IE5.0 when trying to log into a secure completely breaks authentication when the user uses IE5.0 when
area of the server. These Custom Error handlers are enabled by default. 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: Luckily, the handlers can quite easily be switched off:
Open the IIS website in the Management Console, and navigate to the Open the IIS website in the Management Console, and navigate to
folder you put the PCGI executable in. If you named your Zope installation the folder you put the PCGI executable in. If you named your
'Zope', it will be called 'Zope.exe'. Double-click on that file. A property Zope installation 'Zope', it will be called
page will appear. Select the 'Custom Errors' tab. Now, select every HTTP 'Zope.exe'. Double-click on that file. A property page will
Error code in the listbox that doesn't have type 'Default', and click on appear. Select the 'Custom Errors' tab. Now, select every HTTP
the 'Set to Default' button for each one. This will disable IIS overriding Error code in the listbox that doesn't have type 'Default', and
the error message returned by Zope. 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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment