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


These instructions cover easy_install- as well as buildout-based installation
and example configurations for running Ophelia in an Apache/mod_python setup
and for Ophelia's own wsgiref-based server. Manual installation other than
based on eggs is not described.

See doc/CONFIGURATION.txt for an overview of the configuration options Ophelia
recognizes.


Egg-based
=========

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

- Python 2.4 (not all parts of Zope3 used run with Python 2.5 yet)
- setuptools
- easy_install

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

- Install the bare ophelia egg using easy_install::

      /path/to/python2.4 easy_install "ophelia"

  This will put the ophelia package as well as its dependencies on the Python
  installation's module search path, and install one executable script:

  :ophelia-dump:
      dumps single pages rendered by Ophelia to stdout

- Install Ophelia with its wsgiref-based HTTP server::

      /path/to/python2.4 easy_install "ophelia [wsgiref]"

  The "wsgiref" extra provides another executable script:

  :ophelia-wsgiref:
      wsgiref-based HTTP server running Ophelia' WSGI application


Buildout-based
==============

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

- Python 2.4

Installation steps
------------------

- Create a buildout configuration, e.g. by copying the example configuration::

      cp buildout.cfg.example buildout.cfg

  In buildout.cfg, adjust the host, port, servername, and site settings and
  any other configuration variables. You can also override which buildout
  parts will be created, thus leaving out the mod_python or WSGI installation.

- In the distribution directory, bootstrap the buildout::

      /path/to/python2.4 bootstrap/bootstrap

  You may also customize the buildout configuration to build and use its own
  Python.

- Run the buildout script::

      bin/buildout

- You will now find a number of new executables in the bin/ directory. Among
  them are the two scripts described above, ophelia-dump and ophelia-wsgiref.
  If no buildout parts were removed, the others are:

  :python: a link to the buildout's own Python executable

  :mypython: a script that runs a Python interpreter with a module search path
      that holds all packages used by Ophelia

  :dump: a wrapper script around ophelia-dump that loads the configuration
      specified in buildout.cfg

  :wsgirefsite: a wrapper script that runs ophelia-wsgiref with the
      configuration from buildout.cfg

  :apachesite: the run-control script for the Apache site configured in
      buildout.cfg

  :test: a test runner that finds and runs Ophelia's test suites


Manual mod_python based installation
====================================

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

- Python 2.4
- Apache2
- mod_python 3.3 or better

Installation steps
------------------

- Install the ophelia egg into the Python installation run by the mod_python
  you intend to use::

      $ /path/to/python2.4 /path/to/easy_install "ophelia"

  (If you don't have write access to the Python installation used by
  mod_python, e.g. in a shared hosting environment, you can install the egg
  into another Python 2.4 installation and adjust mod_python's PythonPath in
  your site's Apache configuration.)

- Choose places in the file system to put your site's Ophelia pages and static
  (non-Ophelia) documents, and configure Apache accordingly (see below).

- Cause Apache to reload its configuration.

Example Apache 2 configuration
------------------------------

Assume that the root of your site is published at
``<http://www.example.com/foo/bar/>``.

Assume further that your site uses the following file system locations on a
Unix system:

:/var/example/templates/: for the tree of Ophelia templates
:/var/example/python/:    for the Python packages
:/var/example/static/:    for the static stuff

To publish this site, add the following to your host's config::

    Alias /foo/bar /var/example/static
    <Location "/foo/bar">
        PythonPath "['/var/example/python'] + sys.path"
        PythonOption template_root /var/example/templates
        PythonOption site http://www.example.com/foo/bar/
        PythonFixupHandler ophelia.modpython
    </Location>

This instructs Apache to let Ophelia handle any URI under /foo/bar/. Ophelia
will build pages from templates where they exist, and Apache will serve files
from your static content otherwise.

It is possible to set the Ophelia handler only for directories or HTML
documents by applying some path name heuristics and matching the location
against a regular expression.


Manual wsgiref installation
===========================

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

Install the ophelia egg with the "wsgiref" extra as described above.

Example wsgiref server configuration
------------------------------------

Create a configuration file, say, opheliasite.cfg::

    [DEFAULT]
    host = 127.0.0.1
    port = 8080
    template_root = /var/example/opheliasite
    site = http://localhost:8080/

and run the ophelia-wsgiref script on that file::

    ophelia-wsgiref -c opheliasite.cfg

You may want to wrap this call in a run-control script.

The same configuration can be used with the ophelia-dump script, except that
it doesn't require the host and port to be set.
