zc.recipe.deployment 0.4

ZC Buildout recipe for Unix deployments

The zc.recipe.deployment recipe provides support for deploying applications with multiple processes on Unix systems. (Perhaps support for other systems will be added later.) It creates directories to hold application instance configuration, log and run-time files. It also sets or reads options that can be read by other programs to find out where to place files:

crontab-directory

The name of the directory in which cron jobs should be placed. This is /etc/cron.d.

etc-directory

The name of the directory where configuration files should be placed. This is /etc/NAME, where NAME is the deployment name.

log-directory

The name of the directory where application instances should write their log files. This is /var/log/NAME, where NAME is the deployment name.

logrotate-directory

The name of the directory where logrotate configuration files should be placed, typically, /etc/logrotate.d.

run-directory

The name of the directory where application instances should put their run-time files such as pid files and inter-process communication socket files. This is /var/run/NAME, where NAME is the deployment name.

rc-directory

The name of the directory where run-control scripts should be installed. This is /etc/init.d.

The etc, log, and run directories are created in such a way that the directories are owned by the user specified in the user option and are writable by the user and the user’s group.

Changes

0.4 (Mar 22, 2007)

Features Added

• Added setting for the logrotate configuration directories.

Bugs Fixed

• The documentation gave the wrong name for the crontab-directory option.

0.3 (Feb 14, 2007)

Features Added

• Added a configuration recipe for creating configuration files.

0.2.1 (Feb 13, 2007)

• Fixed bug in setup file.

0.2 (Feb 7, 2007)

Bugs Fixed

• Non-empty log and run directories were deleated in un- and re-install.

Detailed Documentation

Using the deplyment recipe is pretty simple. Simply specify a deployment name, specified via the part name, and a deployment user.

Let’s add a deployment to a sample buildout:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo
...
... [foo]
... recipe = zc.recipe.deployment
... user = jim
... ''')

>>> print system(join('bin', 'buildout')),
buildout: Installing foo
zc.recipe.deployment:
    Creating '/etc/foo',
    mode 755, user 'root', group 'root'
zc.recipe.deployment:
    Creating '/var/log/foo',
    mode 755, user 'jim', group 'jim'
zc.recipe.deployment:
    Creating '/var/run/foo',
    mode 750, user 'jim', group 'jim'

(Note that we have to be running as root and must have a user jim for this to work.)

Now we can see that directories named foo in /etc, /var/log and /var/run have been created:

>>> print system('ls -ld /etc/foo'),
drwxr-xr-x 2 root root 4096 2007-02-06 09:50 /etc/foo

>>> print system('ls -ld /var/log/foo'),
drwxr-xr-x 2 jim jim 4096 2007-02-06 09:50 /var/log/foo

>>> print system('ls -ld /var/run/foo'),
drwxr-x--- 2 jim jim 40 2007-02-06 09:50 /var/run/foo

By looking at .installed.cfg, we can see the options available for use by other recipes:

>>> cat('.installed.cfg')
... # doctest: +ELLIPSIS
[buildout]
...
[foo]
__buildout_installed__ =
...
crontab-directory = /etc/cron.d
etc-directory = /etc/foo
log-directory = /var/log/foo
logrotate-directory = /etc/logrotate.d
rc-directory = /etc/init.d
recipe = zc.recipe.deployment
run-directory = /var/run/foo
user = jim

If we ininstall, then the directories are removed.

>>> print system(join('bin', 'buildout')+' buildout:parts='),
buildout: Uninstalling foo
buildout: Running uninstall recipe
zc.recipe.deployment: Removing '/etc/foo'
zc.recipe.deployment: Removing '/var/log/foo'.
zc.recipe.deployment: Removing '/var/run/foo'.

>>> import os
>>> os.path.exists('/etc/foo')
False
>>> os.path.exists('/var/log/foo')
False
>>> os.path.exists('/var/run/foo')
False

The log and run directories are only removed if they are non-empty. To see that, we’ll put a file in each of the directories created:

>>> print system(join('bin', 'buildout')), # doctest: +ELLIPSIS
buildout: Installing foo
...

>>> write('/etc/foo/x', '')
>>> write('/var/log/foo/x', '')
>>> write('/var/run/foo/x', '')

And then uninstall:

>>> print system(join('bin', 'buildout')+' buildout:parts='),
buildout: Uninstalling foo
buildout: Running uninstall recipe
zc.recipe.deployment: Removing '/etc/foo'
zc.recipe.deployment: Can't remove non-empty directory '/var/log/foo'.
zc.recipe.deployment: Can't remove non-empty directory '/var/run/foo'.

>>> os.path.exists('/etc/foo')
False

>>> print system('ls -ld /var/log/foo'),
drwxr-xr-x 2 jim jim 4096 2007-02-06 09:50 /var/log/foo

>>> print system('ls -ld /var/run/foo'),
drwxr-x--- 2 jim jim 40 2007-02-06 09:50 /var/run/foo

Here we see that the var and run directories are kept. The etc directory is discarded because only buildout recipes should write to it and all of it’s data are expendible.

If we reinstall, remove the files, and uninstall, then the directories are removed:

>>> print system(join('bin', 'buildout')),
buildout: Installing foo
zc.recipe.deployment:
    Creating '/etc/foo',
    mode 755, user 'root', group 'root'
zc.recipe.deployment:
    Updating '/var/log/foo',
    mode 755, user 'jim', group 'jim'
zc.recipe.deployment:
    Updating '/var/run/foo',
    mode 750, user 'jim', group 'jim'

>>> os.remove('/var/log/foo/x')
>>> os.remove('/var/run/foo/x')

>>> print system(join('bin', 'buildout')+' buildout:parts='),
buildout: Uninstalling foo
buildout: Running uninstall recipe
zc.recipe.deployment: Removing '/etc/foo'
zc.recipe.deployment: Removing '/var/log/foo'.
zc.recipe.deployment: Removing '/var/run/foo'.

>>> os.path.exists('/etc/foo')
False
>>> os.path.exists('/var/log/foo')
False
>>> os.path.exists('/var/run/foo')
False

Configuration files

Normally, configuration files are created by specialized recipes. Sometimes, it’s useful to specifu configuration files in a buildout cnfiguration file. The zc.recipe.deployment:configuration recipe can be used to do that.

Let’s add a configuration file to our buildout:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... user = jim
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... ''')

>>> print system(join('bin', 'buildout')),
buildout: Installing foo
zc.recipe.deployment:
    Creating '/etc/foo',
    mode 755, user 'root', group 'root'
zc.recipe.deployment:
    Creating '/var/log/foo',
    mode 755, user 'jim', group 'jim'
zc.recipe.deployment:
    Creating '/var/run/foo',
    mode 750, user 'jim', group 'jim'
buildout: Installing x.cfg

By default, the configuration is installed as a part:

>>> cat('parts', 'x.cfg')
xxx
yyy
zzz

If a deployment is specified, then the file is placed in the deployment etc directory:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... user = jim
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... deployment = foo
... ''')

>>> print system(join('bin', 'buildout')),
buildout: Uninstalling x.cfg
buildout: Updating foo
buildout: Installing x.cfg

>>> os.path.exists(join('parts', 'x.cfg'))
False

>>> cat('/etc/foo/x.cfg')
xxx
yyy
zzz

We can read data from a fiile rather than specifying in the configuration:

>>> write('x.in', '1\n2\n3\n')

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... user = jim
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... file = x.in
... deployment = foo
... ''')

>>> print system(join('bin', 'buildout')),
buildout: Uninstalling x.cfg
buildout: Updating foo
buildout: Installing x.cfg

>>> cat('/etc/foo/x.cfg')
1
2
3

The recipe sets a location option that can be used by other recipes:

>>> cat('.installed.cfg') # doctest: +ELLIPSIS
[buildout]
...
[x.cfg]
...
location = /etc/foo/x.cfg
...

Download