
Site Management with Dulcinea
=============================

Dulcinea provides a set of tools for running multiple sites on a
single machine in live, staging, and developer modes.  These tools
impose a particular filesystem layout and choice of web server
(Apache); however, their use is optional.  We're releasing them in the
hope that others may find them useful.


File Layout
-----------

All of the code, data, and configuration files live in subdirectories
of a top-level ``/www/`` directory.  Changing the directory used is
not possible, short of doing a search-and-replace over all of the code
and scripts.

The subdirectories of ``/www/`` are:

    * ``/www/bin/``: Contains the Dulcinea scripts, copied from 
      ``dulcinea/bin``.  The most important script is
      ``/www/bin/site``, which starts and stops any number of sites.

    * ``/www/conf/``: Contains configuration files.  The only one
      required by Dulcinea's site utilities is ``/www/conf/site.conf``; 
      the contents of this file will be explained below.

    * ``/www/sites/``: Contains a subdirectory for each site.  The 
      directory name is the same as the site name in ``site.conf``.

    * ``/www/var/``: Contains variable data, most notably the FileStorage
      files used by ZEO servers.


Site Directories
----------------

Each site has a name.  For example, say your server will be running
three applications: a catalog application, a weblog, and a Mailman
server.  You might call these applications "catalog", "log", and
"mail", respectively.  Each of these applications would be on a
different IP address and reachable through different hostnames, e.g.
``catalog.example.com``, ``log.example.com``, and
``mail.example.com``.  You would therefore have the directories
``/www/sites/catalog``, ``/www/sites/log``, and ``/www/sites/mail``.

Each site directory has a number of subdirectories.

    * ``sitedir/bin`` isn't required by Dulcinea, but you can use it 
      for executable scripts relating to the site.  For example,
      if you need to run a script that expires old sessions it
      would go in this directory.

    * ``sitedir/conf`` holds configuration files containing fragments
      that will be included by the Apache configuration file.  For
      example, if there's a file named apache-https.conf in this directory,
      it will be included in the Apache VirtualHost section for the 
      site's SSL side.

    * ``sitedir/doc`` isn't required, but is the conventional place 
      to put the internal documentation explaining how to run the site.

    * ``sitedir/docroot`` contains the static content for the web server,
      such as images and plain HTML files. 

    * ``sitedir/lib`` usually holds the code; your basic objects and
      Quixote user interface can live here.  This is only a
      convention, though; getting that directory on your PYTHONPATH
      is not handled by Dulcinea.


Contents of ``site.conf``
-------------------------

``site.conf`` is the master configuration file, listing the servers to
run, the services needed for each server, and the name of the live
server.  It's parsed by Python's ``ConfigParser`` module, and
therefore uses the same format. 

A default section sets various default values::

    [DEFAULT]
    administrator = webmaster@example.com
    daemon-uid = web
    start-script-directory = /www/bin/
    sites-directory = /www/sites
    conf-directory = /www/conf
    log-directory = /www/log
    var-directory = /www/var
    httpd = /www/httpd/bin/httpd
    zeod = /www/bin/zeod

Here's the stanza for a very simple site::

    [mail]
    http-address = 0:82
    https-address = 0:444
    mode = devel

    [mail livehost]
    mode = live
    servername = mail.example.com

This site is purely static, so it doesn't require a ZEO or SCGI
server.  When you run ``/www/bin/site start`` on the live server
(which must have the hostname 'livehost', in this configuration),
Apache will be run with a virtual host that looks something like
this::

    <VirtualHost mail.example.com>
        ServerName mail.example.com
        DocumentRoot /www/sites/mail/docroot
        Include /www/sites/mail/conf/apache-common.conf
        Include /www/sites/mail/conf/apache-http.conf
    </VirtualHost>

    <VirtualHost mail.example.com:443>
        ServerName mail.example.com
        DocumentRoot /www/sites/mail/docroot
        Include /www/sites/mail/conf/apache-common.conf
        Include /www/sites/mail/conf/apache-https.conf
    </VirtualHost>

The ``Include`` directives are only added when the ``apache-*.conf`` files
actually exist; ``apache-common.conf`` is used for both SSL and
non-SSL servers, ``apache-http.conf`` is used only for non-SSL, and
``apache-https.conf`` is used only for SSL.  You can put redirects and
``mod_rewrite`` rules in ``apache-common.conf`` to apply them to both
virtual hosts.

When you run ``/www/bin/site start`` on any machine other than the
live server, the http-address option is used instead, so you get::

    <VirtualHost 0:82>
       ...
    </VirtualHost>
    <VirtualHost 0:444>
       ...
    </VirtualHost>

The site will there be accessible as port 82 on the machine.  This is
intended for use on developer workstations.  Developers need to be
able to run all of the applications in order to debug them, so you'd
run all three servers and bind them to different ports.

Here's a fancier stanza, for a site that has both a Quixote
application and a ZEO server:

    [catalog]
    scgi-address = localhost:3004
    zeo-address = localhost:1975
    http-address = 0:80
    https-address = 0:443
    root-namespace = example.catalog.ui
    base-module = example.catalog.lib.base
    publisher = example.catalog.ui.lib.publisher.CatalogPublisher

    [catalog staginghost]
    mode = staging
    servername = staging.example.com

    [catalog livehost]
    servername = catalog.example.com

When you run ``/www/bin/site start`` on either a developer or live
machine, a ZEO server will be run listening on port 1975, using the
FileStorage at ``/www/var/catalog.fs``.  An SCGI process will be
started, using the specified publisher class and using
example.catalog.ui as the root namespace for Quixote.



