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 Instances are created in /var/lib/zope/instance/ 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- (where 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 --addon-mode [manual|all] The script uses the `mkzopeinstance.py' script to create the instance and creates a file /etc/zope2.10//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. 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.