Plone/Zope Admin

Adding a New Zope Instance using Buildout

NOTE: It is usually NOT necessary to create a new zope instance for each new plone site.  A single zope instance can host many independent plone sites (see below for details on adding a new plone site to an existing zope instance). Reasons for adding a new zope instance might inlcude the need for a "development" instance for testing sites and products, the need for a different version of plone or other products to acheive a certain functionality not possible on existing zope instances, or the need to set up a special instance for a specific partner or user to access and administer.

Currently Zope instances are set up and managed using buildout. The "buildout" is a directory containing all the parts that make up a project, including a Zope instance, the Plone sources, custom configuration options, and your our project's source code. Create one like this:

Log in to the webserver via ssh and switch user to "zope"

su zope

Change to the webapps directory in the zope home directory:

cd ~/webapps

Then proceed to install the buildout.  The following example installs a plone 3 recipe.  Modify "zopeinstance" with whatever you want to name the instance and it's home directory.

paster create -t plone3_buildout zopeinstance

This will ask a series of questions. If you want to use an existing installation of Zope rather than have buildout download and compile one for you, specify an absolute path as the zope2_install. Similarly, if you do not want buildout to download the core Plone products, you can point it to an existing directory containing all the products (it will still download Plone 3's eggs, but as we will see later, it is possible to share an eggs directory among multiple buildouts). You will need to enter a Zope administrator username and password, and you may want to turn debug mode and verbose security on during development.

Now, enter the newly created zopeinstance directory, and run the buildout bootstrap script.  NOTE: Python 2.4 is currently required to Plone 3.x:

cd zopeinstance
python2.4 bootstrap.py

This will create a number of directories and scripts and download the latest version of the zc.buildout egg. This step should be needed only once.

A file called buildout.cfg is also created.  This files specifies versions and products to be downlaoded and installed in the Zope/Plone instance.  You can get a head start on setting up the instance by modifying a buildout.cfg from another zope instance.  Click here for tips on using buildout and an example buildout.cfg

Once you have adjusted the buildout.cfg, run buildout:

./bin/buildout

This reads the generated buildout.cfg file and executes its various "parts", setting up Zope, creating a Zope instance, downloading and installing Plone. We will explain this file in more detail shortly.

You will need to run ./bin/buildout again each time you change buildout.cfg. If you do not want buildout to go online and look for updated versions of eggs or download other archives, you can run it in non-updating, offline mode, with;

./bin/buildout -No

To start Zope in the foreground, run:

./bin/instance fg

If there are no errors, you may start zope as a background process:

./bin/instance start

Related commands:

./bin/instance stop
./bin/instance restart

Once your zope instance process is running, you can start adding plone sites, building and administering web applications by accessing the web based "ZMI".  ZMI stands for Zope Managment Interface and it is normally accessible via the web at the port which zope is using, for example: http://halliance.org:8080

NOTE: Zope ports like 8080 might not be web accessible due to firewall settings.  In this case, specify an alternate URL to access the ZMI as described below.

Specifying a URL for the ZMI

(ZMI stands for Zope Managment Interface and it must be accessible in order to administer zope instance and add plone sites.  Typically it is available at the port which zope is using, but that port may not be web accessible depending upon firewall settings.)

• Make sure you have registered a Domain name and pointed to the DNS of choice. 
• Make sure your DNS is configured to point the domain and subdomains to the hosted server.
• Make sure you have added the root domain as a virtual host on the server using virtualmin. This ensures appropriate DNS routing. You can log in to virtualmin here: https://halliance.org:10000
• Open the Apache namedvirtualhost.conf file here: Webmin >> Servers >> Apache Webserver >> Global configuration >> Edit Config Files >> Select namedvirtualhost.conf and click Edit button.
• Add an entry to the namedvirtualhost.conf file following template provided below, adjusting the bits in bold italics.  These settings override any virtualmin settings you might have for the domain. The namedvirtualhost.conf
  

<VirtualHost 196.0.27.12:80>
ServerName zmi.halliance.org
ServerAlias admin.halliance.org

ProxyPass / http://localhost:8080/VirtualHostBase/http/zmi.halliance.org:80/VirtualHostRoot/
ProxyPassReverse / http://localhost:8080/VirtualHostBase/http/zmi.halliance.org:80/VirtualHostRoot/

</VirtualHost>

• Save and restart Apache using using the "apply changes" link in the upper right hand corner of the Apache admin screen
  
• Test the domain.  You should be able to view the ZMI at the url you have specified.

Once you have created a zope instance:

• you can add any number of independent plone sites to it, and assign unique URLs for them. (See below.)
  
• For production sites you will want to make sure that the instance is automatically started if shut off or if the server is restarted. (See below.)
• You will want to configure backups as the zope instances are not automatically backed up by virtualmin.
  

Adding a Plone Site to an Existing Zope Instance

 Steps:

• Log in to the Zope Management Interface (ZMI).  The URL should be something like http://zmi.halliance.org
• make sure you are in the root of your zope instance, and "select type to add..." choosing "Plone Site". 
  
• Fill in the required details and remember the site ID, for instance it might be something like "health3"
• Upon saving, a Plone site will be created and can be viewed in the root of your Zope instance 
  
• The frontend of the Plone site is immediately accessible at http://zmi.halliance.org/health3.  
• You will next want to specify a unique URL for your plone site in the same way you did for the ZMI.  See below.
  

Specifying a URL for a Plone Site

• Make sure you have registered a Domain name and pointed to the DNS of choice. 
• Make sure your DNS is configured to point the domain and subdomains to the hosted server.
• Make sure you have added the root domain as a virtual host on the server using virtualmin. This ensures appropriate DNS routing. You can log in to virtualmin here: https://halliance.org:10000
• Open the Apache namedvirtualhost.conf file here: Webmin >> Servers >> Apache Webserver >> Global configuration >> Edit Config Files >> and select namedvirtualhost.conf and click the Edit button.
  
• Add an entry to the namedvirtualhost.conf file following template provided below, adjusting the bits in bold italics.  note that you must specify the These settings override any virtualmin settings you might have for the domain.
  

<VirtualHost 196.0.27.12:80>
ServerName halliance.org
ServerAlias www.halliance.org

ProxyPass / http://localhost:8080/VirtualHostBase/http/halliance.org:80/health3/VirtualHostRoot/
ProxyPassReverse / http://localhost:8080/VirtualHostBase/http/halliance.org:80/health3/VirtualHostRoot/

</VirtualHost>

Configuring a New Plone Site

Mail

Plone can use Google Apps as an SMTP server to send email. 

• SMPT server: smpt.gmail.com
• SMTP port: 587
• username: full email address of a dedicated mail account
• password: account password
• secure connection: TLS enabled

Alternatively, Plone can use the SMPT setting for the MUSPH mailserver.

• SMPT server: mail.musph.ac.ug
• SMTP port: 25
• username: full email address of a dedicated mail account
• password: account password
• secure connection: TLS enabled

Caching

TBD

Autostarting Zope

For production sites you will want to make sure that the instance is automatically started if shut off or if the server is restarted.

Create a shell script which runs the "./instance start" and call it something descriptive like startzopehalliance.sh .  Example script (the second line is to start a squid cache if you have one installed):

#!/bin/bash

/home/zope/webapps/musphplone3/bin/instance start
sleep 5
/home/zope/webapps/musphplone3/bin/squid-instance

Store the script in a sensible location like: /home/zope

set it to executable and test it

and add it to the crontab using virtualmin or nano to be run periodically

Backing up Zope

You will want to configure backups as the zope instances are not automatically backed up by virtualmin.

You could schedule a backup of the entire instance folder, but this may be resource intensive and require too much space.  At least the following files and directories in the instance home should be backed up: 

1. var/filestorage (contains the main data.fs database file and any data/files stored on the filesystem)
2. products (contains products you may have added which are not specified in buildout.cfg)
3. buildout.cfg (this recipe for your zope instance can be re-run with buildout to recreate the environment)

With this minimum set of files you should be able to recreate your zope instance including all products and save all of your site data and configuration work.

Steps:

• Adjust the paths in the following, focusing on the bits in bold italics.
  

#create the tar archive

tar czf /home/backups/zope/zopeinstance_`date '+%m-%d-%Y'`.tar.gz /home/zope/webapps/zopeinstance/var/filestorage /home/zope/webapps/zopeinstance/products /home/zope/webapps/zopeinstance/buildout.cfg

#find and delete archives older than 22 days

find /home/backups/zope -name 'zopeinstance_*.tar.gz' -mtime +22 -delete

• Add the lines to the end of the /home/backups/zope_backup.sh script. 
  

This zope_backup.sh script is currently set to run as a cron job every Sunday.  It creates a tar archive of the specified directories and files, date stamps the name and saves the archive in /home/backups/zope/ .  The script specifies the deletion of the weekly backup snapshot after 22 days.  If you want to save a particular snapshot from being deleted, simply move or copy it to a different directory.  or, you could add a prefix such as "save_" to the filename. 

There are other ways to do backups and this is very simple procedure. It could be improved.

Moving Zope and Plone Sites

TBD

Plone Development Best Practices

• Use the absolute minimum number of plone products to get the job done. 
  
• Be careful installing plone products; always read the documentation, check the version compatibility and ensure ability to uninstall
• Ideally it is best to separate "development" and "production" zope instances.  This is relatively easy to do when using buildout.
•