Updating a custom Plone 3 buildout for Plone 4


The installers are the recommended way to install Plone 4, but if you have a custom buildout that you want to continue using, there are several changes you'll need to make.

If you have an existing buildout for a pre-4.0 Plone site, some updates are needed to make it work with Plone 4. These instructions assume that you are starting with a working buildout for a Plone 3.3.x site. If you're on an older version of Plone, see the appropriate section of this manual to upgrade it to Plone 3.3.x first.


Trying to update an existing buildout in place is not recommended. Work on a copy of your buildout configuration and site data until you are confident that the upgrade runs successfully.

If you need an example of a working Plone 4 buildout for comparison, look at the ones included in the installer for your platform, or generate one using ZopeSkel's plone3_buildout template. (Yes it has Plone 3 in its name, but as long as you have an up-to-date version of ZopeSkel and enter 4.0 when it prompts for the Plone version, it will generate a correct buildout.)

Common steps to update buildouts for Plone 4

  1. Plone 4 requires Python 2.6, whereas Plone 3 uses Python 2.4. Make sure that you start your buildout off on the right foot by running bootstrap.py using Python 2.6. (If you aren't sure how to get a Python 2.6 installation that works on your system, one option is to run the Plone installer, and then use the Python that it builds to run your custom buildout.) If you have set the executable variable in your ~/.buildout/default.cfg, remove it.

  2. Make sure the [buildout] section has an extends setting which extends the official Plone versions.cfg file for the correct version of Plone. For example:

    extends = http://dist.plone.org/release/4.0/versions.cfg

    If you are providing additional version pins, make sure that they are provided within the file that extends the Plone versions, or in a separate file that is extended after the Plone versions. Also make sure you don't inadvertently override any version pins from the core Plone set.

  3. Remove the part using the plone.recipe.zope2install recipe (this part is often called "zope2"). Zope 2 is now installed automatically as an egg dependency of the Plone egg, rather than via a special recipe. (Zope 2 also includes its own dependencies as eggs, so fake eggs are generally no longer required.) You will also need to remove any references to variables from the zope2 part from other parts (such as "${zope2:location}").

  4. Remove the zope2-location setting from the part using the plone.recipe.zope2instance recipe; it is no longer needed now that Zope 2 is an egg. Also update this part to specify the location of the BLOB storage directory that will be used by the instance:

    blob-storage = ${buildout:directory}/var/blobstorage

    If you will be running the instance as a ZEO client on the same machine as the ZEO server, you should configure both to use the same blobstorage directory, and set the shared-blob flag on each Zope instance:

    shared-blob = on

#. If your buildout installs ZEO, make sure that you use the new plone.recipe.zeoserver recipe instead of plone.recipe.zope2zeoserver. The new recipe does not need a zope2-location setting, since ZODB is now installed as an egg. An example of a working ZEO part configuration:

recipe = plone.recipe.zeoserver
zeo-address = 8100
  1. If you are using the collective.recipe.filestorage recipe to set up filestorages for multiple ZODB mountpoints, you must make sure you are using the newest version of this recipe, and add the following line to its configuration so that blobstorage directories will be configured for each mountpoint:

    blob-storage = var/blobstorage-%(fs_part_name)s

#. If you are using the collective.recipe.supervisor recipe to install and configure supervisord to run your Plone processes, the correct way to start Zope in the foreground is now the "console" parameter to the instance script. The programs setting of this recipe must be updated to use that parameter instead of the old runzope script which is no longer generated by Zope. For example:

programs =
    10 instance ${buildout:bin-directory}/instance [console] ${instance:location}