source: main/waeup.custom/trunk/README-zeo.txt @ 8181

Deploying waeup.custom as ZEO-install
*************************************

Each ZEO install consists of at least one ZEO server and normally two
or more ZEO clients. While the ZEO server is meant to manage the ZODB
database for clients, the clients connect to the outside world, listen
for request and do the real dataprocessing.

We prepared a `buildout` configuration that sets up one server
configuration and two client configs. This configuration is in
``buildout-zeo.cfg``.

Generating the ZEO setup
========================

To install waeup.custom ZEO-based you can run `buildout` with the given
(or your own) configuration file like this::

  $ ./bin/buildout -c buildout-zeo.cfg

This should generate all scripts necessary to run servers, clients,
etc.

Starting ZEO servers and clients
================================

First start the server::

  $ ./bin/zeo_server start

Clients can be started by doing::

  $ ./bin/zeo_client1 start
  $ ./bin/zeo_client2 start

This will start both clients in daemon mode.

Instead of ``start`` you can, as usually, start an instance in
foreground (``fg``), etc. You know the drill.

Manually starting ZEO clients
-----------------------------

This is normally not neccessary.

``zeo_clientN`` scripts are basically wrappers around calls to
``bin/paster``. You can bypass this wrapper and start a client
'manually' like this::

  $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
        pars/etc/zeo1.ini

It is important to give a pid-file as paster otherwise can not start
different clients (they would all refer to the same pid file
`paster.pid` and refuse to start after the first client was started).


Setup (paramters, ports, etc.)
==============================

By default the server will listen on port 8100 for requests from
localhost (not: from the outside world).

You can change ZEO server settings in the ``[zeo_server]`` section
of ``buildout-zeo.conf``. Run `buildout` afterwards.

The clients will listen on port 8081 and 8082. You can change settings
in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
buildout after any change.

If you want to change the paster wrapper for any zeo client, you can
edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
afterwards.

Creating new clients
====================

You want more clients to be created by buildout? Easy. Three steps are
neccessary.

1. Create config files in etc/
------------------------------

Each client needs two configuration files:

  - ``etc/zeoN.conf``
       configuring the paster wrapper

  - ``etc/zeoN.ini``
       configuring the runtime config, ports, etc.

Just copy over these files from the already existing zeo1/zeo2 files
and replace ``zeo1`` or ``zeo2`` with your new name.

2. Update buildout-zeo.cfg
--------------------------

Here, inside ``buildourt-zeo.cfg`` also three steps are needed.

* 2.1. Create new .ini and .conf entries

  The .conf and .ini files in etc/ are only templates that have to be
  generated in their really used final location. In buildout-zeo.cfg
  you can care for this by creating a new ``[zeoN_ini]`` and
  ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).

  Just copy over existing entries and replace the mentions of ``zeo1``
  or ``zeo2`` by your ``zeoN``.

* 2.2. Create a new ``zeo_clientN`` entry

  Then you have to create an entry that will generate the
  ``zeo_clientN`` script. Again, just copy over an existing
  ``[zeo_client1]`` entry and replace ``1`` withg your client number.

* 2.3. Register the new sections in ``[buildout]`` section

  When done with the above: add the new section in ``[buildout]``::

    [buildout]
      ...
      <old entries...>
      ...
      zope_conf_zeo_5
      zeo5_ini
      zeo_client5

  depending on how you named your new sections.

3. Rerun ``buildout``
---------------------

When adding or removing client/server instances, make sure to stop all
running servers/clients before rerunning buildout.

To activate the new setup, rerun buildout::

  $ bin/buildout -c buildout-zeo.cfg

This should generate any new clients and remove older ones or just
update configuration files.


Considerations
==============

There are some things in the current buildout-zeo.cfg we might do not
want. It extends the regular ``buildout.cfg`` so that we do not have
to repeat most sections but the ``parts`` in ``[buildout]`` have to be
listed.

We need, however, not everything with a ZEO-deploy that is listed in a
default buildout. We might do not need docs, no profiling, etc. Also a
regular non-ZEO kofactl might not make to much sense. Therefore all
this might be subject to changes.