------------
Installation
------------

Installation consists of two steps, installing the software, and
configuring it for your deployment.

Prerequisites
-------------

 - Plone 2.5 or above
 - Database Server ( postgresql mysql)

Product Installation
--------------------

The easiest way to install Content Mirror is to download and install
one of our product bundles. You can grab one from here.

http://code.google.com/p/contentmirror/downloads/list

The product bundle is a single Zope 2 Product, containing the required
python eggs/libraries needed to run Content Mirror.

Buildout Installation
---------------------

The ContentMirror product can be installed via buildout by adding it as a 3rd party product
as documented here.

  http://plone.org/documentation/tutorial/buildout/installing-a-third-party-product

for example::

  [productdistros]
  recipe = plone.recipe.distros
  urls = http://contentmirror.googlecode.com/files/ContentMirror-0.4.0-Plone-3.0.tgz

Instance Home Installation
--------------------------

To install manually into an existing plone instance, add extracted ContentMirror product
to the instance's Products directory or any other directory specified as a products
directory in zope.conf.

Database Driver Installation
----------------------------

You'll need the python libraries/extensions for connecting to your
preferred database available from the zope runtime. You don't need the
various zope database adapters products, just the python libraries for
connecting to the external database. Unfortunately configuration of
the various database drivers available is outside of the scope of this
installation guide.  if your on a unix system, and using the system
python, your package management system likely contains suitable
packages for the python database libraries.

Configuring
------------

Before ContentMirror will work, it *must* be configured. Configuration
is done via ZCML ( Zope Configuration Markup Language ). The Content
Mirror product contains a few zcml files in it, that load up the base system, 
as well a sample configuration.

Inside of Content Mirror is a file called settings-example.zcml, you should rename this
file to settings.zcml and make your modifications to it.

The contents of this file are::

  <configure xmlns="http://namespaces.zope.org/zope" 
             xmlns:db="http://namespaces.objectrealms.net/rdb"
	     xmlns:ore="http://namespaces.objectrealms.net/mirror"> 

    <!-- setup a database connection -->
   <db:engine url="postgres://localhost/contentmirror"
             name="mirror-db"
             echo="True"/>

   <!-- If Your Running on Plone 2.5, you must uncomment the following line 
   <include package="ore.contentmirror" file="legacy.zcml"/>
   -->

  </configure>

The db:engine directive is used to specify a database connection, the
syntax used is that of SQLAlchemy's and is well documented there. In
brief the url sytnax is:

   database_driver_name://[user:password@]host[:port_number]/database_name

common database driver names, are mysql, postgres, and sqlite.

The setting-example.zcml uses the db:engine directive to setup a
connection to a postgres database running on localhost with a database
called content mirror. the echo parameter allows specification of
whether statements should be logged to stdout, which is useful for
initial installation and testing purposes. This console output is only
visible if you run zope in the foreground ( ie. runzope, zopectl fg,
or instance fg ).

You should modify the db:engine url to connect to your target database.

If your running on Plone 2.5, you also need to include/uncomment the following
zcml line in settings.zcml::

  <include package="ore.rescueme" file="legacy.zcml"/>

Configuring Custom Types
------------------------
 
If you have custom content types or 3rd party content types your using
your site, you can have them mirrored by adding the following zcml per
custom content class in settings.zcml::

    <ore:mirror content="Products.ATContentTypes.content.document.ATDocument" />

if you need to you can also specify custom serializer and transformer components
to use with your class. Content Mirror already has builtin support for the default 
Plone Content Types. The above zcml line is sufficient for any custom content type
that uses the default archetypes fields types. 

Database Schema Setup
---------------------

Next you'll need to generate the SQL DDL/Schema file for your target
database. Content Mirror provides a script for this purpose. This
script needs to be executed with the Zope environment loaded, in order
to determine which content types are to be mirrored.

if your running in a buildout you can run it like so::

  $ ./bin/instance run parts/productdistros/ContentMirror/ddl.py mysql > mirror.sql
  
if your running Plone directly in a zope instance home setup, you can
do the following::

  $ $INSTANCE_HOME/bin/zopectl run Products/ContentMirror/ddl.py postgres > mirror.sql

the ddl.py script takes one parameter, the name of the target
database to deploy to, names are those available as SQLAlchemy
database driver names ie. ( postgres, mysql, sqlite, etc.)

You should load this file into your target database. ie for mysql::

  $ mysql -u dbowner contentmirror < mirror.sql 

this will connect to the contentmirror database as the dbowner user
and execute the content of mirror.sql, which will create the database
tables needed.

for postgres::

 $ pgsql contentmirror < mirror.sql

Bulk Loading an Existing Site
-----------------------------

If you have an existing site, its often much better to sync the
current state of the portal to the database en mass, rather than wait
for the mirroring process to copy it to the database as content
changes.

Content Mirror provides another script for this purpose, bulk.py.
It takes one argument the path to the portal in the zodb. ie if i had a 
plone site in zope located at /mysite-testing i could invoke the bulk
script on the portal with the following (in a buildout setup)::

  $ ./bin/instance run parts/productdistros/ContentMirror/bulk.py mysite-testing

or in an zope instance home setup with::
 
  $ $INSTANCE_HOME/bin/zopectl run Products/ContentMirror/bulk.py mysite-testing


 


