Installing Plone add-ons - quick instructions

Introduction

This page covers add-on installation instructions for Plone 3.3.x and Plone 4 systems. Legacy systems are not covered in these instructions.

For more detailed add-on installation procedure, you might want to visit the complete add-on installation guide for Plone.

Prerequisitements

What you need to know in order to install add-ons for Plone

• How to use command line of your operating system. This is a hard requirement - you cannot achieve your goal unless you know how to interact with the command line. Here are basics tutorials for Windows and UNIX.
• Working with plain text based configuration files and editing them with a text editor like Notepad
• First create a development / back-up copy of your site. Never install to the working production server directly.

Background

Since Plone 3, Plone installations are managed using buildout: a tool for repeatable deployment process. Plone add-ons are distributed as Python modules, also known as eggs.

• Plone product download area contains popular add-ons for Plone
• Add-on file downloads are hosted on PyPi Python package repository - along with tons of other Python software
• buildout.cfg file in your Plone configuration defines which add-ons are available for your sites to install in Site Setup > Add-ons control panel
• bin/buildout command (or bin/buildout.exe on Windows) in your Plone installation reads buildout.cfg and automatically downloads required packages when run - you do not need to download any Plone add-ons manually
• Plone site setup -> Add ons control panel defines which add-ons are installed for the current Plone site (of many Plone sites on Zope application server)

Plone add-ons, though Python eggs, must be installed through buildout as only buildout will regenerate the config files reflecting newly downloaded and installed eggs. Other Python installation tools like easy_install and pip do not apply in Plone context.

Finding add-ons

Browse plone.org product area or PyPi search for possible add-ons.

When you find a suitable add-on you must write down its Python package id. If the package vendor does not tell this directly on the package page it might need you diving into PyPi to find out. For example, for package Plone SEO the package id is quintagroup.seoptimizer. The id is visible in PyPi page URL if it is not mentioned anywhere else.

Before proceeding make sure that the add-on is compatible with your Plone version. If you cannot find this information on the package page please contact the add-on author.

Downloading and configuring add-on package for Plone

It is suggested that you do not directly test new add-ons on your product site. Instead, have a development copy of the site around where you can safely test the add-ons. Before proceeding to the production environment, always take a back up copy of your Plone site.

Edit file buildout.cfg in your Plone folder with a text editor. Find line

eggs = 

There you can include your package in the  list.

eggs =
   quintagroup.seoptimizer

Some older Plone add-ons (released before Plone 3.3.x) also require you to add add-on package name to zcml= section in buildout.cfg. As a a rule of the thumb, all add-ons released since  the second half of 2010 should no longer require this.

After the buildout.cfg has been file has been changed run command buildout from command line. buildout command reads buildout.cfg file and download the packages defined in eggs section and make them available for Plone.

Note: Run buildout from command line using the instructions below. You don't double click buildout.exe.

On UNIX

bin/buildout

On Windows (for Plone 4.1)

cd C:\Plone41
bin\buildout.exe

If buildout fails please follow these instructions to diagnose add-on installation problems.

Downloading and configuring add-on package from github

Sometimes you need the newest version of an add-on, this is only suggested for experienced developers or for testing purposes.

Edit file buildout.cfg in your Plone folder with a text editor and add:

extensions = mr.developer
auto-checkout = name.of.your.product

[sources]
name.of.your.product = git git://github.com/url/of/name/of/you/product

and under the section [eggs] add your buildout.cfg:

[eggs]
....
....
name.of.your.product

After the buildout.cfg has been file has been changed run command buildout from command line. buildout command reads buildout.cfg file and download the packages defined in eggs section and make them available for Plone.

Note: Run buildout from command line using the instructions below. You don't double click buildout.exe.

On UNIX

bin/buildout

On Windows (for Plone 4.1)

cd C:\Plone41
bin\buildout.exe

If buildout fails please follow these instructions to diagnose add-on installation problems.

Enabling the add-on for your site

When buildout command completes succesfully you need to restart Plone site in order to make the new add-on appear in Plone site setup -> Add ons control panel. It is recommended that for the first add-on trial you start the site in debug mode.

The site is controlled by controller script. It name may vary depending on the installation - it may be either plonectl or instance. We assume instance here. First stop the site.

On UNIX

bin/instance stop

On Windows

bin\instance.exe stop

Then start the site in the debug mode. You can exit the debug mode by pressing CTRL+C key combination in the terminal.

On UNIX

bin/instance fg

On Windows

bin\instance.exe fg

Then navigate your way on the site setup in Plone control panel. You should see the new add-on in the add-ons list.

If the add-on does not appear to the list or if Plone site fails to start in debug mode, the most probably cause is that the add-on is not compatible with your Plone version. In any case, please follow these instructions to diagnose add-on installation problems.

Wrapping it up

After you have verified that the add-on works with your Plone configuration you can resume your site in production mode running.

On UNIX

bin/instance start

On Windows

bin\instance.exe start

Then proceed to adjust the add-on settings according to the add-on manual.

Further help

More detailed instructions for installing Plone add-ons are available for dealing with legacy systems.

Please visit on Plone help asking guidelines and Plone support options page to find further help if these instructions are not enough. Also, contact the add-on author, as listed on Plone product page, to ask specific instructions regarding a particular add-on.