You are here: Home > Resources > Intro to Buildout for Plone-3
 

Intro to Buildout for Plone-3

How to use zc.buildout to add Products to a Plone-3 site and how to use zc.buildout to create a production Plone-3 site.

Outline

  1. Section One
    1. Introduction
    2. Getting ready
    3. What's zc.buildout?
    4. Where are my files?
    5. What are parts?
    6. How do I add Product X?
    7. Running the buildout script
  2. Section Two
    1. Keeping your buildout in a source code repository
    2. A buildout for a production site
      1. Products for production sites
      2. The ZEO database server
      3. The Zope instances
      4. Varnish - a caching proxy server

Section One

Here's where we introduce your instructor and explain the basics of using zc.buildout (usually referred to as just "buildout") to manage your Plone site's software.

Introduction

Your instructor is: Larry Pitcher of Catapult Solutions in Walla Walla, WA. Larry has been working with Plone since 2004. You can often find him in the #plone chat room under the nick "unclelarry."

This course will cover the basics of using buildout to add Products (add-on modules) to a Plone web site, and we'll also cover the basics of using buildout to manage a Plone production web site's software.

Getting ready

Plone should be installed

Before starting the class you should have Plone-3.2.2 or later installed and running on your computer. Here is the download page for Plone-3.2.2. Linux users should use the Unified Installer (it's called "Unified" because it works on many different Linux distros). Windows users should use the Windows Installer. There's a special installer for Mac users, but since I don't have access to a Mac, I can't give you much help with that specifically. There are installation instructions available on this page for Linux users and on this page for Windows users.

Tools you will need

  • You'll need to have a command prompt (on Windows) or a terminal window (on Linux) open to run the buildout commands.
  • You need to be able to browse your file system, either in your terminal or in a "file explorer" type program.
  • You'll need to edit the text configuration files with a basic text editor. If you are using Windows, it will help if you have a nice text editor like notepad2 or notepad++, since the Windows notepad editor is not optimal for these kinds of files. Most Linux systems come with a basic text editor that will work fine.

What's zc.buildout?

The basics

The software called zc.buildout (or just "buildout" for short) is a Python package (did I mention that all of this Zope and Plone software is written in the Python programming language?) that helps developers to manage software installations. The package is installed for you by all of the Plone installers. In fact, the Plone installers use buildout to manage the installation of Plone on your computer.

Confusing terms

When you read the Plone documentation or ask questions in #plone you'll often hear phrases like "...then add this line to your buildout" or "now you need to re-run your buildout." This can be confusing for new users, since these two statements are really talking about very different things.

Edit your buildout

When helpful people tell you to "edit your buildout" the actually mean "edit your buildout.cfg file." We'll be looking at the buildout.cfg file in some detail later.

Re-run your buildout

When you are told to "run (or re-run) your buildout" what you really need to do is to run the bin/buildout script (on Linux) or the bin\buildout.exe executable (on Windows). We'll look at this later, too.

Where are my files?

After you install Plone, where does your Plone site's files live?

  • The Plone installer for Windows will try to put the files in: C:Program Files\Plone (C:\Program Files (x86)\Plone on Vista 64bit).
  • The Unified Installer for Linux will put your files in: /usr/local/Plone if you do a root install, or in <myhomefolder>/Plone if you don't.
  • When you are installing Plone you can choose to install it in a different location if you'd like. For this class I won't assume that it's installed in any certain location. I'll just start off with the Plone directory and you will have to know where that is located, either in the default location, or somewhere special that you chose.

Which files are important?

  • The file that we'll be most interested in is called "buildout.cfg." This file is where we tell buildout which add-on products to download and install for us. Here's a copy of the buildout.cfg file from the Plone-3.2.3 Windows Installer. We'll be taking a look at the contents of this file later.
  • The second most interesting file for us is the buildout script/executable, which is located in your Plone/bin directory. This is the file that you run to make buildout work.
  • If you're running Plone on Linux, you also need to know about the plonectl script. This is how we start and stop Plone on Linux. This script is also located in Plone/bin.

What are parts?

The buildout.cfg file has several sections, which are called "parts". Each of these parts has a different purpose. The parts that we are most interested in are called "productdistros" and "instance." Each part in the file is labeled with its name in brackets.

[productdistros]

The productdistros part is where we add "old-style" products that are not Python eggs. These products will have a download link in their installation instructions. The download link should be put into the buildout.cfg file like this:

[productdistros]
recipe = plone.recipe.distros
urls =
       http://plone.org/products/docfindertab/releases/1.0.4/Products.DocFinderTab-1.0.4.zip
       http://plone.org/products/windowz/releases/1.2/windowZ-1.2.tgz
nested-packages =
version-suffix-packages =


[instance]

The instance part controls the details of your Plone installation, such as the port number that the Zope web server runs on, the administrator username and password, as well as products that you wish to install from Python eggs.

How do I add Product X?

You'll probably want to add products to your Plone site, like a visual theme.

Let's say that you want to use the "Busy City Theme" product. This theme is packaged as a python egg and the product's page on plone.org has good installation instructions. It tells us to add "alterootheme.busycity" to our [instance] part under the "eggs" and "zcml" directives. Before we start, it's a good idea to make a backup copy of the original buildout.cfg file, just in case we accidentally make a mess of it.

Edit your buildout.cfg to add an egg.

  1. Open up your buildout.cfg file in your text editor of choice.
  2. Find the section labeled: "[instance]"
  3. Find the line that has: "eggs ="
  4. Add "alterootheme.busycity" below the list of eggs.
  5. Find the line that has: "zcml ="
  6. Add "alterootheme.busycity" below that line.
  7. Save your buildout.cfg file.

Adding an "old style" product.

Some products are not yet packaged as Python eggs. These products need to be installed using their download link, as demonstrated in the previous section. If you find a product that you want to use that is not packaged as a Python egg you will need to find the download link on the product's page on plone.org and enter that URL in the [productdistros] part.

Running the buildout script

After you've edited the buildout.cfg file you need to "run" your buildout. I mentioned the buildout script (executable on Windows) file earlier. This script uses your buildout.cfg file as a guide to set up your Plone software installation. 

Command syntax

To run buildout open a terminal/command window.

  • Linux
    • To run the buildout script, cd into your main Plone directory, such as /usr/local/Plone if you installed Plone as root or in <myhomefolder>/Plone if you didn't.
    • Run this command:
    • # ./bin/buildout -v
    • If you installed Plone as root you may need to use sudo to run buildout.
  • Windows
    • To run the buildout command, cd into your main Plone directory, such as C:\Program Files\Plone.
    • Run this command:
    • > bin\buildout -v

The buildout command has several other options, which you can view by using the -h option, but for a basic buildout the -v (verbose) command is sufficient.

What if there are errors?

If you get errors when you run buildout, use Google to look for answers first, and if you don't find an explanation there, ask in the #plone chat room or the plone-users email list. If you ask in #plone, make sure that you paste your error into paste.plone.org first. Don't paste a long error traceback into the chat room.

Document Actions