Automating Plone site creation with collective.recipe.plonesite

Back in May, I gave a talk at Plone Symposium East about migrating from Drupal to Plone with Transmogrifier. Part of my presentation involved showing the power of collective.recipe.plonesite in combination with zc.buildout. During the talk, when I asked who had heard about this recipe, only a couple of people raised their hands. I then promised to write this blog post in order to raise awareness of the recipe and how it can help you.

The Plone site recipe makes it possible to automate the creation and maintenance of a Plone site via zc.buildout. The main goal of the recipe is allow for a Plone site to be created during a buildout run. When working on a project with a large group of people, it is important to make sure that everyone is working from the same basis. Buildout helps to do this by installing various additions and pinning versions, but there was no way to make sure the Plone site was always set up the same way. At Six Feet Up, this would lead to a lengthy "getting started" page being created on the project wiki.

Creating a Plone site

Automating the creation of the Plone site is as easy as adding a part to the buildout configuration. Here is an example of the simplest possible configuration.

[buildout]
parts = instance plonesite
extends = http://dist.plone.org/release/4.0.7/versions.cfg

[instance]
recipe = plone.recipe.zope2instance
user = admin:admin
eggs = Plone

[plonesite]
recipe = collective.recipe.plonesite
site-id = test
instance = instance

This configuration consists of only two parts, instance and plonesite. The instance part sets up the Zope instance and downloads all the necessary packages to run Plone.

The plonesite part gives buildout the information it needs to create the Plone site. The site-id will be used as the id for the Plone site object that will be created. The instance option tells buildout what Zope instance will be used to run the script that creates the Plone site.

Running the buildout will now result in a Plone site being created.

$ python2.6 bootstrap.py
$ bin/buildout
Installing instance.
Installing plonesite.
Retrieved the admin user
Added Plone Site
Quick installing: []
Running profiles: []
Finished

Once that has completed, the instance can be started up.

$ bin/instance fg
2011-07-07 13:05:17 INFO ZServer HTTP server started at Thu Jul  7 13:05:17 2011
    Hostname: 0.0.0.0
    Port: 8080
...
2011-07-07 13:05:26 INFO Zope Ready to handle requests

To verify that the Plone instance has been created, open the site up in the browser by going to http://localhost:8080/test, you should see a blank Plone site which looks like this:

Installing Products and Profiles

The Plone site recipe also has the ability to quick install products and run GenericSetup profiles. This allows each developer to start with the exact same setup, since you know what was installed when the site was created.

The options provide two points where you can run your install code. The first is called initial. These options will only run after the initial creation of the site. This is useful for one time set up code that should only run after the site has been created.

The second install point runs every time once the site has been loaded. This allows for the ability to run the profiles and keep the site up-to-date. No longer will you have to release your code, then login to the site and have to remember what steps to take after that. The Plone site recipe can handle all this for you by relying on GenericSetup profiles to handle the heavy lifting.

Here is an example of using a fictional product named my.policy. In this policy package we have two profiles defined, my.policy:initial and my.policy:default. Here is how these would be added to the Plone site part:

[plonesite]
recipe = collective.recipe.plonesite
site-id = test
instance = instance
profiles-initial = my.policy:initial
profiles = my.policy:default

Following normal buildout conventions, you can add as many profiles as you like by adding the one per line or separated by spaces. At Six Feet Up, we typically only have the policy package listed here, the rest of the dependencies are handled via GenericSetup's metadata.xml.

Command Line Helpers

There are two helpful command line tips which make using the Plone site recipe even better.

The first is the ability to easily create a fresh build of a project that is under heavy development. In the early stages of development, there are times when your current instance may become unusable, or you need to run the latest profile code against a clean instance. This is where the site-replace option comes in handy. This option tells the Plone site recipe to delete the Plone site referred to by the site-id option. Here is how to do this from the command line:

$ bin/buildout plonesite:site-replace=True
Retrieved the admin user
Removed existing Plone Site
Added Plone Site
Finished

The site is now put back into its original state. This makes use of buildout's ability to change a part's variables from the command line. Just be careful not to run this on production!

The second option allows you to skip loading up the Plone site during the buildout run. By default, each time you run your buildout with the Plone site recipe installed, it will start up Plone and apply the profiles listed. With the enabled option, this can be avoided if there is no need to run the profiles (e.g. just making a buildout config change).

$ bin/buildout plonesite:enabled=False

On this run, the build will happen much faster as it does not need to start up Plone.

Conclusion

This recipe has helped Six Feet Up simplify the development and release process for its projects. Using the Plone site recipe automates much of the process and means that less human interaction is needed in order to ensure build quality. This also makes sure that setup code remains under version control and can easily be reviewed, modified and passed on to the next developer or release environment.

See more detailed documentation on the product page on plone.org.