Setting up Buildout Using the Windows Installer for Plone

Prerequisities

Refers to Plone3.x

Step by step instructions

This doesn't include the installation of a compiler or a svn repository and is intended as a quick and easy way of getting buildout up and running on Windows

Install ZopeSkel and supporting components

This involves downloading and running the Plone Installer for Windows, on which you will base your buildout, and setting up easy_install.

• Download the Windows installer for the latest version of Plone – http://plone.org/products/plone
• Install this to a location on your target machine, e.g., c:\plone3 or d:\plone3. Make sure your installation of Plone doesn’t have any spaces within its folder structure. Therefore, don’t install it        within "Program Files" as the space between ‘Program’ and ‘Files’ will cause problems later on.

Your installation includes the easy_install program, which we will use to install further set-up programs and you may also use when installing python system packages.

• Open up your DOS prompt command line tool, using ‘start’, ‘run’ and typing in ‘cmd’. Type either c: or d: to get you to the correct drive where you have installed Plone.
• Navigate to the new Plone installation directory using the cmd line tool, and type:

Python\Scripts\easy_install.exe -U ZopeSkel

You should see the program downloading and installing components including Cheetah, Paste and ZopeSkel.

Creating a Plone 3 Buildout

Now you have the tools for creating a buildout development environment. Now, let's create a skeleton Plone 3 buildout using paster:

Using a cmd prompt, navigate to your Plone instance home directory which may be c:\Plone3 or d:\Plone3. Now, enter the command:

Python\Scripts\paster create -t plone3_buildout ‘yoursitename’

Replacing ‘yoursitename’ with the name of your project website.

You’ll be asked a number of questions:

1. The path to a Zope 2 installation : Enter "c:\Plone3\Zope" or "d:\Plone3\Zope", adjusting to the path of your Plone installation.
   
2. The path to directory containing Plone products: Leave this blank to let buildout install components under its own control. That way, they'll update when the next 0.0.1 update happens.
3. Admin user name: enter your preferred username here.
4. Password: enter your preferred password here.
5. Port number for running Plone: usually 8080.
6. Debug mode: on or off (use ‘on’ for development)
7. Verbose security: on or off (on if you wish to debug security issues using verbose security’s log files

Bootstrapping the buildout

Now we need to ‘bootstrap’ the buildout. This creates a number of directories, including /bin, /parts, /eggs and /develop-eggs, and the buildout script.

Navigate using cmd to the folder that you’ve just created using the paster command above. This is the root of your buildout instance. Run the following command with the path to the Python installation created by the installer included (typically like d:/Plone/python/python.exe or c:/Plone/python/python.exe):

 d:\Plone\python\python.exe bootstrap.py

where d:/Plone is the root of your Plone install.

Running Buildout

Your command interpreter should still be logged to the root of your buildout installation. Now, let's run buildout:

bin\buildout

Buildout will fetch all the Plone requirements from the Internet, install them, and create control and convenience scripts. Expect it to take a little while.

Installing the Windows service

If you wish to be able to run your new Plone installation as a Windows service, you'll need an extra step. Just issue the command:

bin\instance install

This is useful if you intend to to run your instance in a production type environment. You can then use the services applet to start and stop the services (or set it to run automatically) as well as using the command line. You may use "bin\instance remove" to remove the service.

Running your new Zope/Plone instance

Start your new Zope/Plone instance as a service by navigating to the buildout root, e.g., c:\plone3\mysite and issuing the command:

bin\instance start

Stop the service with a "bin\instance stop" command. Note: currently (17/04/08) there is a bug with the "instance start' command which fails if you have either a theme or a policy package installed. You need to use either of the commands below to run your instance.

Running with "bin\instance console" runs the instance in the fore ground but not in de-bug mode which is faster. Note that if this DOS window is closed the application will close.

The instance can also be started in the foreground by typing "bin\instance fg", which runs the instance in  foreground mode within the DOS command window. If this window is closed, the application will close. Running in the foreground with instance fg automatically starts Zope in debug mode which is very helpful as it provides running de-bug messages.

If your server has started up properly, you will be able to navigate to http://localhost:8080/manage and access your buildout instance with the username and password you chose. Note that you'll need to add a Plone site. Unlike when you initially ran the Windows installer, one won't be created for you.

Further information

For further advice on using buildout to add products or create themes and policies, please consult http://plone.org/documentation/tutorial/buildout/tutorial-all-pages.

Note on adding egg-based products: Using this approach you only be able to use all-python eggs, or ones that have a Win32 binary egg available, due to the lack of a compiler.