Why Cookiecutter for Zope configuration?

This page explains the rationale behind using cookiecutter as the configuration engine for Zope instances, replacing the older buildout-based approach.

The problem: replacing buildout

For many years, the Plone and Zope community used buildout with the plone.recipe.zope2instance recipe to generate Zope instance configurations. While functional, this approach had drawbacks:

  • Buildout is a complex tool with a steep learning curve

  • The recipe used Python string templates that were not intuitive to write or maintain

  • Configuration generation was tightly coupled to the buildout execution model

  • The broader Python ecosystem has moved away from buildout toward standard packaging tools (pip, setuptools, etc.)

The idea: cookiecutter

Cookiecutter is a widely used, well-maintained utility for creating text-based file-system structures from templates. It uses Jinja2 templating and accepts configuration via YAML files, making it a natural fit for generating Zope configuration files.

The cookiecutter-zope-instance template wraps cookiecutter with the specific knowledge needed to produce correct zope.conf, zope.ini, site.zcml, and related files.

Differences from the old recipe

Variable names

Variable names have been redesigned to use a consistent namespace convention. As the Zen of Python says: “Namespaces are one honking great idea – let’s do more of those!”

Variables are grouped by prefix:

  • db_* – Database settings

  • db_relstorage_* – RelStorage-specific settings

  • db_zeo_* – ZEO-specific settings

  • db_pgjsonb_* – PGJsonb-specific settings

  • cors_* – CORS settings

  • zcml_* – ZCML inclusion settings

  • wsgi_* – WSGI server settings

Sentry integration

The old recipe included built-in Sentry configuration. This has been removed in favor of using collective.sentry, which provides a much better integration as a standalone package.

The ctl.py script

The old recipe generated a control script. For modern workflows, consider using mxmake, which already has built-in support for cookiecutter-zope-instance.

Contributors

The idea and initial implementation came from Jens Klein (Klein & Partner KG of BlueDynamics Alliance). The project was then donated to the Plone Foundation and is maintained by the Plone community.

See the contributors graph for all contributors.