How I structure plone projects¶

There is a rule number one: everything must be stored in svn. If you have pieces of configuration outside of svn, you're in for pain. I've had to work my way through Products/ directories trying to figure out which versions were in there. version.txt helps a bit, but once it is a version of which you cannot find a .tgz, you're done for. Or, if it is an svn checkout: is it safe to update it or does it need to be a specific revision?

Which pieces of configuration should you include? Well, which products are installed. Which plone version. The apache config file(s). Perhaps an awstats config. A cronjob for /etc/cron.d. Those config files are simple: just store them somewhere in your svn, I'll get to the location later. For the list of products and the plone version you've got basically three choices:

• A "readme" file that lists your plone version and add-on products. You'd better keep those up to date!
• Put the zipfiles in some svn directory of your choice. Your svn repository won't really like that, neither the backup of your svn repository.
• Put the list of products (and download locations) in some script that downloads and installs them.

I use the last method, by using instancemanager. Basically a config file like this (URLs shortened to keep 'em on one line):

archive_sources = [
    {'source': 'qPloneGoogleSitemaps-0.3.0.tar.gz',
     'url': 'http://surf..../qPloneGoogleSitemaps-0.3.0.tar.gz',
     },
    {'source': 'RedirectionTool-1.1.tar.gz',
     'url': 'http://plon.....s/1.1/RedirectionTool-1.1.tar.gz',
     },

Instancemanager will reliably download those files and put them in your Products directory. Works for bundles, too. A good custom shell script or stuff like buildout can also help here. Nobody has to wonder which products and which versions to use: just look at (or use...) the config file.

For a small project with just one custom product, I normally add an instancemanager directory inside that custom product. Which, of course, is in your svn repository. In there, I put the instancemanager config with the specification of the project (other add-ons, plone version, zope version). Perhaps another directory for some documentation and an apache config file.

For a big project, you'll probably end up with a couple of specific svn checkouts of add-on products and a set of custom products. Svn bundles to the rescue! I normally make sure I only have to grab one svn checkout to set me up completely. Inside that checkout I've got the following directories:

myproject/externalproducts

An svn bundle of the external add-on products for which I need a specific checkout instead of a regular zip file. Perhaps a branch on which I'm doing fixes. Or a specific revision. The exact configuration is again explicitly in svn in this way!

myproject/products

An svn bundle of the add-ons I'm developing myself. Project-specific stuff. It somehow is handy to differentiate between "products" and "externalproducts" as you've got to take greater care with changes in products that other people are using than with changes in your own project-specific products. Put your DIYplonestyle theme in here, for instance.

integration

Here's where I put the configuration for bigger projects. I normally subdivide it further into subdirectories

integration/instancemanager

Instancemanager configuration files. Often a projectname.py for regular development and a specific production.py with the current stable production server's configuration.

integration/apache_etc

The apache configuration files.

integration/cron_d

Some cronjobs you want to put in to /etc/cron.d

integration/doc

Documentation for the whole project. Explanation of how to set up the server. Backup/restore documentation.

This way of setting up projects slowly developed during a few years of setting up projects like this. We also use it at zest software for the majority of our projects. One thing that's not fully crystallized yet is how to deal with production bundles and development bundles. The needs for this tend to differ wildly per project. Some only do an update once every two months, others try out a quick change in preview and put it into production right away as they need a more rapid cycle.

I hope this is of help to some people. It would be interesting to hear of other setups or recipes. If you don't have a blog yourself, feel free to email me.