Installing Add-ons
Introduction
With Plone 3.0, the Plone community adopted new standards for packaging, distributing and installing add-ons for Plone. Instead of shipping them as folders that get copied into a "magic" Products folder in your Zope instance, add-ons (and the packages that make up Plone itself!) are now shipped as Python eggs, which are installed into the instance of Python that is powering your Zope instance using the Buildout installation system.
These new installation methods can make it far easier and simpler to install add-ons in a consistent, repeatable way.
The purpose of this document is to provide a single point of documentation that covers the common add-on installation techniques for typical real-world deployment scenarios.
Always backup your Plone installation before changing the configuration of a production installation.
Always read your add-on's documentation, usually in a README.txt or similar file. Your add-on may have specific installation instructions, which you must obviously follow.
Installing Add-ons Using Buildout
Buildout is a powerful, easy-to-use utility for creating scripted, repeatable installations of Plone, Zope and Python. As of Plone 3.2, Plone's Unified Installer began using Buildout, and so Buildout is now the "mainstream best practice" way to install Plone add-ons.
Buildout can be used to install both Zope 2-style Products and egg-based add-ons. If Buildout is available for your installation, it is the recommended way to manage add-on installation.
How to install a new add-on will depend on whether it is packaged as an egg, or a traditional Zope 2 Product.
Installing eggs
Most modern Plone add-ons are now packaged as eggs, the Python community's standard distribution format. Egg-based packages are very simple to install with Buildout. Here's how.
Step 1: Add the egg to your buildout.cfg file
Find your "buildout.cfg" file, typically located in the "zinstance" subdirectory of your Plone installation directory. Simply list the egg in the eggs section of your buildout, and optionally a version (otherwise, you get the latest available). Buildout will automatically download and install the egg and any dependencies it specifies.
[buildout]
...
eggs =
Products.PloneFormGen
collective.recaptcha
If you want buildout to search other egg repositories, you can add a URL to find-links that contains download links for the eggs. By default, Plone searches the following repositories, in addition to PyPi, the Python community's master repository for eggs.
[buildout]
...
find-links =
http://dist.plone.org
http://download.zope.org/ppix/
http://download.zope.org/distribution/
http://effbot.org/downloads
Step 2: If your add-on is not named "Products.*", add it to the zcml section of your buildout
It is important to realize that Zope will not load configure.zcml files automatically for packages that are not in the Products.* namespace. Instead, you must explicitly reference the package. Buildout can create such a reference (known as a ZCML slug) with the zcml option under the [instance] part. Here is how to ensure that collective.recaptcha is available to Zope:
[buildout]
...
eggs =
Products.PloneFormGen
collective.recaptcha
...
[instance]
...
zcml =
collective.recaptcha
Step 3: Rerun buildout and restart your Zope instance
Now that you've reconfigured your buildout, you must rerun buildout and restart your Zope instance to download and install your new eggs.
Navigate to your zinstance directory, and type:
$ ./bin/buildout
Buildout will run, and install your new products. Then, start (or restart) Zope, typically with
$ ./bin/plonectl restart
Step 4: Install the Add-on in Your Plone Site
In each Plone site where you want to install the add-on, go to Site Setup>Add-ons and activate the add-on.
At this point, you may get an error (indicated by a red exclamation mark), which usually indicates that you missed out a dependency or that the add-on itself is broken. Make sure that you have read the relevant documentation. If this happened in an actual released version of the add-on , you may want to contact the author or post an issue in the product's bug tracker (if it has one), but please make sure that you have followed the instructions properly first.
Installing a traditional Zope 2 Product with Buildout
The easiest way to install out a traditional Zope 2 product is to extract it into the products/ folder inside the buildout. If you see documentation referring to the Products/ folder in a Zope instance, this is the same thing.
However, this approach makes it harder to redistribute your project and share it with other developers. It is often more predictable to let buildout download and install the package for you. You can do this with the [productdistros] section of buildout.cfg. For example, here is how you might install a product named ExampleProduct and a set of products named ExampleProductBundle:
[productdistros]
recipe = plone.recipe.distros
urls =
http://example.com/dist/ExampleProduct-1.0.tgz
http://example.com/dist/ExampleProductBundle-1.0.tgz
nested-packages =
ExampleProductBundle-1.0.tgz
version-suffix-packages =
Note that our fictional ExampleProductBundle is distributed as a single directory containing a number of products in sub-directories, so we list it under nested-packages.
As always, if you change buildout.cfg, you must re-run buildout:
$ ./bin/buildout
Installing Egg-based add-ons Without Buildout
Installing egg-based add-ons for Plone without Buildout is not recommended unless you are an advanced developer. It is far better to migrate your Plone installation to Buildout (or upgrade to Plone 3.2 or higher, which use Buildout). Relatively few egg-based add-ons are compatible with versions of Plone below 3.0 in any case.
Installing Zope 2-style Products Without Buildout
You can install Zope 2-style add-on Products without Buildout. Typically, you'd only do this if you are running Plone 2.x, which predates mainstream use of Buildout.
Step 1: Place the Product's Directory in Your Zope Instance's "Products" Directory
Remember to use a test instance unless you know that the Product is compatible with your Plone setup!
Generally you will download a file like SomeProduct-0.5.3.tar.gz. Extract the contents of this file. On a Unix-like system, you might say:
$ tar -zxvf SomeProduct-0.5.3.tar.gz
On a Windows system, use 7zip or another zip extraction tool. Make sure that you preserve the directory structure when extracting; some tools, such as WinZip, have a habit of flatting the directory structure of the compressed archive, thus giving you all the files in a single directory. In this case, you may need to select an option to preserve the structure when you extract the archive.
You should end up with a directory structure like either:
SomeProduct-0.5.3/
SomeProduct/
__init__.py
...
or:
SomeProduct/
__init__.py
...
The SomeProduct/ directory is the "Product directory", recognizable by the __init__.py file. Sometimes there might be several Products packaged into a single archive. Place the Product's directory (or directories) in your Zope instance's Products/ directory. In Windows, the instance directory is often named Data. Note that you do not want to use the lib/python/Products directory.
Make sure the folder has the same owner and permissons as the other Products in your Zope instance, and is readable by the user that your Zope server runs as. For example, the Unified Installer build of Plone runs as a user named "plone" and all Plone Products are owned by this user. On *nix and Mac OS X you can move to your Products directory and execute the command
sudo chown -R plone *
to set the ownership of all files in the Products folder to user "plone".
Step 2: Restart Zope
Unless you restart Zope, it will never know that there are new Products available. When restarted, the new Products will show up in the Zope Control Panel's Products section. This means the software is now available for use in the Plone instance. (Some Products will start to take effect at this point, like DocFinderTab or anything that does monkeypatching.)
Step 3: Install the Product in Your Plone Site
In each Plone site where you want to install the Product, go Site Setup>Add/Remove Products and install the Product.
At this point, you may get an error (indicated by a red exclamation mark), which usually indicates that you missed out a dependency or that the product itself is broken. Make sure that you have read the relevant documentation. If this happened in an actual released version of the product, you may want to contact the author or post an issue in the product's bug tracker (if it has one), but please make sure that you have followed the instructions properly first.
Further information
Troubleshooting Add-on Product Installation Problems
For more advanced information on using Buildout when doing custom development work, see Managing projects with Buildout - Packages, products and eggs.
Credits
Thanks to J. Cameron Cooper for the first version of the Zope 2-style Products installation instructions. Martin Aspeli, Graham Perrin, Jon Stahl and Steve McMahon conspired on updates.
Visit our
