zc.recipe.deployment 1.2.0

1.2.0 (2014-02-04)

• Added an on-change option to the configuration recipe to run a command when a configuration file changes.

1.1.0 (2013-11-04)

• Do not touch an existing configuration file if the content hasn’t changed.

1.0.0 (2013-04-24)

• Added a name option to the configuration recipe to allow explicit control of generated file paths.

0.10.2 (2013-04-10)

• Fix packaging bug.

0.10.1 (2013-04-10)

• Fix for 0.9 -> 0.10 .installed.cfg migration

0.10.0 (2013-03-28)

• Add etc-prefix and var-prefix to specify new locations of these entire trees. Final versions of these paths are exported.

• Previously undocumented & untested etc, log and run settings are deprecated. Warnings are logged if their values are used.

• Add cache-directory and lib-directory to the set of output directories.

• Add system-wide configuration, allowing locations of the “root” directories to be specified for an entire machine.

• Allow *-directory options (e.g. log-directory) to be overridden by configuration data.

0.9.0 (2011-11-21)

• Fixed test dependencies.

• Using Python’s doctest module instead of deprecated zope.testing.doctest.

• Added a directory option for configuration to override default etc directory.

0.8.0 (2010-05-18)

Features Added

Added recipe for updating configuration files that may shared by multiple applications.

0.7.1 (2010-03-05)

Bugs fixed

• Fixed a serious bug that cause buildouts to fail when using new versions of the deployment recipe with older buildouts.

• Made uninstall more tolerant of directories it’s about to delete already being deleted.

0.7.0 (2010-02-01)

Features Added

You can now specify a user for crontab entries that is different than a deployment user.

0.6 (2008-02-01)

Features Added

Added the ability to specify a name independent of the section name. Also, provide a name option for use by recipes.

Important note to recipe authors: Recipes should use the deployment name option rather than the deployment name when computing names of generated files.

0.5 (Mar 23, 2007)

Features Added

Added recipe for generating crontab files in /etc/cron.d.

0.4 (Mar 22, 2007)

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.

Deployment Name

The deployment name is used for naming generated files and directories. The deployment name defaults to the section name, but the deployment name can be specified explicitly:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... name = bar
... user = %s
... etc-user = %s
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Installing foo.
zc.recipe.deployment:
    Creating 'PREFIX/etc/bar',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/cache/bar',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/lib/bar',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/log/bar',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/run/bar',
    mode 750, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/cron.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/init.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/logrotate.d',
    mode 755, user 'USER', group 'GROUP'

>>> print ls(os.path.join(sample_buildout, 'etc/bar'))
drwxr-xr-x USER GROUP PREFIX/etc/bar

>>> print ls(os.path.join(sample_buildout, 'var/cache/bar'))
drwxr-xr-x USER GROUP PREFIX/var/cache/bar

>>> print ls(os.path.join(sample_buildout, 'var/lib/bar'))
drwxr-xr-x USER GROUP PREFIX/var/lib/bar

>>> print ls(os.path.join(sample_buildout, 'var/log/bar'))
drwxr-xr-x USER GROUP PREFIX/var/log/bar

>>> print ls(os.path.join(sample_buildout, 'var/run/bar'))
drwxr-x--- USER GROUP PREFIX/var/run/bar

>>> cat('.installed.cfg') # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
[buildout]
installed_develop_eggs =
parts = foo
<BLANKLINE>
[foo]
__buildout_installed__ =
...
cache-directory = PREFIX/var/cache/bar
crontab-directory = PREFIX/etc/cron.d
etc-directory = PREFIX/etc/bar
etc-prefix = PREFIX/etc
etc-user = USER
lib-directory = PREFIX/var/lib/bar
log-directory = PREFIX/var/log/bar
logrotate-directory = PREFIX/etc/logrotate.d
name = bar
prefix = PREFIX
rc-directory = PREFIX/etc/init.d
recipe = zc.recipe.deployment
run-directory = PREFIX/var/run/bar
user = USER
var-prefix = PREFIX/var

Note (here and earlier) that the options include the name option, which defaults to the part name. Other parts that use the deployment name should use the name option rather than the part name.

Configuration files

Normally, configuration files are created by specialized recipes. Sometimes, it’s useful to specify configuration files in a buildout configuration 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
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling foo.
Running uninstall recipe.
zc.recipe.deployment: Removing 'PREFIX/etc/bar'
zc.recipe.deployment: Removing 'PREFIX/etc/cron.d'.
zc.recipe.deployment: Removing 'PREFIX/etc/init.d'.
zc.recipe.deployment: Removing 'PREFIX/etc/logrotate.d'.
zc.recipe.deployment: Removing 'PREFIX/var/cache/bar'.
zc.recipe.deployment: Removing 'PREFIX/var/lib/bar'.
zc.recipe.deployment: Removing 'PREFIX/var/log/bar'.
zc.recipe.deployment: Removing 'PREFIX/var/run/bar'.
Installing foo.
zc.recipe.deployment:
    Creating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/cache/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/lib/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/log/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/run/foo',
    mode 750, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/cron.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/init.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/etc/logrotate.d',
    mode 755, user 'USER', group 'GROUP'
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
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling x.cfg.
Updating foo.
Installing x.cfg.
zc.recipe.deployment:
    Updating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'

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

>>> cat(os.path.join(sample_buildout, 'etc/foo/x.cfg'))
xxx
yyy
zzz

If a directory is specified, then the file is placed in the directory.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... directory = etc/foobar
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling x.cfg.
Updating foo.
Installing x.cfg.
zc.recipe.deployment:
    Creating 'PREFIX/etc/foobar',
    mode 755, user 'USER', group 'GROUP'

>>> os.path.exists(join('parts', 'x.cfg'))
False
>>> os.path.exists(join(sample_buildout, 'etc/foo/x.cfg'))
False

>>> cat(os.path.join(sample_buildout, 'etc/foobar/x.cfg'))
xxx
yyy
zzz

A directory option works only with a deployment option.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... text = xxx
...        yyy
...        zzz
... directory = etc/foobar
... ''' % (sample_buildout, user, user))

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

>>> os.path.exists(join('parts', 'x.cfg'))
True
>>> os.path.exists(join(sample_buildout, 'etc/foobar/x.cfg'))
False

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

We can read data from a file 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
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... file = x.in
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling x.cfg.
Updating foo.
Installing x.cfg.
zc.recipe.deployment:
    Updating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'

>>> cat(os.path.join(sample_buildout, '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 = PREFIX/etc/foo/x.cfg
...

By default, the part name is used as the file name. You can specify a name explicitly using the name option:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... name = y.cfg
... text = this is y
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling x.cfg.
Updating foo.
Installing x.cfg.
zc.recipe.deployment:
    Updating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'

>>> cat(os.path.join(sample_buildout, 'etc/foo/y.cfg'))
this is y

If name is given, only the file so named is created:

>>> ls(os.path.join(sample_buildout, 'etc', 'foo', 'x.cfg'))
Traceback (most recent call last):
OSError: [Errno 2] No such file or directory: 'PREFIX/etc/foo/x.cfg'

The name can be a path, or even absolute:

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo x.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [x.cfg]
... recipe = zc.recipe.deployment:configuration
... name = ${buildout:directory}/y.cfg
... text = this is y also
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling x.cfg.
Updating foo.
Installing x.cfg.
zc.recipe.deployment:
    Updating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'

>>> cat('y.cfg')
this is y also

If the content of the configuration file is unchanged between builds, and the path hasn’t been changed, the file isn’t actually written in subsequent builds. This is helpful if processes that use the file watch for changes.

>>> mod_time = os.stat('y.cfg').st_mtime

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Updating foo.
Updating x.cfg.
zc.recipe.deployment:
    Updating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'

>>> os.stat('y.cfg').st_mtime == mod_time
True

Cron support

The crontab recipe provides support for creating crontab files. It uses a times option to specify times to run the command and a command option containing the command.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo cron
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [cron]
... recipe = zc.recipe.deployment:crontab
... times = 30 23 * * *
... command = echo hello world!
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')),
Updating foo.
Installing cron.

This example creates PREFIX/etc/cron.d/foo-cron

>>> open(os.path.join(sample_buildout, 'etc/cron.d/foo-cron')).read()
'30 23 * * *\tUSER\techo hello world!\n'

The crontab recipe gets its user from the buildout’s deployment by default, but it doesn’t have to.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo cron
...
... [foo]
... recipe = zc.recipe.deployment
... name = bar
... prefix = %s
... user = %s
... etc-user = %s
...
... [cron]
... recipe = zc.recipe.deployment:crontab
... times = 30 23 * * *
... user = bob
... command = echo hello world!
... deployment = foo
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling cron.
Updating foo.
Installing cron.

>>> open('etc/cron.d/bar-cron').read()
'30 23 * * *\tbob\techo hello world!\n'

SharedConfig

This recipe can be used to update configuration files that are shared by multiple applications. The absolute path of the file must be specified. Also, the configuration files must accept comments that start with “#”.

Like the configuration recipe, the content to add in the configuration file can be provided using the “text” or the “file” option.

First let’s create a file that will be used as the shared configuration file.

>>> open('y.cfg', 'w').write(
... '''Some
... existing
... configuration
... ''')

We now create our buildout configuration and use the “sharedconfig” recipe and run buildout.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo y.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [y.cfg]
... recipe = zc.recipe.deployment:sharedconfig
... path = y.cfg
... deployment = foo
... text = xxx
...        yyy
...        zzz
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Installing foo.
zc.recipe.deployment:
    Creating 'PREFIX/etc/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/cache/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/lib/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/log/foo',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Creating 'PREFIX/var/run/foo',
    mode 750, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Updating 'PREFIX/etc/cron.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Updating 'PREFIX/etc/init.d',
    mode 755, user 'USER', group 'GROUP'
zc.recipe.deployment:
    Updating 'PREFIX/etc/logrotate.d',
    mode 755, user 'USER', group 'GROUP'
Installing y.cfg.

>>> print open('y.cfg', 'r').read()
Some
existing
configuration
<BLANKLINE>
#[foo_y.cfg DO NOT MODIFY LINES FROM HERE#
xxx
yyy
zzz
#TILL HERE foo_y.cfg]#
<BLANKLINE>

Running buildout again without modifying the configuration leaves the file the same.

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Updating foo.
Updating y.cfg.

>>> print open('y.cfg', 'r').read()
Some
existing
configuration
<BLANKLINE>
#[foo_y.cfg DO NOT MODIFY LINES FROM HERE#
xxx
yyy
zzz
#TILL HERE foo_y.cfg]#
<BLANKLINE>

If we add some more lines to the file

>>> open('y.cfg', 'a').write(
... '''Some
... additional
... configuration
... ''')

and run buildout again, but this time after modifying the configuration for “y.cfg”, the sections will be moved to the end of the file.

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo y.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [y.cfg]
... recipe = zc.recipe.deployment:sharedconfig
... path = y.cfg
... deployment = foo
... text = 111
...        222
...        333
... ''' % (sample_buildout, user, user))

>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling y.cfg.
Running uninstall recipe.
Updating foo.
Installing y.cfg.

>>> print open('y.cfg', 'r').read()
Some
existing
configuration
Some
additional
configuration
<BLANKLINE>
#[foo_y.cfg DO NOT MODIFY LINES FROM HERE#
111
222
333
#TILL HERE foo_y.cfg]#
<BLANKLINE>

The text to append to the shared configuration file can also be provided via a file.

>>> write('x.cfg', '''
... [foo]
... a = 1
... b = 2
...
... [log]
... c = 1
... ''')

>>> write('buildout.cfg',
... '''
... [buildout]
... parts = foo y.cfg
...
... [foo]
... recipe = zc.recipe.deployment
... prefix = %s
... user = %s
... etc-user = %s
...
... [y.cfg]
... recipe = zc.recipe.deployment:sharedconfig
... path = %s/etc/z.cfg
... deployment = foo
... file = x.cfg
... ''' % (sample_buildout, user, user, sample_buildout))
>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
While:
  Installing.
  Getting section y.cfg.
  Initializing part y.cfg.
Error: Path 'PREFIX/etc/z.cfg' does not exist

Oops. The path of the configuration file must exist. Let’s create one.

>>> write(join(sample_buildout, 'etc', 'z.cfg'), '')
>>> print system(join('bin', 'buildout')), # doctest: +NORMALIZE_WHITESPACE
Uninstalling y.cfg.
Running uninstall recipe.
Updating foo.
Installing y.cfg.

>>> print open(join(sample_buildout, 'etc', 'z.cfg'), 'r').read()
<BLANKLINE>
#[foo_y.cfg DO NOT MODIFY LINES FROM HERE#
<BLANKLINE>
[foo]
a = 1
b = 2
<BLANKLINE>
[log]
c = 1
<BLANKLINE>
#TILL HERE foo_y.cfg]#
<BLANKLINE>

While uninstalling, only the lines that the recipe installed are removed.

>>> print system(join('bin', 'buildout')+' buildout:parts='),
Uninstalling y.cfg.
Running uninstall recipe.
Uninstalling foo.
Running uninstall recipe.
zc.recipe.deployment: Removing 'PREFIX/etc/foo'
zc.recipe.deployment: Removing 'PREFIX/etc/cron.d'.
zc.recipe.deployment: Removing 'PREFIX/etc/init.d'.
zc.recipe.deployment: Removing 'PREFIX/etc/logrotate.d'.
zc.recipe.deployment: Removing 'PREFIX/var/cache/foo'.
zc.recipe.deployment: Removing 'PREFIX/var/lib/foo'.
zc.recipe.deployment: Removing 'PREFIX/var/log/foo'.
zc.recipe.deployment: Removing 'PREFIX/var/run/foo'.

But the files are not deleted.

>>> os.path.exists('y.cfg')
True

>>> print open('y.cfg', 'r').read()
Some
existing
configuration
Some
additional
configuration
<BLANKLINE>

>>> os.path.exists(join(sample_buildout, 'etc', 'z.cfg'))
True

>>> print open(join(sample_buildout, 'etc', 'z.cfg'), 'r').read()
<BLANKLINE>