[Zodb-checkins] CVS: ZEO/doc - ZopeREADME.txt:1.1.2.1 start.txt:1.1.2.1
Jeremy Hylton
jeremy@zope.com
Tue, 21 May 2002 01:43:04 -0400
Update of /cvs-repository/ZEO/doc
In directory cvs.zope.org:/tmp/cvs-serv26953/doc
Added Files:
Tag: ZEO2-branch
ZopeREADME.txt start.txt
Log Message:
Start moving stuff to the doc tree
=== Added File ZEO/doc/ZopeREADME.txt ===
Zope Enterprise Objects
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.
Starting (and configuring) the ZEO Server
To start the storage server, go to your Zope install directory and::
python lib/python/ZEO/start.py -p port_number
(Run start without arguments to see options.)
Of course, the server and the client don't have to be on the same
machine.
If the server and client *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 docs/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))
(See the misc/custom_zodb.py for an example.)
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::
import ZEO.ClientStorage
Storage=ZEO.ClientStorage.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, 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.
Starting in Zope 2.2, 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. In the future, this interaction will be removed by
=== Added File ZEO/doc/start.txt ===
The ZEO Server start script, start.py
ZEO provides a Python script for starting the ZEO server. The ZEO
server is implemented as a Python class and could be used with other
main programs, however, a simple ZEO server is provided for convenience.
Basic usage
To start the storage server, go to your Zope install directory and::
python lib/python/ZEO/start.py -p port_number
(Run start without arguments to see options.)
Of course, the server and the client don't have to be on the same
machine.
If the server and client *are* on the same machine, then you can use
a Unix domain socket::
python lib/python/ZEO/start.py -U filename
Serving custom storages or multiple storages with the storage server
The Storage server can host multiple storages and can
host any kind of storage. Each storage has a unique storage
name. By default, the ZEO start.py script serves a
standard FileStorage with the name '1'.
You can control what storages are served by creating a Python
file containing definitions for the storages and using the '-S'
option to the start.py script to indicate the storage
to be served. The form of the -S option is::
-Sstorage_name=module_path:attribute_name
Where:
storage_name -- is the storage name used in the ZEO protocol.
This is the name that you give as the optional
'storage' keyword argument to the ClientStorage constructor.
module_path -- This is the path to a Python module
that defines the storage object(s) to be served.
The module path should ommit the prefix (e.g. '.py').
attribute_name -- This is the name to which the storage object
is assigned in the module.
Consider the following example. I want to serve a FileStorage
in read-only mode, which I define in the module file
/stores/fs.py::
import ZODB.FileStorage
Storage=FileStorage.FileStorage('/stores/fs1.fs', read_only=1)
I then start start.py with the argument::
python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-S 1=/stores/fs:Storage
This option says to serve storage '1'. Storage '1' is
found in attribute 'Storage' from the module
'/stores/fs'.
Now consider a more complicated example. I want to serve the storage
from the previous example. I also want to serve two Oracle
storages that are defined in the file '/stores/oracle.py'::
import DCOracle, DCOracleStorage
system=DCOracleStorage.DCOracleStorage(
lambda : DCOracle.Connect('system/manager@spamservice')
)
scott=DCOracleStorage.DCOracleStorage(
lambda : DCOracle.Connect('scott/tiger@spamservice')
)
I simply need to include three -S options::
python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
-Ssystem=/stores/oracle:system \
-Sscott=/stores/oracle:scott \
-S1=/stores/fs:Storage
In this case, we made the storage and attribute name the
same. To connect to the 'system' or 'scott' storage, we
need to specify the storage in the ClientStorage constructor, as
in::
import ZEO.ClientStorage
Storage=ZEO.ClientStorage.ClientStorage(
'/xxx/var/zeo.sock', storage='scott')
Options
The ZEO server start script is run with one or more command line
options. An optional FileStorage file name may be provided after the
options. The options are as follows:
-D -- Run in debug mode
In debug mode, the process is not run in the background
and detailed debugging information is logged.
Note that to actually log this information, you need to
configure logging to include very low-severity (< -300) log
entries. For example, to configure the stupid logger to log
these messages, set the environment veriable
'STUPID_LOG_SEVERITY' to -999.
-U -- Unix-domain socket file to listen on
If you want to accept connections on a Unix domain socket, then
use this option to specify the socket file name.
-u username or uid number
The username to run the ZEO server as. You may want to run
the ZEO server as 'zope' or some other user with limited
resouces. The only works under Unix, and if ZServer is
started by root.
If the server *is* started as root, the 'nobody' user if this
option isn't used.
-p port -- port to listen on
Use this option together with the '-h' option to specify a host
and port to listen on.
-h adddress -- host address to listen on
Use this option together with the '-p' option to specify a host
and port to listen on.
-s -- Don't use zdeamon
This option has no effect on Unix.
-S storage_name=module_path:attr_name -- A storage specification
where:
storage_name -- is the storage name used in the ZEO protocol.
This is the name that you give as the optional
'storage' keyword argument to the ClientStorage constructor.
module_path -- This is the path to a Python module
that defines the storage object(s) to be served.
The module path should ommit the prefix (e.g. '.py').
attr_name -- This is the name to which the storage object
is assigned in the module.