Upgrading to 2.1.x

Some notes on the process of updating your Plone site software.

The process of upgrading a Plone site can be intricate. The 2.0.x to 2.1.x jump is no different. (Anyone who has followed the series of quirks and bugs in Agapow.net over the early part of 2006 will have seen the evidence.) While you could just avoid the move, there are compelling new features in the 2.1 release of Plone and several useful Products that work only in 2.1.

Note: For reference, I was upgrading from Plone 2.0.5 and Zope 2.7.6, and hoping to get to Plone 2.1.2 (the latest stable).

General notes

The first general principle is that Zope/Plone and their associated Products can be very version-sensitive. So you can't just leap from say) Zope 2.7 to 2.9. You may have to upgrade in several steps. Check the requirements.

The second principle is that you upgrade from the top down. Update all your products, then upgrade Plone, then Zope, then Python (if necessary). Of course, updated versions of Products may lose compatibility with older versions of Plone and so on (c.v. RichDocument). Again, you may have to upgrade in several steps.

Third principle, backup all along the way. The simplest way is just to copy the whole Products and var directories. This way, if you make a mistake or are forced to rollback the upgrade, you can just drop the old directories back and you're in business.

See the Plone migration how-to.


Specifics: First I upgraded Zope from 2.7.6 to 2.7.8. (Previous experiments showed this was necessary.) Assuming you have several Zope installations on your host machine, this is done by simply by changing the paths listed in the the zope/bin/runzope and zope/bin/zopectl scripts. Test your installation by running it with runzope -X "debug-mode=on and then shut it down.

Then I downloaded the latest version of Plone (2.1.2), unpacked and copied - not moved! - all the resulting Products into your instance Products directory. This makes it easier if you have to reattempt the upgrade later. I tested the site with runzope again and it looked like a mess but this is to be expected. There's a migration script to bring content up to date, found in the ZMI in the site as the portal_migration tool. It showed that the site instance was an older version than that on disk, again what was expected. So I clicked Dry run and attempted a migration.

Errors were reported and fixed before the migration was done for real. Then I checked the Add/Remove products panel of the actual site to see if anything needed to be updated or reinstalled.

Assorted issues

Plone 2.1 makes all your top level folders tabs, one of the (IMHO) uglier aspects of the Plone UI. The migration doc suggests a few ways to get rid of, but I found it was easiest to just use a bit of css:

#portal-globalnav { display: none; }

Migration can get stymied by what appears to be incorrect or incomplete folders, particularly the Members folder or those within it. If you examine the traceback given at migration failure, you should see which one is giving trouble. Several scripts have been suggested to fix this but I favoured a simpler solution: cutting all the content out of the troublesome folder and then deleting it.

Another problem occurred with a top-level object I had with the id news. The Plone migrator attempted to create a folder with the same id, and fell over when it couldn't. Solution: rename the old folder, migrate, and rename the new folder.

Making the jump to Zope2.9 will require more editting of the zope run scripts, as the Python Zope module has been renamed to Zope2.

After the migration, PloneSoftwareCenter was broken, with any file downloads from it silently failing. This can be fixed by installing the most recent plone-2.1-integration branch of PSC from the Plone collective SVN area, as well as the ExternalStorage product. This seems to fix things.

CMFPhoto appears to be broken as well.