==================
Installing modzope
==================

Requirements
------------

  * Zope X3.1 and a suitable version of Python (2.3.5 or 2.4.x)

  * Apache 2.0.xx

  * mod_python 3.1.x or higher


Installing the prerequisites
----------------------------

* Apache

  mod_python starts Python interpreters within the Apache 2 server
  process.  The way modzope's configuration is set by default, only
  one interpreter is started for the whole site and Zope 3 is loaded
  into it.  Apache has different multi-process approaches, on Unix
  being ``prefork`` the default.  This MPM (multi-process module)
  forks new processes for incoming requests.  This is not a
  preferrable model for running modzope, though, because each spawned
  process requires a new Python interpreter into which Zope 3 has to
  be loaded from scratch each time the process is forked.  Loading
  Zope 3 takes time, therefore you'd really only like to do this once
  when you start Apache.

  The solution is to use an MPM that doesn't spawn over processes but
  spreads the work among *threads*.  Multiple threads within one
  process can share the same interpreter.  The MPM that does this on
  Unix is called the ``worker MPM``.  It is therefore recommended to
  compile Apache 2 with this MPM (or on Debian, for instance, you can
  just install it from the corresponding package).

* mod_python

  If you're using mod_python 3.1.4 or lower, it is recommended that
  you apply `a patch`_ that fixes a memory leak problem with named
  Python interpreters and multithreaded MPMs.

.. _`worker MPM`: http://httpd.apache.org/docs-2.0/mod/worker.html
.. _`a patch`: phttp://www.dscpl.com.au/projects/vampire/source/patches/mod_python.c.diff


Installing modzope
------------------

First, create a regular Zope 3 instance using the ``mkinstance``
script.  Then install modzope into that instance through the regular
distutils routine::

  $ python setup.py install.py --home $INSTANCE

where $INSTANCE is your Zope 3 instance directory.  This will copy the
``modzope`` and ``wsgiref`` packages to the instance's ``lib/python``
directory.  Alternatively, you can specify any other installation path
or even none (in which case both packages will be installed in the
interpreter's ``site-packages`` location), as long as you make sure
that this path is inside the Apache interpreter's search path (see
``apache2.conf``).

Like the regular Zope instance, modzope also has a configuration file
(``modzope.conf``) that doesn't include any server settings, though.
Its main purpose is the ZODB configuration.  You can either use the
existing ``zope.conf`` and strip any server and logging configuration
from it, or use the skeleton ``modzope.conf`` file from the modzope
distribution (in the ``democonf`` directory).

At last, Apache needs to be configured to handle all requests for a
certain VirtualHost (or all hosts, for that matter) through modzope.
The ``democonf`` directory contains an skeleton configuration file
that can be included in a VirtualHost section of the Apache config
file.  Copy this file to a sensible place (your Apache ``conf``
directory or your instance's ``etc`` directory) and adjust the
PythonPath statement according to your setup.  Last, include the file
in your Apache configuration with the include statement::

  Include "path/to/apache2.conf"


Running Apache
--------------

For startup, modzope needs to know where ``modzope.conf`` is located.
Since there's no way for modzope to read the Apache configuration upon
startup (stupid, isn't it?), this option cannot be specified in the
Apache configuration, but must be passed as an environment variable,
``MODZOPE_CONF``.  This environment variable needs to be set for the
Apache process and must contain the full and absolute path of the
``modzope.conf`` file you wish to use.