============
Installation
============

Installation of Singing & Dancing uses buildout_.  If you don't know
what buildout is or `how to create a buildout`_, `follow this
tutorial`_ first.

These instructions assume that you already have a Plone 3.x buildout
that's built and ready to run.

Singing & Dancing is available as `Python eggs on PyPI`_.

To install Singing & Dancing, add it to your buildout by following
these steps:

1) Edit your ``buildout.cfg`` file and look for the ``[buildout]``
   section.  Add an ``extends =`` option in that section like the
   following::

     [buildout]
     extends = https://svn.plone.org/svn/collective/collective.dancing/buildout-extends/0.8.10.cfg
     parts =
         zope2
         ...
         ...

   Should you already have an ``extends =`` line, add the new line at
   the end of the other extends files.  For Plone 3.2.2, your
   ``[buildout]`` section might start like this::

     [buildout]
     extends =
         http://dist.plone.org/release/3.2.2/versions.cfg
         https://svn.plone.org/svn/collective/collective.dancing/buildout-extends/0.8.7.cfg
     parts =
         zope2
         ...
         ...

2) Next, you'll need to add ``collective.dancing`` to the ``eggs`` and
   ``zcml`` options in your ``[instance]`` section.  Which should then
   look like this::

     [instance]
     ...
     eggs =
         ${buildout:eggs}
         ...
         collective.dancing
     zcml =
         ...
         collective.dancing

3) Remove all ``additional-fake-eggs`` and ``skip-fake-eggs`` options
   from your ``[zope2]`` section, if any.  (This is so you don't
   overrride the ones defined in the S&D extends file that we added in
   step 1.)

Processing the message queue
----------------------------

One important thing to note is that S&D usually queues messages in its
own message queue before sending them out.  You might have noticed
that when you send out a newsletter, S&D tells you that it queued the
messages.

In a production setup, you would normally process the message queue
periodically using the built-in Zope ClockServer_.  While you're
testing, you can visit the *Statistics* screen in the S&D advanced
configuration panel and manually clear the queues.  If your mail
configuration in Plone is set up correctly, you should be sending mail
out now.

To set up ClockServer to trigger the processing automatically for you,
add this stanza to the Zope 2 ``[instance]`` section of your buildout
configuration and rerun ``bin/buildout -v``::

  zope-conf-additional = 
      <clock-server>
        # plonesite is your plone path
        method /plonesite/@@dancing.utils/tick_and_dispatch
        period 300
        user admin
        password admin
        # You need your *real* host here
        host www.mysite.com 
      </clock-server>
      
Or, if your site is behind Apache using a Virtual Host, 
the zope.conf clock server configuration would be ::

  zope-conf-additional = 
      <clock-server>
        # plonesite is your plone path
        # www.mysite.com your site url
        method /VirtualHostBase/http/www.mysite.com:80/plonesite/VirtualHostRoot/@@dancing.utils/tick_and_dispatch
        period 300
        user admin
        password admin
      </clock-server>

This will process the message queue every five minutes.  It assumes
that your Plone site's ID is ``portal``, that your username and
password are ``admin``, and that your site is called
``www.mysite.com``.

**Note**: You must not set up this ClockServer on more than one
instance.  The processing makes sure it's not invoked twice at the
same time by using file locking.  This file locking won't work if you
configure the clock server on two different servers.

Once you're done editing your buildout configuration, don't forget to
run your buildout again before you start up Zope::

  $ ./bin/buildout -v

That's it!  You can now start up your Zope instance, and then install
Singing & Dancing in your Plone site by visiting the *Add-on Products*
site control panel.

Configuring zope.sendmail to send out messages
----------------------------------------------

Singing & Dancing uses `zope.sendmail`_ to send out its mail.  S&D
comes with a default configuration for ``zope.sendmail`` in its
``collective/dancing/mail.zcml`` file.  This configuration will read
SMTP parameters from your Plone site.

Be warned however, that this default configuration is not suitable for
high-volume newsletters.  The aforementioned configuration file
contains an example configuration using ``mail:queuedDelivery`` that
works much more reliably when dealing with a large number of mails.

Troubleshooting
---------------

Should the above instructions not work for you, :ref:`contact-us`.

**NOTE**: If you're upgrading your buildout from an older version
where you included version dependencies of S&D by hand, remove the
``develop-eggs`` directory inside your buildout and re-run buildout.

Here's a list of the most common stumbling blocks:

   - `ValueError: too many values to unpack <https://bugs.launchpad.net/singing-dancing/+bug/253377>`_

   - `Products/Five/i18n.zcml uses namespace package in configure package directive <https://bugs.launchpad.net/zope2/+bug/228254>`_

   - Should you see ``ImportError: Module
     zope.app.component.metaconfigure has no global defaultLayer``
     when starting up, make sure you have
     ``plone.recipe.zope2install`` >= 2.2.  You may use buildout's
     ``versions`` feature to tell it which version to use.

.. _buildout: http://pypi.python.org/pypi/zc.buildout
.. _how to create a buildout: http://plone.org/documentation/tutorial/buildout/creating-a-buildout-for-your-project
.. _follow this tutorial: http://plone.org/documentation/tutorial/buildout
.. _Python eggs on PyPI: http://pypi.python.org/pypi/collective.dancing
.. _ClockServer: http://plope.com/software/ClockServer/
.. _zope.sendmail: http://pypi.python.org/pypi/zope.sendmail