
The Ming Server Installation Guide
==================================
billy-bob@billy-bob-ming.com


The Easy Way
------------

Run the following command from a shell prompt:

	python setup.py install

A user-friendly script will guide you through the installation
procedure, prompting you to choose where you'd like to install
each package component.


The Hard Way
------------

If you don't feel like chatting with the interactive script, you
can just pass the right parameters to the 'install' command above.
The install script expects any of the following --install-x options:

      OPTION        |  DESTINATION PATH FOR:
--------------------|--------------------------------------------------
 --install-lib      |  "TheMingServer" Python package
 --install-scripts  |  the "ming.cgi" script
 --install-data     |  example templates (data directory)
 --install-htdocs   |  example static documents and web resources

If you omit some of them, the relative components will not be installed
(even if the same component was required by the interactive installer).

If you don't set ANY of them, or if you try to use any install
command other than 'install' (ie: 'install-lib'), the installation
script will fall back to interactive mode.


Component Overview and Setup
============================


The 'ming.cgi' Script
---------------------

This is the "executable file" for The Ming Server: any Ming page
can only be accessed through this Python script. Once you have
succesfully installed it to your web server's cgi-bin directory,
open it with a text editor and set the following variables according
to your needs:

SERVER must contain your host address (plus the port number your web server
       is configured to listen to, in case it's not 80);
SITE_DIRECTORY is the path to the data directory (see below);
FILES_DIR is the path to the files directory (a world-readable and writable
          directory in which the server will temporarily store information
		  about requests). This is the only directory where The Ming
		  Server will write any files.  One might point it to a user
		  directory and set a quota;
LOG_DIR is the path to the directory the server will save the logfile to
        (unless logging is disabled).

You should now be able to access any resource inside the data directory you
have specified, by pointing a web browser to an url similar to this:

   [SERVER]/cgi-bin/ming.cgi?page=[RESOURCE]

where RESOURCE is the path to the desired resource, relative to the data
directory.


The Example Templates
---------------------

In order to work, The Ming Server must be provided with a "data directory":
this directory acts as the container for all your Ming site's pages.
The package includes the basic set of resources any site directory
must be filled with (excluding the actual content). In particular, it
contains the following files:

site.html
menu.html
footer.html

These are nothing more than example html templates that you can use for
rendering your site's resources.

Install these files to any directory you like, and don't forget to point
the Ming server to this location (the data directory) as described in the
last section.

Please refer to the online documentation for details about what kind of
content you can populate the data directory with, and about how you can use
the included templates.

Our site, http://billy-bob-ming.com, is a running example of The
Ming Server and its related pieces where you can poke around to
see how it works. Or write us a billy-bob@billy-bob-ming.com and we'll
help you figure it out.


