Introduction

With Plone 3.0, the Plone community began adopting new standards for packaging, distributing and installing add-on Products for Plone. Instead of shipping Products as folders that get copied into a "magic" Products folder in your Zope instance, add-on Products (and the products 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, typically via buildout scripts or the EasyInstall utility.

These new installation methods can make it far easier and simpler to install add-on Products in a consistent, repeatable way. However, the Plone community is still in the midst of adopting these new techniques, which means you may find add-on Products that require different approaches to installation.

The purpose of this document is to provide a single point of documentation that covers the common add-on Product installation techniques for typical real-world deployment scenarios.

Always read your product's documentation, usually in a README.txt or similar file. Your product may have specific installation instructions, which you must obviously follow.

Installing Products Using Buildout

Buildout is a powerful, easy-to-use utility for creating scripted, repeatable installations of Plone, Zope and Python. Most advanced Plone developers currently use Buildout to create and manage Plone deployments. As of Plone 3.1, Plone's Unified Installer will begin using Buildout, and so Buildout will cross into wide use among "everyday" Plone system administrators.

Buildout can be used to install both Zope 2-style and egg-based Products. If buildout is available for your installation, it is the recommended way to manage add-on product installation.

Installing add-on Products with Buildout is documented at:

http://plone.org/documentation/tutorial/buildout/installing-a-third-party-product

Installing Zope 2-style Products from a Tarball

  $ tar -zxvf SomeProduct-0.5.3.tar.gz

  SomeProduct-0.5.3/
    SomeProduct/
      __init__.py
      ...

  SomeProduct/
    __init__.py
    ...

sudo chown -R plone *

Step 2: Restart Zope

Installing Egg-based Products Using Easy_Install

Most new Plone add-on Products are now packaged as Python eggs, which are now the standard way to package and distribute all Python software. You can easily install egg-based Products using the EasyInstall utility. 

Getting EasyInstall

EasyInstall is included with the Plone 3.0.x Windows, OS X, and Unified (Linux/BSD/Unix) installers and, so if you've installed Plone using one of these installers, you don't have to worry about this step.

If you do not already have EasyInstall on your system, please read and follow the installation instructions for EasyInstall. Be sure that you are installing EasyInstall into the copy of Python that is powering your Zope instance. Depending on your server configuration, this may or may not be your system-wide Python.

If you're using your system (or a shared) Python to run Plone, you'll need to be cautious about installing Zope- and Plone-specific add-ons. They can conflict with one another. If you need to use your system or a shared Python, consider using virtualenv to control this risk by creating virtual, isolated Python environments for each Zope/Plone installation.

Got it!

Once you have EasyInstall, you can install an Egg-based add-on Product simply by typing:

 easy_install name-of-product

where "easy_install" is the full pathname of the easy_install command for the Python that you're using to run Plone. For the popular installers, the pre-installed easy_install is typically in one of these locations:

Windows

\Plone 3\Python\Scripts\easy_install

OS X

/Applications/Plone-3.0.6/Python-2.4.4/bin/easy_install

Unified Installer (Linux/BSD/Unix)

/opt/Plone-3.0.6/Python-2.4.4/bin/easy_install

If you have more than one copy of Python on your system, you may wish to explicitly specify where EasyInstall should install the Product.  You can do this with the --prefix switch.   For example, to install a Product into the lib/python directory of a Zope instance located at /usr/local/zope210/instance1, type:

easy_install --prefix /usr/local/zope210/instance1/lib/python name-of-product

Slugs, ick!

Once you've EasyInstalled your Product, you may need need to create a ZCML slug in order for Zope to recognize and activate the Product.

If the add-on Product you are trying to install is part of the Products.* namespace (e.g. its name is "Products.Something"), then Zope will automatically detect and use it. However, if your add-on Product is not part of this namespace (e.g. its name starts with anything other than "Products.") then you will have to manually create a ZCML slug, which is a single line of code.

To create a ZCML slug for an add-on Product:

1. Navigate to your Zope instance's etc/package-includes folder.
2. Create a file called "nameofyourproduct-configure.zcml"
3. Put the following line of code in that file:
   

<include package="name.of.product" file="configure.zcml" />

For example, to create a ZCML slug for a product called "plone.portlet.static", you would create a file called "plone.portlet.static-configure.zcml" with the contents

<include package="plone.portlet.static" file="configure.zcml" />

Further information

http://plone.org/documentation/tutorial/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.