
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.4 or newer) and read the installation notes
there.  Toboso exists primarily to serve as an example of a 
Dulcinea application.

Contents of ``site_config.py``
-------------------------

``site_config.py`` is the master configuration file, listing the servers to
run, the services needed for each server, and the name of the live
server.  Put it in your site-packages directory or in some other place
so that ``import site_config`` works.

When loaded, the site_config module must have a ``config`` variable mapping
site names to dictionaries containing site-specific values.
Here is an example site_config.py file:

---
toboso=dict(  
  apache_version=2,
  httpd="/sw/sbin/httpd",
  administrator="You <webmaster@example.org>",
  allow_anonymous_registration="True",
  conf_directory="/tmp/toboso/conf",
  var_directory="/tmp/toboso/var",
  log_directory="/tmp/toboso/logs",
  sites_directory="/tmp/toboso/sites",
  start_script_directory="/sw/bin",
  daemon_uid="web",
  servername="127.0.0.1",
  # comment out the next line if apache should not be started.
  http_address="127.0.0.1:8000",
  #https_address="0:443",
  scgi_address="localhost:1984",
  durus_address="localhost:2001",
  root_namespace="toboso.ui.qslash",
  root_exports=['_q_index', 'css', 'user', 'admin', 'login', 'logout', 'my'],
  cache_size=5000)

config={"toboso" : toboso}
---

When you run ``/www/bin/site start``, Apache will be run with a
virtual host, including directives from
/tmp/toboso/sites/toboso/conf/apache-common.conf and
/tmp/toboso/sites/toboso/conf/apache-http.conf files if those files
exist.  If the https_address configuration value is provided, Apache
will also start a virtual host using SSL, including directives from
the /tmp/toboso/sites/toboso/conf/apache-common.conf and
/tmp/toboso/sites/toboso/conf/apache-https.conf files if those files
exist.

The list of configuration variables listed above is not complete, but
all uses of configuration values should be detectable by grepping the
dulcinea/toboso source code for calls to "get_config_value".  In
particular, we run sites in one of three modes: live, staging, or
devel mode.  Certain functionality, mostly having to do with how
site-generated email is directed, depends on the value of the site's
``mode`` configuration variable.  If you need any of this code, or if
you want any of your own code to be similarly controlled, you might
want to add a mode value to your site_config.py.




