Saturday, 3 November 2007

Plone 3: Deployment using buildout

A new feature of Plone 3 is the buildout process. It's a much smarter way of setting plone up and could be useful if you're managing several plone sites. But equally, if you're interested in taking Plone 3 for a testdrive, getting started by using the buildout system is probably a great way to get up and running quickly.

If anyone's interested in a rough guide for getting started with Plone 3 (and using buildout to set-up a zope 2 / plone 3 environment, here's my notes (and some reference links) on setting things up.

Firstly, I've set this up using Ubuntu 7.10 (Gutsy); the process should be pretty similar for other distros though.

Before you read any further, here's a disclaimer: Plone 3 currently only works with Python 2.4. Ubuntu 7.10 ships with Python 2.5. The install method I'm outlining here doesn't require uninstalling Python 2.5 although I can't make any promises. You will need to install Python 2.4 on your machine - and I can't promise that setting this up won't break anything else on your system. You have been warned.. :)

Ok, so with that out of the way, here's a note of the steps I took to get things up and running (and links to other good articles for further reading):

1. Install python2.4 and python2.4-dev:
sudo apt-get install python2.4
sudo apt-get install python2.4-dev

2. Set python 2.4 as default (please read disclaimer first!):
- remove the symlink for python 2.5
sudo rm /usr/bin/python

- replace symlink with one for python2.4
sudo ln -s /usr/bin/python2.4 /usr/bin/python

- edit the debian defaults file
sudo vim /usr/share/python/debian_defaults

- Change the default version from python2.5 to python2.4 like so:

# the default python version
default-version = python2.4

I'd like to acknowledge the ProgProg site for this solution - check the original post here: (

Once you've made those changes, check by running 'python' from the command-line (Ctrl+D exits).. If it's been successful, you should now be running v2.4.4 by default

If it is, you should be ready to get started with the Plone buildout. Most of the initial information I got for setting this up is from Martin Aspeli's *awesome* article on the Plone site - well worth a read:

Now we have Python 2.4 running, we need to install a few things - starting with easy install and PIL (the Python Imaging Library):
sudo apt-get install python-setuptools
sudo apt-get install python-imaging

When I first tried running this, I had problems with the version of setuptools that apt-get installed (it was older than the one required). I solved this by grabbing the latest .egg file from the cheese shop:

- go to the site and download the egg file to your machine:
- Install the egg using easy_install:
sudo easy_install -U setuptools-0.6c7-py2.4.egg

If you get errors with the install (if easy_install doesn't appear to be working as expected), grab the latest version and run it:

sudo python

Once that's all done, we can start working:

- Install ZopeSkel:
sudo easy_install -U ZopeSkel

To test ZopeSkel:
paster create --list-templates

If successful, you should see a list of templates (like this):

Available templates:
archetype: A Plone project that uses Archetypes
basic_namespace: A project with a namespace package
basic_package: A basic setuptools-enabled package
basic_zope: A Zope project
nested_namespace: A project with two nested namespaces.
paste_deploy: A web application deployed through paste.deploy
plone: A Plone project
plone2.5_buildout: A buildout for Plone 2.5 projects
plone2.5_theme: A Theme for Plone 2.5
plone2_theme: A Theme Product for Plone 2.1 & Plone 2.5
plone3_buildout: A buildout for Plone 3 projects
plone3_portlet: A Plone 3 portlet
plone3_theme: A Theme for Plone 3.0
plone_app: A Plone App project
plone_hosting: Plone hosting: buildout with ZEO and any Plone version

If you do, you're now ready to set up the environment. Either you can set up a dedicated user (e.g. www, plone or whatever you choose to call it), or if you're just testing it out, you could use your own account.

From your home-directory (or within a folder in your home-directory):
paster create -t plone3_buildout myploneproject

- here, plone3_buildout is the name of the template you're using and myproject is the name of the folder you're going to create your build in.

It will ask you a series of questions, leaving most of these blank should get you a working fresh zope 2 / plone 3 instance. You'll need to enter a username and password to allow you to manage the control panel; I'll leave this for you to decide upon.

Here's an example using mostly the defauts (note that I'm using admin / mypassword for this example):

user@mypc:~/plone$ paster create -t plone3_buildout myploneproject
Selected and implied templates:
ZopeSkel#plone3_buildout A buildout for Plone 3 projects

egg: myploneproject
package: myploneproject
project: myploneproject
Enter zope2_install (Path to Zope 2 installation; leave blank to fetch one) ['']:
Enter plone_products_install (Path to directory containing Plone products; leave blank to fetch one) ['']:
Enter zope_user (Zope root admin user) ['admin']: admin
Enter zope_password (Zope root admin password) ['']: mypassword
Enter http_port (HTTP port) [8080]: 8080
Enter debug_mode (Should debug mode be "on" or "off"?) ['off']:
Enter verbose_security (Should verbose security be "on" or "off"?) ['off']:

After that's done, cd into the folder for the project you just created:
cd myploneproject

And run the bootstrap script:

Let's create a generic buildout and test it before adding some extra bits in:
bin/buildout -v
(if that doesn't work, try ./bin/buildout -v)

This should take a little while, but watch as the buildout handles all the dependencies for you and sets everything up automatically :)

When you get your terminal prompt back, you should now be able to build and run your initial zope 2 instance:
./bin/instance fg

Give it a few minutes to set everything up for the first time and check your zope instance:
Point your browser to:

And enter the username and password you just specified (e.g. admin | mypassword)

You should see a dropdown menu to the right, find 'Plone Site' in the listing and select it. Enter the Id name (I'm going to use testplone for this example) and hit 'Add Plone Site'

When you get back to the control panel, you should now see something like 'testplone (Site)' in the listings. If so, point your browser to:

And after a few seconds, you should see your test instance of Plone!

I'm going to bring the site down, make a couple of quick modifications and bring it back up just to demonstrate the power of buildout:

Go back to:
Select the Control Panel link from the left and hit the Shutdown link.

Go back to the terminal (and your project directory) and edit buildout.cfg file:
vim buildout.cfg

Find this:

# elementtree is required by Plone
eggs =

And add this below element tree:

So it should now look like this:
# elementtree is required by Plone
eggs =

Also find this:
# e.g. zcml = my.package my.other.package
zcml =

And add plone.portlet.static here too - so it should look like:

# e.g. zcml = my.package my.other.package
zcml =

These lines will add the "static html portlet" to Plone 3 - this allows you to create a portlet on your site which you can just put plain html into - rather useful.

I'm also going to add a 'classic' plone2 plugin, ZWiki0.60 into the build - here's an example -
Find this:

recipe = plone.recipe.distros
urls =

And add the URL for the current build of ZWiki here:
(or check for the latest version)

So you should now have:
recipe = plone.recipe.distros
urls =
nested-packages =
version-suffix-packages =

Save the file and quit the editor.

Rebuild and re-deploy:
bin/buildout -v
./bin/instance fg

Go back to your plone instance and to the control panel:

Select Install products (or go here):

You can now check Zwiki and Static text portlet as installable products!

1 comment:

Milo Joseph Hardwick said...

Fantastic article...! Really helped me out, sir. I've been struggling all morning with getting my buildout to work.

Many, many thanks!