Not Logged In

plone.recipe.zope2instance 4.2.13

Introduction

This recipe creates and configures a Zope 2 instance in parts. It also
installs a control script, which is like zopectl, in the bin/ directory.
The name of the control script is the the name of the part in buildout.
By default various runtime and log information will be stored inside the var/
directory.

Note: This recipe is not intended to setup a Zope 2 WSGI based instance and
will not work for this use-case. There’s no special recipe required to setup
WSGI any longer and you can use simple template recipes instead.

This release is targeted at Zope 2.12+ and Python 2.6. If you are using
this recipe with earlier versions of Zope or Python, you should use one
of the releases from the 3.x series.

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.distributionmy.distribution-meta.

http-address

Give a port for the HTTP server. Defaults to 8080. Set to an empty
string to disable the HTTP server. You may want to do this when
running Zope under an external server such as a WSGI deployment.

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.

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

Specify the number of threads that Zope’s ZServer web server will use to
service requests. The recipes default is 2.

environment-vars

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

Theme 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:

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).

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.

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.

read-only

Set zeo client as read only

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’.

The filename for the Z2 access log. Defaults to var/log/${partname}-Z2.log.

z2-log-level

Set the log level for the access log. Level may be any of CRITICAL, ERROR,
WARN, INFO, DEBUG, or ALL. Defaults to WARN.

access-log-max-size

Maximum size of access log file. Enables log rotation.

access-log-old-files

Number of previous log files to retain when log rotation is enabled.
Defaults to 1.

access-log-custom

Like event-log-custom, a custom section for the access logger, to be able
to use another event logger than logfile.

Load non-setuptools compatible Python libraries

products

A list of paths where Zope 2 products are installed. The first path takes
precedence in case the same product is found in more than one directory.
Zope 2 products are deprecated and won’t work any longer in a future version
of Zope/Plone.

extra-paths

A list of paths where additional Python packages are installed. The paths
are searched in the given order after all egg and products paths.

Advanced ZCML options

site-zcml

If you want a custom site.zcml file, put its content here. If this option
is used the zcml and zcml-additional options are ignored.

zcml-additional

Extra ZCML statements that should be included in the generated site.zcml
file.

Advanced ZEO options

zeo-client-cache-size

Set the size of the ZEO client cache. Defaults to ‘30MB’. The ZEO cache is
a disk based cache shared between application threads. It’s stored inside
the directory designated by the TMP environment variable.

zeo-client-client

Set the persistent cache name that is used to construct the cache
filenames. This enabled the ZEO cache to be persisted. Persistent cache
files are disabled by default.

zeo-client-blob-cache-size

Set the maximum size of the ZEO blob cache, in bytes. If not set, then
the cache size isn’t checked and the blob directory will grow without bound.

zeo-client-blob-cache-size-check

Set the ZEO check size as percent of zeo-client-blob-cache-size (for
example, 10 for 10%). The ZEO cache size will be checked when this many
bytes have been loaded into the cache. Defaults to 10% of the blob cache
size. This option is ignored if shared-blob is enabled.

zeo-client-drop-cache-rather-verify

Indicates that the cache should be dropped rather than verified when
the verification optimization is not available (e.g. when the ZEO server
restarted). Defaults to ‘False’.

zeo-storage

Set the storage number of the ZEO storage. Defaults to ‘1’.

zeo-var

Used in the ZEO storage snippets to configure the ZEO var folder.
Defaults to $INSTANCE_HOME/var.

Advanced options

before-storage

Wraps the base storage in a “before storage” which sets it in
read-only mode from the time given (or “now” for the current time).

This option is normally used together with demo-storage for a
normally running site in order for changes to be made to the
database.

client-home

Sets the clienthome for the generated instance.
Defaults to ${buildout:directory}/var/<name of the section>.

default-zpublisher-encoding

This controls what character set is used to encode unicode data that reaches
ZPublisher without any other specified encoding. This defaults to ‘utf-8’.
Plone requires this to be set to utf-8.

demo-storage

If ‘on’ it enables the demo storage. By default, this is a
memory-based storage option; changes are not persisted (see the
demo-file-storage option to use a persistent storage for changes
made during the demonstration).

To use with a base storage option configured with a blob-storage,
you must set a demo-blob-storage.

demo-file-storage

If provided, the filename where the ZODB data file for changes
committed during a demonstration will be stored.

demo-blob-storage

If provided, the name of the directory where demonstration ZODB blob
data will be stored.

This storage may be connected to a demonstration file storage, or
used with the default memory-based demo storage (in this case you
might want to use a temporary directory).

effective-user

The name of the effective user for the Zope process. Defaults to not setting
an effective user.

enable-product-installation

Enable the persistent product registry by setting this to on. By default
the registry is turned off. Enabling the registry is deprecated.

ftp-address

Give a port for the FTP server. This enables the FTP server.

http-force-connection-close

Set to on to enforce Zope to set Connection: close header.
This is useful if for example a 304 leaves the connection open with
Varnish in front and Varnish tries to reuse the connection.

http-fast-listen

Set to off to defer opening of the HTTP socket until the end of the Zope
startup phase. Defaults to on.

icp-address

Give a port for the ICP server. This enables the ICP server.

import-directory

Used to configure the import directory for instance.
Defaults to <client-home>/import.

port-base

Offset applied to the port numbers used for ZServer configurations. For
example, if the http-server port is 8080 and the port-base is 1000, the HTTP
server will listen on port 9080. This makes it easy to change the complete
set of ports used by a Zope server process. Zope defaults to 0.

python-check-interval

An integer telling the Python interpreter to check for asynchronous events
every number of instructions. This affects how often thread switches occur.
Defaults to 1000.

relative-paths

Set this to true to make the generated scripts use relative
paths. You can also enable this in the [buildout] section.

scripts

Add this parameter with no arguments to suppress script generation.
Otherwise (i.e. without this parameter), scripts for packages added
to the eggs parameter will be generated. You may also configure
per package. E.g.:

Used to configure the base directory for all things going into var.
Defaults to ${buildout:directory}/var.

webdav-address

Give a port for the WebDAV server. This enables the WebDAV server

webdav-force-connection-close

Valid options are off and on. Defaults to off

zlib-storage

Adds support for file compression on a file storage database. The
option accepts the values ‘active’ (compress new records) or
‘passive’ (do not compress new records). Both options support
already compressed records.

You can use the ‘passive’ setting while you prepare a number of
connected clients for compressed records.

zodb-cache-size-bytes

Set the ZODB cache sizes in bytes. This feature is still experimental.

zodb-temporary-storage

If given Zope’s default temporary storage definition will be replaced by
the lines of this parameter.

zope-conf

A relative or absolute path to a zope.conf file. If this is given, many of
the options in the recipe will be ignored.

zope-conf-additional

Give additional lines to zope.conf. Make sure you indent any lines after
the one with the parameter.

Example:

zope-conf-additional =
locale fr_FR
http-realm Slipknot

zopectl-umask

Manually set the umask for the zopectl process

Example:

zopectl-umask = 002

Additional Control Script debug and run Commands

The extended Zope 2 control script installed by this recipe, usually
bininstance by convention, offers a debug command and another
run command. The debug command starts an interactive Python
prompt with the Zope 2 application available via the app name.
Similarly, the run command accepts a Python script as an argument
that will be run under the same conditions.

These commands have also been extended to set up a more complete
environment. Specifically, these commands set up a REQUEST, log in
the AccessControl.SpecialUsers.system user, and may traverse to an
object, such as a CMF portal. This environment set up is controlled
with following options:

-R/--no-request -- do not set up a REQUEST.
-L/--no-login -- do not login the system user.
-O/--object-path <path> -- Traverse to <path> from the app
and make available as `obj`.

Note that these options must come before the script name,
e.g. bin/instance -RLOPlone/front-page debug

Additional control script commands

Third-party distributions may add additional commands to the control script by
installing a ‘plone.recipe.zope2instance.ctl’ entry point. For example,
an egg called MyDist could include a module called mymodule with the
following custom command:

def foo(self, *args)
"""Help message here"""
print 'foo'

It would then install the foo method as a command for the control script using
the following entry point configuration in setup.py:

This would allow invoking the foo method by running bin/instance foo
(assuming the instance control script was installed by a buildout part
called instance.) The entry point is invoked with the following
parameters:

Reporting bugs or asking questions

Changelog

4.2.13 (2013-07-28)

adding support for zopectl umask
[hman]

4.2.12 (2013-06-04)

be able to set zeo client as read only from buildout configuration
[vangheem]

4.2.11 (2013-05-23)

When creating the blobstorage dir, make it only readable for the
current user, otherwise you get a ZODB warning on startup. This
uses code from the ZODB, which does the same when Zope starts up and
the blobstorage directory does not exist yet.
[maurits]

4.2.6 (2012-12-09)

Make the zope.conf http-server optional by setting http-address to
an empty string. Useful for configurations used under an external
server such as a WSGI deployment.
[rossp]

4.2.5 (2012-09-20)

Added event and access log rotation capability.
[sureshvv]

4.2.4 (2012-08-29)

Expose ‘drop-cache-rather-verify’ ZEO client option which indicates that
the cache should be dropped rather than verified when the verification
optimization is not available (e.g. when the ZEO server restarted).
[runyaga]

Strip all empty lines out of zeo.conf to provide more compact view.
[runyaga]

Support all RelStorage options, even future options. Used a simple pattern
to recognize where options should be placed: any option name containing a
dash is a generic option; the rest (except “name”) are database-specific.
[hathawsh]

4.1.9 - 2011-08-11

No longer rely on softwarehome in startup script.
[hannosch]

4.1.8 - 2011-07-17

Add preliminary support for Zope 4.0, by re-using the skeleton for 2.13.
[hannosch]

Added zeo-client-blob-cache-size and zeo-client-blob-cache-size-check
options to control maximum size of blob cache, and when to check the size,
when using ClientStorage without shared blobs.
[davidjb]

If a resource directory is specified using resources, create it if it does
not yet exist.
[davisagli]

Support the new create-schema option introduced in RelStorage 1.5.0b2.
[mj]

4.1.7 - 2011-06-07

Renamed the optional 998-resources.zcml (introduced in 4.1.6) to
998-resources-configure.zcml, otherwise it does not get loaded
in the standard site.zcml.
[maurits]

4.1.4 - 2011-01-01

4.1.3 - 2010-12-20

Added option http-force-connection-close which was only present in comment.
[tesdal]

4.1.2 - 2010-12-05

Fixed error introduced in 4.1.1.
[hannosch]

4.1.1 - 2010-12-05

Disambiguate the blob-storage option if shared-blob isn’t used. In this
case we use var/blobcache as a default location, so we don’t accidentally
overwrite the real blob data with a blob zeocache. Refs
https://bugs.launchpad.net/bugs/645904.
[hannosch]

4.1 - 2010-12-04

Give the readme an overhaul, group options into sections and mention the
most commonly used ones at the top.
[hannosch]

4.0.4 - 2010-09-09

Exit with the return code of the executed do_* method. This closes #10906
(clicking “Restart” in ZMI control panel caused shutdown).
[kleist]

Implemented the “restart” command for “bin/instance.exe”.
[kleist]

4.0.3 - 2010-08-20

Setuptools / Subversion ignores empty directories and doesn’t include them
into the source distribution. Added readme files to the bin and var
directories inside the skeleton. This lets persistent ZEO caches work again,
which want to put their files into the var directory.
[hannosch]

4.0.2 - 2010-08-04

Rewritten major parts of commands specific for the Windows Service, inspired
by “collective.buildout.cluster.base.ClusterBase” as used by the Windows
installer. Closes http://dev.plone.org/plone/ticket/10860.
[kleist]

4.0.1 - 2010-07-30

Use pid file to check for running application, instead of service status.
[sidnei]

If we are used in an environment with Zope2 as an egg, we make sure to
install the mkzopeinstance and runzope scripts we depend on ourselves.
This is done even if they already exist, since the eggs may have changed.
[hannosch, davisagli]

Added Zope2 egg to the list of dependencies of this recipe. This can cause
trouble for Zope versions before Zope 2.12 or Plone before 4.0.
[hannosch]

Added the cache-prefix option for RelStorage.

3.6 (2009-10-11)

Expanded the RelStorage options, including keep-history and replica-conf.
[hathawsh]

3.5 (2009-09-05)

Added support for relative-paths in the script generation.
[jvloothuis]

When zope-conf is set the config file will be directly loaded from that
location (it previously created a stub zope.conf which included it).
[jvloothuis]

Added an option to avoid using the normal shell scripts for starting Zope.
This makes it possible to avoid the hard-coded paths in these scripts.
[jvloothuis]

3.3 - 2009-07-07

Reinstall scripts on update which appears to be good recipe practice.
[stefan]

3.2 - 2009-04-02

Add a new zcml-additional option. This is useful for environments where
non-code configuration (such as database connection details for
ore.contentmirror) are managed through zcml.
[wichert]

3.1 (2009-03-15)

The 2.9 fix for spaces caused a problem using debug (bug 337740)
due to the way do_debug passed the “-i” command line argument
to get_startup_cmd.
[smcmahon]

3.0 (2009-02-27)

The 2.9 fix for the instance run command was itself broken and
would fail on anything except Windows.
[smcmahon]

Changed the zope2-egg option to omit any kind of instance creation for
now. The mkzopeinstance script relies on being able to import Zope2, which
is not available when buildout runs.
[hannosch]

2.9 (2009-02-26)

The instance run command was vulnerable to spaces in pathnames, and
needed some extra quoting for win32.
[smcmahon]

Check for existence of windows scripts before patching them. Some
Linux distributions of Zope2 don’t have these files.
[smcmahon]

Delegate commands to win32serviceutil.HandleCommand() on win32,
instead of starting the interpreter through os.system(). Should
shave off a couple seconds from overall time taken to process those
commands.
[sidnei]

Compute serviceClassString ourselves, since we are calling this
as a module and not directly as __main__, otherwise the service
won’t be installed correctly.
[sidnei]

2.8 (2008-12-05)

Add more tests for ZEO client with blob and demo storages.
Still no test on ‘shared-blob-dir’ option.
[encolpe]

Always use ‘r’-style strings for passing script and configuration
filenames (eg: on ‘instance run <script>’).
[sidnei]

Add a demo-storage option and tests.
[encolpe]

Add a first test for blob-storage.
[encolpe]

2.7 (2008-11-18)

Added a zope2-egg option and an accompanying simple startup script for
use with an eggified Zope2.
[hannosch]

Do not fail with a Zope2 egg checkout.
[hannosch]

Normalize first argument to os.spawnl. It can get really upset
otherwise (dll import failure on a relocatable python install).
[sidnei]

Use same quoting as on ‘do_foreground’ for servicescript
usage. Fixes problems with installing the buildout-based Plone
installer for Windows on a path with spaces.
[sidnei]

Ensure that do_foreground leaves self.options.program arguments as it
found them. This makes it possible to use ‘fg’ and ‘debug’ more than
once within the same control session.
[klm]

2.6 (2008-10-22)

Normalize, absolutize and lowercase-ize (is that a word?) paths
before comparing, to avoid problems with relative filenames and
different drive letter case on Windows.
[sidnei]

2.5 (2008-09-22)

Add support for zodb-cache-size-bytes from ZODB 3.9 and later.
[wichert]

2.4 (2008-07-15)

Introduced zope.conf variables “INSTANCEHOME” and “CLIENTHOME”.
Its very very helpful in cluster setups with zope-conf-additional
sections (buildout lacks to reference the current section).
[jensens]

Made test command compatible with zope.testing 3.6.
[hannosch]

2.3.1 (2008-06-10)

No code changes. Released to fix the 2.3 release which put .egg files in
the wild.
[hannosch]

2.3 (2008-06-06)

Need to actually pass in deprecation-warnings, otherwise we get a
KeyError.
[sidnei]

Fix another place where the directory name needed to be escaped to
avoid problems with spaces.
[sidnei]

Don’t try to delete location if it does not exist.
[sidnei]

2.2 (2008-06-06)

Added deprecation-warnings option that allows turning the option
to disable deprecation warnings on or off. You can provide the value
error to it, and every deprecation warning will be turned into an
exception.
[sidnei]

Fix copy and paste error that caused a failure on changing
runzope.bat to call servicewrapper.py.
[sidnei]

Escape ‘executable’ argument before passing it to os.spawnl, in
order to make it work on Windows when the executable name has spaces
on it.
[sidnei]

2.1 (2008-06-05)

Fixed a test problem on Windows, where explicit closing of files is required.
[hannosch]

Call servicewrapper.py from runzope.bat instead of setting
PYTHONPATH and calling Zope2/Startup/run.py. That way we set
sys.path from inside Python code and avoid exceeding the maximum
environment variable limit.
[sidnei]

Allow to use an alternative temporary storage, by specifying the new
zodb-temporary-storage option.
[jensens]

Added environment-vars option to set environment variables. Changed
the zope-conf-additional example code to something that isn’t covered by
the recipe.
[claytron]

2.0 (2008-05-29)

Do not use system but exec when starting Zope. This makes it possible for
process management tools to properly manage Zope processes.
[wichert]

1.9 (2008-04-15)

1.8 (2008-04-05)

Fixed a Win32 problem in which the presence of Python string escapes in the
path to zope.conf (e.g., d:botestpartsinstanceetczope.conf would escape
the b). This showed up when using the ‘run’, ‘debug’ or ‘adduser’ commands.
This fixes #211416.
[smcmahon]

Added console command to the instance script, which is equivalent to fg but
does not implicitly turn on debug mode but respects the zope.conf setting.
[hannosch]

1.7 (2008-03-31)

Added new client-home option and let it default to a subfolder of the
buildout-wide var folder with a subfolder of the name of the section.
[hannosch]

Added limited support for running tests under Zope <= 2.8.
[hannosch]

1.6 (2008-03-27)

Fixed runzope script generation for Zope 2.8.
[hannosch]

Cleaned up “./bin/instance test” option handling.
[stefan]

Removed generator expressions as these aren’t supported in < py2.4, which is
used by zope 2.7/8.
[duffyd]

1.5 (2008-02-29)

Added access-log-custom option to be able to use another event logger
than the file one for the access logger.
[tarek]

Fix instance generation to work on Windows with blanks in the path name.
This closes #188023.
[hannosch, gotti]

Added rel-storage option to be able to wire Zope to RelStorage
(postgresql/oracle) instead of a FileStorage database.
[tarek]

1.3

For each entry in recipe-specified ‘extra-paths’ line, add a ‘path’ line
to the instance and Zope client zope.conf files.
[klm]

1.2

Added the boolean shared-blob option, defaulting to no. If all of
zeo-client, blob-storage and shared-blob options are set,
the instance will assume the blob directory set by blob-storage is shared
with the server instead of streaming ‘blob’ files through the ZEO connection.
[rochael]

Changed ctl.do_foreground() (which is invoked by the fg command
line argument) start Zope in debug mode to emulate the behavior of
zopectl fg. This required a little special WIN32 code to make
sure it would work in both *nix and Windows.
[smcmahon]

Added var option, which is used to configure the base directory for all
the things going into var.
[hannosch]

Added zeo-var option, which is used in the zeo storage snippets to
configure the zeo var folder.
[hannosch]

Avoid doubled entries to eggs specified in the buildout in ‘sys.path’:
the working set (‘ws’) gets passed again when installing the script
(‘bin/instance’), but it is not also added to ‘extra_paths’.
[witsch]

Made the config snippet prettier while still getting the resulting
indentation right.
[witsch]

0.9

Added support for zodb 3.8’s “<blobstorage>” directive.
[witsch]

Added a script name arg before callint zope.testing.testrunner.run.
zope.testing.testrunner:1772, get_options removes the first arg from
the list of arguments expecting a script name there. Was causing
“bin/instance test” to behave improperly.
[rossp]

0.8

Use bin if present falling back to utilities. This makes it possible to use
a Zope version installed from a tarball and not compiled inplace.
[rossp]