Document Actions
Using Add-on Products
Note: Return to tutorial view.
Finding and downloading products
The most common place to look for third-party products is the Plone.org products area. Most mature products list themselves here.
The Plone Software Center that powers the products area provides several tools for product authors, including a roadmap tool (like the one Plone itself uses), and an issue tracker (powered by Poi, which of course has its own issue tracker) and a documentation section (powered by the PloneHelpCenter, which also powers the Plone.org documentation section where you are probably reading this). Not every product uses all of these features, of course.
Most products will post a description of the project and usually also installation instructions in their products area. Be sure to read this. Many products will have other dependencies, or requirements for third-party products. Make sure you download all the necessary components.
Evaluation
It is important to realise that the products in the products area are not necessarily quality-controlled to the same standards that Plone itself is - doing so would simply be too time-consuming and place unnecessary limits on the freedom of third-party developers to share their creations with the rest of the Plone universe. However, this does mean that you have to be a little careful when you install a product!
First of all, there are often several products that do roughly the same thing. For example, there are several message board applications with different strengths and weaknesses. How shall you choose? And how do you know if a product is reliable or ready for real-world use?
First of all, you could judge the state of the product by how it presents itself. Does it provide sufficient information for you to understand what it does? Does it have a bug tracker? How many open or closed bugs are there? What version is it at? A product with an alpha release is obviously less stable than a product with a final release.
Secondly, try to gauge what other people are using. It may be a good idea to ask politely in the mailing lists or the chatroom for other people's experiences.
Ultimately, though, you will have to try it out! When doing so, you should never, ever simply install it on your one and only "production" Zope instance. Third party products have been known to completely hose your Plone instance before. There are a two golden rules:
- Always try out a product on a test instance. Ideally, this should be an exact copy of your production instance.
- Always keep backups of your production instances, and take a backup immediately before installing a new product. You never know what can go wrong.
To set up a test instance, you should install a second Zope instance (usually it is easiest to do so using the mkzopeinstance.py script, see the set-up from source how-to), and copy the contents of the Products directory and the Data.fs from the production Zope instance to the test one. This way, you will have an exact copy to play with.
Installing an Add-on Product
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
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.
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:
- Navigate to your Zope instance's etc/package-includes folder.
- Create a file called "nameofyourproduct-configure.zcml"
- 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.
