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
- Command line usage basics
- Working with plain text based configuration files
- 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 product download area contains popular add-ons for Plone
- Add-on files are distributed on PyPi Python package repository using Python egg package format
- buildout.cfg defines which add-ons are available for all of your sites on Zope application server (Zope application server supports multiple Plone site instances)
- buildout command automatically downloads required packages - you do not need to download them 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)
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. 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.
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.
Visit our