
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.

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

To see how a Dulcinea application installation works, please 
download the Toboso (0.3 or newer) and read the installation notes
there.  Toboso exists primarily to serve as an example of a 
Dulcinea application.

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

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 Durus 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 Durus server:

    [catalog]
    scgi-address = localhost:3004
    durus-address = localhost:1975
    http-address = 0:80
    https-address = 0:443
    root-namespace = example.catalog.ui
    root-exports = _q_index catalog

    [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 Durus server will be run listening on port 1975, using the
FileStorage at ``/www/var/catalog.durus``.  An SCGI process will be
started, using the specified publisher class and using
example.catalog.ui as the root namespace for Quixote.



