zope-common for Ubuntu/Debian
-----------------------------

The document describes how to handle Zope installations, managing Zope
instances and how the packaging of Zope versions and products work on Debian
systems.

Zope versions in Debian
-----------------------

The packaging of Zope versions and products allows parallel installations 
and running of different Zope versions on the same system.

Hints for a Zope user
---------------------

Installing a Zope package doesn't start you a Zope process, it just sits on
your disk. To actually do something you have to create a Zope instance and
start this instance. You can do this by hand, but the packaging provides you
with some support to setup pre-configured Zope instances like a sandbox
instances (play around, test), or preconfigured instances like plone-site or
cps-site.

Each Zope version is installed in

	/usr/lib/zope<version>

Instances are created in

	/var/lib/zope<version>/instance/<instance name>

If you want to add them somewhere else, add a symlink in the above directory to
the instance home, so the packaging tools can find them.

Zope products are installed in:

	/usr/share/zope/Products

These won't show up in Zope instances by default. Make them visible to the
instances by the packaging tools (the dzhandle binary) or use your own tools
and scripts.

You don't have to use the packaging tools. Just create the instances manually
and the packaging won't touch them (If it's touched anyway, please report a
bug).


Handling of Zope Products
-------------------------

Products are typically packaged as zope-<product> (where <product> is all
lowercase). Installing a product makes the product available on your system,
but not in an Zope instance, except the instance is configured to have all
products installed by default.

To add the MyProduct product to the Zope 2.10 instance `myinstance', you have
to run the following command:

    # dzhandle -z 2.10 add-product myinstance MyProduct

The local system administrator can install additional Zope products in the
directory /usr/local/share/zope/Products, and they will be available to
dzhandle in the very same way the Debian products are.

It is possible to manage multiple versions of the same Products using a suffix
in the form ProductName:suffix for the product directory. For example, the
products MyProduct:stable and MyProduct:devel can be added to two different
zope instances running the following commands:

    # dzhandle -z 2.10 add-product instance1 MyProduct:stable
    # dzhandle -z 2.10 add-product instance1 MyProduct:devel


Handling of Zope Instances
--------------------------

You (or a package) can create a zope instance using:

  dzhandle -z 2.10 make-instance <instance> --addon-mode [manual|all]

The script uses the `mkzopeinstance.py' script to create the instance and
creates a file /etc/zope2.10/<instance>/debian_policy, which has information
about how the instance should be handled.

Addon-Mode describes, if all addons should be installed in the Products
directory of the instance, or if you want to handle these yourself either
copying products to the location by hand or using the dzhandle tool.

Addon-Technique describes how products and extensions, which are installed as
.deb packages, are shown to the instance.

- 'linked' makes everything visible to the instance, by using a symlink
  to the packaged addon. Doesn't handle different python versions well.

- 'tree-linked' copies the directory tree of the addon and symlinks every
  file. Works better when you do have different zope versions requiring
  different python versions (that's what the zope2.10-sandbox package uses).

- 'copied' copies the product to the instance, but doesn't update the copy
  on package upgrades.

Restart-Policy describes how instances are restarted during configuration.

An instance, which should be restarted on system start, has to be mentioned in
/etc/default/zope<version>.


Product Installation in Instances
---------------------------------

A product is automatically installed in an instance, if the Addon-Mode of the
instance is set to 'all', and the instance doesn't have the addon exclude in
it's instance policy file (Excluded-Addons).

The installation will fail, if there's already a product in an instance in
Addon-Mode 'all' and the product isn't in the list of excluded addons.


Product Upgrades in Instances
-----------------------------

The installation of a packaged product in an instance is upgraded, if the
Addon-Technique for the instance is 'linked' or 'tree-linked'. Manually
installed products and 'copied' products are not updated.


Product Removals in Instances
-----------------------------

When a packaged product is removed, it is tried to remove all product
installations in instances, if the Addon-Technique of the instance is 'linked'
or 'tree-linked'. The removal will fail, if the instance is in Addon-Mode
'manual'.

Manually installed products and 'copied' products are not removed from the
instances.


Local third-party zope products
-------------------------------

The system administrator can install third-party custom products in
/usr/local/share/zope/Products, and they will be read before the
system-installed ones.


Using dzhandle with non-root users
----------------------------------

It is possible to use dzhandle as non-root users to create and manage zope and
zeo instances; these personal instances won't be started at system start-up by
the init script, and the installed products won't be added, removed or upgraded
when installing, removing or upgrading debian packages.

The default paths for personal zope and zeo instances are:

  $HOME/zope/instance
  $HOME/zope/zeo

These paths can be overridden creating a file ~/.dzhandle.conf within the home
directory of the user with the following syntax:

  # this is a comment
  instances: /home/user1/zope/instances
  zeoinstances: /home/user1/zope/zeo
  products: /home/user1/zope/products

dzhandle detects when it is used with a non-root user and reads the
configuration file in the home directory (or uses the default). This is an
example usage of this feature:

  $ whoami
  user1
  $ dzhandle -z2.10 make-instance testing -m manual -u admin:pwd
  $ dzhandle -z2.10 add-product testing CMFPlone
  $ dzhandle -z2.10 zopectl testing start
  $ dzhandle -z2.10 zopectl testing stop
  $ dzhandle -z2.10 purge-instance testing
  
This instance will be created in:

  /home/user1/zope-instances/zope2.10/testing

Users can enable dzhandle usage for custom products putting them under
~/zope/products (or where specified by the configuration file) and following
the instructions from the "Local third-party zope products" paragraph.


Plone packaging
---------------

Plone is available in Debian as a single binary package (zope-plone3) which
provides all the required zope products. The packaging allows one to install
multiple Plone versions on the same system: the products use the major version
as suffix to allow parallel install. For example, to add the Plone 3.0 products
to the instance plone_instance, you can run:

  $ dzhandle -z2.10 add-product plone_instance CMFPlone:3.0

A pre-packaged Zope instance ready to run a Plone site is available installing
the plone3-site package.
