Purpose

This document is a crash course for non-technical persons how to diagnose add on product installation problems with Plone. This document does not give you an answer why your installation doesn't work, but it will explain how to extract information from Plone system and where you should take this information if it doesn't give enough clues how to solve the problem.

Different installation processes

Newer Plones contain buildout command line utility to manage Plone configuration. It is based on buildout.cfg configuration file. When buildout command is executed it reads this file and downloads necessary files from PyPi package repository to your Plone configuration.

Some older Plone products are distributed as archive files. This document is helpful.

How you install your product depends on whether your Plone is managed by buildout and how the third party add on product author ships the product. The buildout based mechanism is recommended if the product supports it.

Reading product specific information (README.txt)

Products may contain special procedures and additional product dependency installations before they became useful. These are always documented within product themselves and there is no generic answer for this problem.

1. Read product instructions on the product page at plone.org products area. See if the product contains a special documentation link or document section within the plone.org product area.
2. Read product instructions shipped within the product

• If you are using a buildout based installation the product files are usually placed in eggs/YOURPRODUCTNAME-VERSIONNUMBER-egg folder if the buildout command completes succesfully. If the buildout command does not complete succesfully copy-paste the buildout printout and proceed to the section "asking for help."
• If you are using a packed product tar-file or zip-file the installation instructions should be contained in the archive as README.TXT or INSTALLATION.txt file

Product installation mechanism

These are the usual steps to activating an add on product

1. Getting add on product files to your system and make Plone to find the add on product files
2. Executing the Add On products installer which performs adaptions on your site database to use the product

Getting Python files to your system

If you are using a package file based installation (zip/tar.gz file) you must download this file and extract it correctly. On Windows systems .tar.gz archives might be difficult to open, since Windows does not support them directly. Please use an utility like 7Zip to extract this archive.

Buildout command should download the required files when executed.

When buildout command fails

Please copy the buildout command output from your console and go to the step 'Asking for help'.

If you are getting HTTP 404 Not found errors or timeout errors it might be that PyPi package repository servers are down. Please go to step Asking help on chat to ask whether other people are expering the the same problem.

Why doesn't the add on product installer appear in Add/remove section

This is probably the reason why you are reading this document.

1. The add on installer does not appear until Plone restart. You need to restart Plone server it detect changes in the code files. Did you remember to do this?

If you did and the add on product still does not appear the usual reasons are

1. Not all product dependencies are installed and Python import fails when trying to access these modules.
2. There are version incompatiblities and Python import fails because module expectations mismatch

Pleas reread the installation instructions. If they don't help you then follow the steps below to diagnose the problem.

How to pinpoint the reason what is wrong

If Add on products Add/Remove installer does not find your product please to the following:

1. You need to put your Zope application server to debug mode
2. You need to restart Plone
3. Read the add-on product start up failure reason from Zope log files

Putting Zope to debug mode

When Zope is in debug mode any product start up failure will prevent Zope to start. You cannot access your Plone site as long as there are faulty products and Zope is in debug mode.

Buildout based installations

In buildout.cfg file, change line:

debug-mode = off

to:

debug-mode = on

Run buildout command:

bin/buildout

Restart zope:

bin/instance restart

Other installations

Find file etc/zope.conf. This file is somewhere under your Plone folder. The location of the file might vary between operating systems and Plone versions. On Windows it is usually C:\Program Files\Plone 3\Data\etc\zope.conf.

Change line:

debug-mode off

to:

debug-mode on

Restart Zope using either command bin/zopectl restart, Plone control panel on Windows or Windows services restart button in Windows Control Panel.

Finding the log file

The next step is to open the log file for examination. Plone has two log files: one for application output and one for site statistics. You need to open the former. It is called either event.log or instance.log.

On Windows, the Plone log file is usually located in C:\Program Files\Plone 3\Data\log\event.log.

On buildout based Plone installations log file is $INSTALLATION_FOLDER/var/log/instance.log.

Reading the log file

New log entries are appended to the end of the file. Use your machine's clock and log file timestamps to match the entires. Search the log file using your product name as a key.

Below is a sample entry what you are looking for:

2009-01-03T19:30:07 ERROR Application Couldn't install PloneFormGen Traceback (most recent call last):
File "C:\\Program Files\\Plone 3\\Zope\\lib\\python\\OFS\\Application.py", line 758, in install_product
global_dict, global_dict, silly)   File "C:\\Program Files\\Plone 3\\Data\\Products\\PloneFormGen  \\__init__.py", line 14, in ?
from Products import PythonField, TALESField, TemplateFields ImportError: cannot import name PythonField

In this particular case, we can see that the add on product PloneFormGen cannot open module PythonField.

Google search ploneformgen pythonfield reveals that we need to install ScriptableField product prior installing PloneFormGen product.

When Add On product installer fails

After Plone finds add on product Python code files and they are intact, the product appears in Add on products section in Plone site setup. This is calledproduct quick installer. Note that not all products have a quick installer. E.g. products which are generic Zope products do not have a Plone quick installer.

The quick installer is intended to perform changes to your site instance database to make the product usable. The add on products need this two staged installation procedure, because all Plone sites under Zope application server share the same Python code files, but databases are site instance specific.

When your product appears in Add-on products section on your Plone site, but executing the installer by pressing the install button fails, you should see an exclamation mark icon next to the product name. Press this warning icon to read the log entry.

Asking for help

Plone experts need the following information to help you with your add on product problem

• Add on product name and version you are trying to install
• Your operating system name and version
• Your Plone version
• Log entry related to the problem

Te log entry is the crucial piece of information to know what has failed. The purpose of this document is prepare you to have this information on hand so that people can help you.

Google for help

Before asking for help, make a Google search with related keywords. Pick meaningful keywords from the log entry. In our example above, we would do a Google search for words:

ploneformgen pythonfields

You might need to try different variations, since the problem might not be the add on product specific, but a general Plone/Python problem:

plone pythonfields

plone pythonfields importerror

Google search will bring up all related discussions if someone has had the same problem before and you will have your answer right away.

Asking help on mailing lists

Mailing lists provide an answer with few days response times.

Use plone.org -> Support -> Forums -> General forum to ask help related to third party add on installation problems. Note that you need to subscribe to the forum through Nabble.

Asking help on chat

When you ask the help in chat you need to have your log entries prepared beforehand.

1. Paste your log entry and related information to paste.plone.org information sharing clipboard

2. Start chat conversation using plone.org IRC chat web gateway

3. Do not ask permission to ask a question, but directly start the conversation having the all necessary input. The example below:

   Hi! I am trying to install PloneFormGen product, but it does not appear in the add on products list.
   When I start Zope in debug mode I get the following log entry.
   I pasted the log to paste.plone.org and here is the link for the log entry http://paste.plone.org/25655
   

Do no paste text to chat. This distrupts other people chatting about other topics.

You might not receive an answer in the chat for few minutes if people are not at their computers. Please be patient.

Asking help directly from the product author

In most cases, generic Plone experts can usually help you faster than the product author himself/herself.

The product author contact address is available at the product page on plone.org. Use it to contact the author and include all relevant information in the contact email.