zc.zodbrecipes 0.2.1

************
ZODB Recipes
************

Recipes for working with ZODB.

Changes
*******

0.2.1 (2007-04-23)
================

Bugs Fixed
----------

- crontab and logrotate configuration files were being generates incorrectly.

0.2 (2007-04-17)
================

Added handling of %import directives.

0.1 (2007-04-13)
================

Initial release.

.. contents::

Detailed Documentation
**********************

Defining ZEO Storage Servers
============================

The zc.zodbrecipes:server recipe can be used to define ZEO storage
servers. To define a storage server, you define a part for the server
and specify configuration data.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = server
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... ''')

Here we specified a minimal configuration using a "foo" storage. We
can use aby kind of storage we want. Here we ised an import statement
to import the schema definition that defined the foo section. Any
imports are simply copied to the generated configuration file. When
we run the buildout:

>>> print system(buildout),
buildout: Installing server
zc.zodbrecipes:
A runzeo script couldn't be found at:
<BLANKLINE>
'/sample-buildout/bin/runzeo'
<BLANKLINE>
You may need to generate a runzeo script using the
zc.recipe.eggs:script recipe and the ZODB3 egg, or you may need
to specify the location of a script using the runzeo option.
<BLANKLINE>

We got a warning because the recipe expects there to be a runzeo
script and we haven't created one. This is done using the
zc.recipe.egg:script recipe:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = zodb server
...
... [zodb]
... recipe = zc.recipe.egg:script
... eggs = ZODB3
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... ''')

>>> print system(buildout),
buildout: Installing zodb
buildout: Updating server

We get 2 things. We get a directory in parts containing ZEO and
zdaemon configuration files:

>>> ls('parts', 'server')
- zdaemon.conf
- zeo.conf

Let's look at the configuration files:

>>> cat('parts', 'server', 'zeo.conf')
%import foo
<BLANKLINE>
<zeo>
address 8100
monitor-address 8101
transaction-timeout 300
</zeo>
<BLANKLINE>
<foo main>
path /databases/Data.fs
</foo>
<BLANKLINE>
<eventlog>
<logfile>
path STDOUT
</logfile>
<BLANKLINE>
</eventlog>

We see the same data we input with the addition of an eventlog section
that directs logging to standard out. In production, we'll use
zdaemon's transacript log to capture this logging output in a file.
If we wish, we can specify a log file ourselves:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = zodb server
...
... [zodb]
... recipe = zc.recipe.egg:script
... eggs = ZODB3
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... <eventlog>
... <logfile>
... path /var/log/zeo.log
... </logfile>
... </eventlog>
... ''')

>>> print system(buildout),
buildout: Uninstalling server
buildout: Updating zodb
buildout: Installing server

>>> cat('parts', 'server', 'zeo.conf')
%import foo
<BLANKLINE>
<zeo>
address 8100
monitor-address 8101
transaction-timeout 300
</zeo>
<BLANKLINE>
<foo main>
path /databases/Data.fs
</foo>
<BLANKLINE>
<eventlog>
<logfile>
path /var/log/zeo.log
</logfile>
<BLANKLINE>
</eventlog>

But we'll stick with the default:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = zodb server
...
... [zodb]
... recipe = zc.recipe.egg:script
... eggs = ZODB3
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... ''')

>>> print system(buildout),
buildout: Uninstalling server
buildout: Updating zodb
buildout: Installing server

Let's look at the zdaemon log file:

>>> cat('parts', 'server', 'zdaemon.conf')
<runner>
daemon on
directory /sample-buildout/parts/server
program /sample-buildout/bin/runzeo -C /sample-buildout/parts/server/zeo.conf
socket-name /sample-buildout/parts/server/zdaemon.sock
transcript /sample-buildout/parts/server/zeo.log
</runner>
<BLANKLINE>
<eventlog>
<logfile>
path /sample-buildout/parts/server/zeo.log
</logfile>
<BLANKLINE>
</eventlog>

We run the runzeo script with the zeo.conf file. Log and run-time
files are places in the server part directory. We use a transcript
log to provide the ZEO server log. I like to use the transacriot log
because it captures program output, such as start-up exceptions that
aren't captured in a program's logs.

And we get a control script generated in our bin directory:

>>> cat('bin', 'server')
#!/usr/local/bin/python2.4
<BLANKLINE>
import sys
sys.path[0:0] = [
'/sample-buildout/eggs/zdaemon-2.0-py2.4.egg',
'/sample-buildout/eggs/setuptools-0.6-py2.4.egg',
'/sample-buildout/eggs/ZConfig-2.4-py2.4.egg',
]
<BLANKLINE>
import zdaemon.zdctl
<BLANKLINE>
if __name__ == '__main__':
zdaemon.zdctl.main([
'-C', '/sample-buildout/parts/server/zdaemon.conf',
]+sys.argv[1:]
)

This is a zdaemon script. We can use this to control the ZEO server
process.

Unix Deployment support
=======================

The server recipe works with the zc.recipe.deployment. In particular,
if a deployment option is specified, it names a part or section that
defines the following uptions:

crontab-directory
A directory for crontab files.

etc-directory
A directory for configuration files.

log-directory
A directory for log files.

logrotate-directory
A directory for logrotate configuration files.

rc-directory
A directory for run-control scripts.

run-directory
A directory for run-time files.

user
The user the server process should run as

Let's create some directories and add a deployment section to our
buildout:

>>> for d in 'cron', 'etc', 'log', 'rotate', 'rc', 'run':
... mkdir(d)
... globals()[d] = join(sample_buildout, d)

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = zodb server
...
... [zodb]
... recipe = zc.recipe.egg:script
... eggs = ZODB3
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %%import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... deployment = demo
...
... [demo]
... crontab-directory = %(cron)s
... etc-directory = %(etc)s
... log-directory = %(log)s
... logrotate-directory = %(rotate)s
... rc-directory = %(rc)s
... run-directory = %(run)s
... user = bob
... ''' % globals())

>>> print system(buildout),
buildout: Uninstalling server
buildout: Updating zodb
buildout: Installing server

Now, the parts directory and the control script will be gone:

>>> import os
>>> os.path.exists(join('parts', 'server'))
False
>>> os.path.exists(join('bin', 'server'))
False

Instead, the control script will be in the rc directory:

>>> ls('rc')
- demo-server

The run-control script name now combines the deployment name and the
script name.

and the configuration files will be in the etc directory:

>>> ls('etc')
- server-zdaemon.conf
- server-zeo.conf

In additional we'll get a logrotate configuration file:

>>> cat('rotate', 'demo-server')
/sample-buildout/log/server-zeo.log {
rotate 5
weekly
postrotate
/sample-buildout/rc/demo-server -C /sample-buildout/etc/server-zdaemon.conf reopen_transcript
endscript
}

This will rotate the zeo log file once a week.

If we look at the zdaemon configuration file, we can see that it reflects
the deployment locations:

>>> cat('etc', 'server-zdaemon.conf')
<runner>
daemon on
directory /sample-buildout/run
program /sample-buildout/bin/runzeo -C /sample-buildout/etc/server-zeo.conf
socket-name /sample-buildout/run/server-zdaemon.sock
transcript /sample-buildout/log/server-zeo.log
user bob
</runner>
<BLANKLINE>
<eventlog>
<logfile>
path /sample-buildout/log/server-zeo.log
</logfile>
<BLANKLINE>
</eventlog>

Note that different file names are used. Since a deployment may be
(and usually is) shared by multiple parts, files are prefixed with
their part names. Also note that the deployment user is set in the
zdaemon configuration.

We can request definition of a cron job to pack the databases by
specifying a pack option. This option takes 5 or 6 values. The
first 5 values are the time and date fields defined by Unix crontab
files. The last field is the number of days in the past to pack to and
defaults to 1.

Let's add a pack option:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = zodb server
...
... [zodb]
... recipe = zc.recipe.egg:script
... eggs = ZODB3
...
... [server]
... recipe = zc.zodbrecipes:server
... zeo.conf =
... <zeo>
... address 8100
... monitor-address 8101
... transaction-timeout 300
... </zeo>
... %%import foo
... <foo main>
... path /databases/Data.fs
... </foo>
... deployment = demo
... pack = 1 1 * * 0 3
...
... [demo]
... crontab-directory = %(cron)s
... etc-directory = %(etc)s
... log-directory = %(log)s
... logrotate-directory = %(rotate)s
... rc-directory = %(rc)s
... run-directory = %(run)s
... user = bob
... ''' % globals())

>>> print system(buildout+' -D'),
buildout: Uninstalling server
buildout: Updating zodb
buildout: Installing server

Now, we'll get a crontab file:

>>> cat(cron, 'pack-demo-server')
1 1 * * 0 bob /sample-buildout/bin/zeopack -p 8100 -S main -d 3

In this example, we'll pack the databases every Sunday at 1:01 to 3
days.

Download
**********************