Metadata-Version: 1.0
Name: zc.recipe.deployment
Version: 0.3
Summary: ZC Buildout recipe for Unix deployments
Home-page: http://www.python.org/pypi/zc.recipe.deployment
Author: Jim Fulton
Author-email: jim@zope.com
License: ZPL 2.1
Description: ***********************
        Unix Deployment Support
        ***********************
        
        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:
        
        cron-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.
        
        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.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
        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
        ...
        
        
        .. cleanup
        
        >>> print system(join('bin', 'buildout')+' buildout:parts='),
        buildout: Uninstalling x.cfg
        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'.
        
        Download
        **********************
        
Keywords: deployment build
Platform: UNKNOWN
