Commit f00e8450 authored by Jim Fulton's avatar Jim Fulton

Documentation cleanup.

parent 671c4115
MKHOWTO=mkhowto
MKHTML=$(MKHOWTO) --html --iconserver=. --split=4 --dvips-safe
ZODBTEX = guide/gfdl.tex guide/introduction.tex guide/modules.tex \
guide/prog-zodb.tex guide/storages.tex guide/transactions.tex \
guide/zeo.tex guide/zodb.tex
default: pdf
all: pdf ps html
pdf: storage.pdf zodb.pdf
ps: storage.ps zodb.ps
html: storage/storage.html zodb/zodb.html
storage.pdf: storage.tex
$(MKHOWTO) --pdf $<
storage.ps: storage.tex
$(MKHOWTO) --ps $<
storage/storage.html: storage.tex
$(MKHTML) storage.tex
zodb.pdf: $(ZODBTEX)
$(MKHOWTO) --pdf guide/zodb.tex
zodb.ps: $(ZODBTEX)
$(MKHOWTO) --ps guide/zodb.tex
zodb/zodb.html: $(ZODBTEX)
$(MKHTML) guide/zodb.tex
clobber:
rm -rf storage.pdf storage.ps storage/ zodb.pdf zodb.ps zodb/
ZEO Documentation
=================
This directory contains ZEO documentation.
howto.txt
The first place to look.
It provides a high-level overview of ZEO features and details on
how to install and configure clients and servers. Includes a
configuration reference.
cache.txt
Explains how the client cache works.
trace.txt
Describe cache trace tool used to determine ideal cache size.
ZopeREADME.txt
A somewhat dated description of how to integrate ZEO with Zope.
It provides a few hints that are not yet in howto.txt.
Zope Enterprise Objects (ZEO)
Installation
ZEO 2.0 requires Zope 2.4 or higher and Python 2.1 or higher.
If you use Python 2.1, we recommend the latest minor release
(2.1.3 as of this writing) because it includes a few bug fixes
that affect ZEO.
Put the package (the ZEO directory, without any wrapping directory
included in a distribution) in your Zope lib/python.
The setup.py script in the top-level ZEO directory can also be
used. Run "python setup.py install --home=ZOPE" where ZOPE is the
top-level Zope directory.
You can test ZEO before installing it with the test script::
python test.py -v
Run the script with the -h option for a full list of options. The
ZEO 2.0b2 release contains 122 unit tests on Unix.
Starting (and configuring) the ZEO Server
To start the storage server, go to your Zope install directory and
run::
python lib/python/ZEO/start.py -p port_number
This run the storage sever under zdaemon. zdaemon automatically
restarts programs that exit unexpectedly.
The server and the client don't have to be on the same machine.
If they are on the same machine, then you can use a Unix domain
socket::
python lib/python/ZEO/start.py -U filename
The start script provides a number of options not documented here.
See doc/start.txt for more information.
Running Zope as a ZEO client
To get Zope to use the server, create a custom_zodb module,
custom_zodb.py, in your Zope install directory, so that Zope uses a
ClientStorage::
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(('', port_number))
You can specify a host name (rather than '') if you want. The port
number is, of course, the port number used to start the storage
server.
You can also give the name of a Unix domain socket file::
from ZEO.ClientStorage import ClientStorage
Storage = ClientStorage(filename)
There are a number of configuration options available for the
ClientStorage. See doc/ClientStorage.txt for details.
If you want a persistent client cache which retains cache contents
across ClientStorage restarts, you need to define the environment
variable, ZEO_CLIENT, or set the client keyword argument to the
constructor to a unique name for the client. This is needed so
that unique cache name files can be computed. Otherwise, the
client cache is stored in temporary files which are removed when
the ClientStorage shuts down. For example, to start two Zope
processes with unique caches, use something like::
python z2.py -P8700 ZEO_CLIENT=8700
python z2.py -P8800 ZEO_CLIENT=8800
Zope product installation
Normally, Zope updates the Zope database during startup to reflect
product changes or new products found. It makes no sense for
multiple ZEO clients to do the same installation. Further, if
different clients have different software installed, the correct
state of the database is ambiguous.
Zope will not modify the Zope database during product installation
if the environment variable ZEO_CLIENT is set.
Normally, Zope ZEO clients should be run with ZEO_CLIENT set so
that product initialization is not performed.
If you do install new Zope products, then you need to take a
special step to cause the new products to be properly registered
in the database. The easiest way to do this is to start Zope
once with the environment variable FORCE_PRODUCT_LOAD set.
The interaction between ZEO and Zope product installation is
unfortunate.
This diff is collapsed.
...@@ -142,10 +142,10 @@ Connection management ...@@ -142,10 +142,10 @@ Connection management
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
A ZEO client manages its connection to the ZEO server. If it loses A ZEO client manages its connection to the ZEO server. If it loses
the connection, it starts a thread that attempts to reconnect. While the connection, it attempts to reconnect. While
it is disconnected, it can satisfy some reads by using its cache. it is disconnected, it can satisfy some reads by using its cache.
The client can be configured to wait a connection when it is created The client can be configured to wait for a connection when it is created
or to return immediately and provide data from its persistent cache. or to return immediately and provide data from its persistent cache.
It usually simplifies programming to have the client wait for a It usually simplifies programming to have the client wait for a
connection on startup. connection on startup.
...@@ -192,27 +192,15 @@ Installing software ...@@ -192,27 +192,15 @@ Installing software
------------------- -------------------
ZEO is distributed as part of the ZODB3 package and with Zope, ZEO is distributed as part of the ZODB3 package and with Zope,
starting with Zope 2.7. You can download it from: starting with Zope 2.7. You can download it from
http://pypi.python.org/pypi/ZODB3.
- http://www.zope.org/Products/ZODB3.2, or
- http://www.zope.org/Products/Zope
To use ZEO with Zope 2.6, download ZODB3.2 and install it into your
Zope software home. ZODB3 comes with a distutils setup.py script.
You can use the --home option to setup.py install to the software in
custom location. For example, if Zope is installed in /home/zope,
then this command will install the new ZEO and ZODB:
python setup.py install --home /home/zope
The install command should create a /home/zope/lib/python/ZEO directoy.
Configuring server Configuring server
------------------ ------------------
The script runzeo.py runs the ZEO server. The server can be The script runzeo.py runs the ZEO server. The server can be
configured using command-line arguments or a config file. This configured using command-line arguments or a config file. This
document describes only describes the config file. Run runzeo.py document only describes the config file. Run runzeo.py
-h to see the list of command-line arguments. -h to see the list of command-line arguments.
The runzeo.py script imports the ZEO package. ZEO must either be The runzeo.py script imports the ZEO package. ZEO must either be
...@@ -312,8 +300,8 @@ authentication-realm ...@@ -312,8 +300,8 @@ authentication-realm
schemes use a realm to identify the logic set of usernames schemes use a realm to identify the logic set of usernames
that are accepted by this server. that are accepted by this server.
Configuring client Configuring clients
------------------ -------------------
The ZEO client can also be configured using ZConfig. The ZODB.config The ZEO client can also be configured using ZConfig. The ZODB.config
module provides several function for opening a storage based on its module provides several function for opening a storage based on its
...@@ -330,12 +318,6 @@ specified. Everything else is optional. An example configuration is:: ...@@ -330,12 +318,6 @@ specified. Everything else is optional. An example configuration is::
server zeo.example.com:8090 server zeo.example.com:8090
</zeoclient> </zeoclient>
To use a ZEO client from Zope, write a configuration file and load it
from custom_zodb.py::
from ZODB.config import storageFromURL
Storage = storageFromURL("/path/to/client.txt")
The other configuration options are listed below. The other configuration options are listed below.
storage storage
...@@ -400,9 +382,9 @@ Running the ZEO server as a daemon ...@@ -400,9 +382,9 @@ Running the ZEO server as a daemon
In an operational setting, you will want to run the ZEO server a In an operational setting, you will want to run the ZEO server a
daemon process that is restarted when it dies. The zdaemon package daemon process that is restarted when it dies. The zdaemon package
provides two tools for running daemons: zdrun.py and zdctl.py. The provides two tools for running daemons: zdrun.py and zdctl.py. You can
document "Using zdctl and zdrun to manage server processes" find zdaemon and it's documentation at
(Doc/zdctl.txt) explains how to use these scripts to manage daemons. http://pypi.python.org/pypi/zdaemon.
Rotating log files Rotating log files
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
......
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