Introduction

.. image:: http://img.shields.io/pypi/v/plone.recipe.zope2instance.svg :target: https://pypi.org/project/plone.recipe.zope2instance

.. image:: http://img.shields.io/travis/plone/plone.recipe.zope2instance.svg :target: https://travis-ci.org/plone/plone.recipe.zope2instance

.. image:: https://github.com/plone/plone.recipe.zope2instance/workflows/Test/badge.svg?branch=master :target: https://github.com/plone/plone.recipe.zope2instance/actions?query=workflow%3ATest+branch%3Amaster

This recipe creates and configures a Zope instance in parts. (Despite its name it nowadays only works for Zope 4+.) It also installs a control script, which is like zopectl, in the bin/ directory. The name of the control script is the name of the part in buildout. By default various runtime and log information will be stored inside the var/ directory.

You can use it with a part like this::

[instance] recipe = plone.recipe.zope2instance user = admin:admin http-address = 8080 eggs = my.distribution zcml = my.distribution

.. contents:: Contents

Options

Common options

eggs The list of distributions you want to make available to the instance.

zcml Install ZCML slugs for the distributions listed, separated by whitespace. You can specify the type of slug by appending '-' and the type of slug you want to create. Some examples: my.distribution my.distribution-meta.

http-address Set the address of the HTTP server. Can be either a port or a socket address. Defaults to 0.0.0.0:8080.

ip-address The default IP address on which Zope's various server protocol implementations will listen for requests. If this is unset, Zope will listen on all IP addresses supported by the machine. This directive can be overridden on a per-server basis in the servers section. Defaults to not setting an ip-address. Used for ZServer only, not WSGI.

threads Specify the number of worker threads used to service requests. The default is 4 for WSGI (since this is the waitress default) and 2 for ZServer.

zodb-cache-size Set the ZODB cache size, i.e. the number of objects which the ZODB cache will try to hold. Defaults to 30000.

zserver-threads Deprecated, use threads instead. Specify the number of threads that Zope's ZServer web server will use to service requests. The recipes default is 2. Used for ZServer only, not WSGI.

environment-vars Define arbitrary key-value pairs for use as environment variables during Zope's run cycle. Example::

environment-vars =
  TZ US/Eastern
  zope_i18n_allowed_languages en
  zope_i18n_compile_mo_files true

initialization Specify some Python initialization code to include within the generated sitecustomize.py script (Buildout >= 1.5) or within the instance script (Buildout < 1.5). This is very limited. In particular, be aware that leading whitespace is stripped from the code given. added in version 4.2.14

wsgi By default this recipe creates a Python script that uses waitress as a WSGI server. When running Python 2 you can disable WSGI and use ZServer by setting wsgi = off and including ZServer in the eggs specification list. Example::

 wsgi = off
 eggs =
   ...
   ZServer

You can use other PasteDeploy-compatible WSGI servers by passing a path to a WSGI configuration file here and including the WSGI server's egg in the eggs specification. Example::

 wsgi = ${buildout:directory}/etc/gunicorn.ini
 eggs =
   ...
   gunicorn

The WSGI configuration file will not be created for you in this case, unlike the built-in waitress support. You have to provide it yourself.

max-request-body-size Specify the maximum request body size in bytes The default is 1073741824 (since this is the waitress default)

Theme resources

Please refer to <https://pypi.org/project/plone.resource>_ for more details and setup instructions.

resources Specify a central resource directory. Example::

resources = ${buildout:directory}/resources

Locales

locales Specify a locales directory. Example::

locales = ${buildout:directory}/locales

This registers a locales directory with extra or different translations. If you want to override a few translations from the plone domain in the English language, you can add a en/LC_MESSAGES/plone.po file in this directory, with standard headers at the top, followed by something like this::

#. Default: "You are here:" msgid "you_are_here" msgstr "You are very welcome here:"

Translations for other message ids are not affected and will continue to work.

Development options

verbose-security Set to on to turn on verbose security (and switch to the Python security implementation). Defaults to off (and the C security implementation).

debug-exceptions WSGI only: set to on to disable exception views including standard_error_message. Exceptions other than Unauthorized or ConflictError can then travel up into the WSGI stack. Use this option if you want more convenient error debugging offered by WSGI middleware such as the werkzeug debugger <https://werkzeug.palletsprojects.com/en/0.15.x/debug/>. See the Zope WSGI documentation <https://zope.readthedocs.io/en/latest/wsgi.html> for examples.

profile Set to on enables repoze.profile <https://github.com/repoze/repoze.profile>_. Defaults to off, If switched on there are further options prefixed with profile_ to configure it as below. You will need to add the repoze.profile package, either by adding it to your eggs section directly or by using the extra plone.recipe.zope2instance[profile].

profile_log_filename Filename of the raw profile data. Default to profile-SECTIONNAME.raw. This file contains the raw profile data for further analysis.

profile_cachegrind_filename If the package pyprof2calltree is installed, another file is written. It is meant for consumption with any cachegrind compatible application. Defaults to cachegrind.out.SECTIONNAME.

profile_discard_first_request Defaults to true. See repoze.profile docs <https://repozeprofile.readthedocs.io/en/latest/#configuration-via-python>_ for details.

profile_path Defaults to /__profile__. The path for through the web access to the last profiled request.

profile_flush_at_shutdown Defaults to true. See repoze.profile docs <https://repozeprofile.readthedocs.io/en/latest/#configuration-via-python>_ for details.

profile_unwind Defaults to false. See repoze.profile docs <https://repozeprofile.readthedocs.io/en/latest/#configuration-via-python>_ for details.

Direct storage

If you have only one application process, it can open the database files directly without running a database server process.

file-storage The filename where the ZODB data file will be stored. Defaults to ${buildout:directory}/var/filestorage/Data.fs.

blob-storage The name of the directory where the ZODB blob data will be stored, defaults to ${buildout:directory}/var/blobstorage.

Basic ZEO storage

If you want multiple application processes you need to run a separate database server process and connect to it, either via ZEO or RelStorage.

zeo-address Set the address of the ZEO server. Defaults to 8100. You can set more than one address (white space delimited). Alternative addresses will be used if the primary address is down.

zeo-client Set to 'on' to make this instance a ZEO client. In this case, setting the zeo-address option is required, and the file-storage option has no effect. To set up a ZEO server, you can use the plone.recipe.zeoserver recipe. Defaults to 'off'.

blob-storage The location of the blob zeocache, defaults to var/blobcache. If shared-blob is on it defaults to ${buildout:directory}/var/blobstorage.

shared-blob Defaults to off. Set this to on if the ZEO server and the instance have access to the same directory. Either by being on the same physical machine or by virtue of a network file system like NFS. Make sure this instances blob-storage is set to the same directory used for the ZEO servers blob-storage. In this case the instance will not stream the blob file through the ZEO connection, but just send the information of the file location to the ZEO server, resulting in faster execution and less memory overhead.

zeo-client-read-only-fallback A flag indicating whether a read-only remote storage should be acceptable as a fallback when no writable storages are available. Defaults to false.

read-only Set zeo client as read only added in version 4.2.12

ZEO authentication

You need to activate ZEO auth on the server side as well, for this to work. Without this anyone that can connect to the database servers socket can read and write arbitrary data.

zeo-username Enable ZEO authentication and use the given username when accessing the ZEO server. It is obligatory to also specify a zeo-password.

zeo-password Password to use when connecting to a ZEO server with authentication enabled.

zeo-realm Authentication realm to use when authentication with a ZEO server. Defaults to 'ZEO'.

RelStorage

Please refer to <https://pypi.org/project/RelStorage>_ for more details and setup instructions.

rel-storage Allows to set a RelStorage instead of a FileStorage.

Contains settings separated by newlines, with these values:

• type: any database type supported (postgresql, oracle, mysql)
• RelStorage specific keys, like cache-servers and poll-interval
• all other keys are passed on to the database-specific RelStorage adapter.

Example::

rel-storage =
  type oracle
  dsn (DESCRIPTION=(ADDRESS=(HOST=s01))(CONNECT_DATA=(SERVICE_NAME=d01)))