All of the scripts are written on the assumption that the
cgi/, lib/, bin/, and
tools/ directories are siblings of one another, so that
scripts can simply refer to, for example, ../lib to get
the libraries.
It is not necessary for any of these directories to be children
of the document root or even of the server root, and in most cases it's
undesirable (since it could reveal things about your site's structure that
an attacker could conceivably exploit). It is necessary to declare
the cgi/ directory a ScriptAlias (in Apache
terminology). In most cases it will not be necessary to directly
customize any of the Combo scripts because they take their parameters and
templates from the site/ directory.
It is also not necessary for any of the code directories to be writable, and again in most cases it's probably not desirable.
The site/ directory is assumed to be a child of the server's
document root; it is meant to contain all of the templates and parameter
files that make your site distinctive. All of the Combo scripts will look
there by default, but your site may differ; the server environment
variable COMBO_SITE_DIR can be set to point things in the
right direction.
A Combo site has two general kinds of information: static and dynamic.
Static information can be maintained ``offsite'' under the control of the
site administrator's favorite version-control system. Dynamic information
is either uploaded to the site by users, created online by forms, or
generated by software (found in Combo's bin/ directory)
running on the server. It may also be under version control, but
in that case the version control will be running on the server.
For various reasons, including the reluctance of mod_dav to
follow symlinks and the fact that most sites' home pages are dynamic, it's
best to put dynamic information in ``real'' directories and use symbolic
links to splice in the static stuff. This also makes it easy to keep
static and dynamic content under separate version control systems (even if
it's only two different CVS repositories).
To give an example of the kind of twisty, oddball configurations that are
possible with Combo, consider the PenguinSong sites PenguinSong.net and PenguinSong.org. Because these sites
share a document root at the moment there are actually two site
directories, called /net/ and /org/, and it's
the virtual hosting that keeps them separate. Even stranger, Combo is a PenguinSong.org project, so it's
perfectly reasonable to eat our own dogfood and symlink Combo straight out
of the project tree. (For obvious security reasons, we'll probably stop
doing that at some point.)
If a site has no dynamic content -- if it's totally non-interactive, in other words -- it's possible to use Combo's crosslinking, formatting, and indexing tools completely offline, treating it as just another part of your webmaster's toolkit. It's also possible to use Combo with a local copy of Apache as a previewer. It should also work with any lightweight miniserver that supports CGI's.