plone.recipe.zope2instance 1.3

ZC Buildout recipe for installing a Zope 2 instance

plone.recipe.zope2instance
==========================

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.

You can use it with a part like this::

[instance]
recipe = plone.recipe.zope2instance
zope2-location = /path/to/zope2/install
user = admin:admin
http-address = 8080
eggs = ${buildout:eggs} my.package
products = ${buildout:directory}/products
zcml = my.package

Options
-------

zope2-location
The path where Zope 2 is installed. If you are also using the
plone.recipe.zope2install recipe, and you have that configured as a part
called 'zope2' prior to the zope2instance part, you can use ${zope2:location}
for this parameter.

zope-conf
A relative or absolute path to a zope.conf file. If this is not given, a
zope.conf will be generated based on the the options below.

repozo
The path to the repozo.py backup script. A wrapper for this will be
generated in bin/repozo, which sets up the appropriate environment for
running this. Defaults to "${zope2-location}/utilities/ZODBTools/repozo.py".
Set this to an empty value if you do not want this script to be generated.

The following options all affect the generated zope.conf:

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.

zcml
Install ZCML slugs for the packages listed, separated by whitespace. You
can specify the type of slug by appending '-' and the type of slug you want
to create. The valid types are configure, overrides and meta. Some
examples: my.package-overrides my.package-meta

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.

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

debug-mode
Set to 'on' to turn on debug mode in Zope. Defaults to 'off'.

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

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

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.

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.

http-address
Give a port for the HTTP server. Defaults to 8080.

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

event-log
The filename of the event log. Defaults to var/log/${partname}.log

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

z2-log
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.

file-storage
The filename where the ZODB data file will be stored.
Defaults to var/filestorage/Data.fs.

blob-storage
The name of the directory where the ZODB blob data will be stored.

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.zope2zeoserver recipe.
Defaults to 'off'.

shared-blob
If 'zeo-client' is set to 'on' and 'blob-storage' is set to a directory that
is shared between this instance and the ZEO server (as configured by the
'blob-dir' setting on zeo.conf, then setting 'shared-blob' to 'on' causes
this instance not to stream the blob file through the ZEO connection, but
just to send the information of the file location to the ZEO server.

zeo-address
Set the address of the ZEO server. Defaults to 8100.

zeo-client-name
Set the name of the ZEO client. Defaults to the name of the part. If a false
value is provided no zeo-client-name will be set.

zeo-client-cache-size
Set the size of the ZEO client cache. Defaults to '30MB'.

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.

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

zserver-threads
Specify the number of threads that Zope's ZServer web server will use to
service requests. You shouldn't change this unless you know what you are
doing. Zope's default is 4.

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

Reporting bugs or asking questions
----------------------------------

We have a shared bugtracker and help desk on Launchpad:
https://bugs.launchpad.net/collective.buildout/

Change History
==============

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]

- Merged rochael-blobsupport branch. Added support for ZODB 3.8 blob storage
configuration for ZEO clients. This references
https://bugs.launchpad.net/collective.buildout/+bug/179113.
[rochael, hannosch]

- Added `zeo-client-name` option. Defaults to the name of the ZEO client.
[hannosch]

1.1
---

- Small documentation update. Added link to the bugtracker.
[hannosch]

- Changed default of zope.conf option 'default-zpublisher-encoding' to 'utf-8'
instead of Zope's default value of 'iso-8859-15'.

- Have PID file's location default to '${buildout:directory}/var/${name}.pid'.
Keeping the PID file in $INSTANCE_HOME gives trouble when buildout rebuilds
the part.
[nouri, mustapha]

1.0
---

- Increased 'zodb_cache_size' default value to 5000, which is more likely a
better default these days.
[hannosch]

- Added support for 'extra-paths' as in 'zc.recipe.egg'; this is useful when
using regular python packages for which no eggs are available (yet), i.e.
with 'plone.recipe.distros'.
[witsch]

- Added zeo-storage option (merge branch ree-add-zeo-storage-option).
[ree]

- 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]

- Patching 'PYTHONPATH' in the Zope startup skripts should insert all
additional paths (to eggs) __before__ 'SOFTWARE_HOME', because otherwise
(newer) egg versions of components from the standard Zope distribution
(i.e. stuff that lives in 'lib/python') cannot be used.
[witsch]

- Changed the option to suppress deprecation warnings to "--nowarn" or
'--nowarning" to be consistent with "zopectl test".
[witsch]

- Added option "-w" to allow the test runner to suppress deprecation warnings,
so it's easier to spot failing tests...
[witsch]

- Updated import for Zope 2.7 (and below) compatibility.
[duffyd]

- Merging -r51966:52659 claytron-zopeconfoptions branch to trunk.
[claytron]

- 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]

0.7
---

- Found the problem with strange environment variables.
[hannosch]

- Fixed documentation bug, the cache size is respected by non-zeo instance as
well.
[hannosch]

0.6
---

- J1m actually read the docs ;)
[hannosch]

- Attempt to fix the sometimes insane number of tests which are found by the
test runner.
[hannosch]

0.5
---

- Added an option to set the effective-user.
[optilude]

0.4
---

- Generate a bin/repozo script to perform backups using repozo.py (and
set up the appropriate pythonpath for this to work).
[optilude]

- Document options properly, and add the ability to specify a zope.conf
file explicitly rather than having one generated from a template.
[optilude]

0.3
---

- Finally found a way to provide the Zope Windows service with the right
environment. We need a new wrapper script, which sets up the PYTHONPATH.
[hannosch]

- Make it possible to configure the name of the zopectl script using the
control-script option in the [instance] section.
[wichert]

0.2
---

- Extend support for zcml slugs to include Zope 2.9.
[dunny]

- Added support for making a ZEO-client.
[regebro]

0.1
---

- Initial implementation.
[hannosch]