HOW TO INSTALL THE MKADMIN WEB APPLICATION
==========================================

Make a virtual hostname for the installation and add it to /etc/hosts
	-- for example, x.ussadmin.indexdata.com

Install Apache2, mod-perl and the HTML::Mason module:
$ sudo apt-get install apache2 libapache2-mod-perl2 libhtml-mason-perl

Make an Apache2 configuration file for your server/application,
perhaps by editing a copy of the supplied example configuration,
mkadmin-example.conf

Follow the installation instructions at the top of that file to make
it available to Apache2 (or, if you are running on something other
than a Debian-based GNU/Linux operating system, do whatever the local
equivalent is.)

Point your web-browser at the virtual host you created
	-- for example, http://x.ussadmin.indexdata.com/


TROUBLESHOOTING
===============

Web browser displays "It works!" or something similarly inane

	Several possibilities:
	1. Apache2 configuration fragment has not been installed
	2. Apache2 has not been restarted.
	3. The virtual host is not being picked up -- I saw this when
	   Ubuntu 8.10's Apache2 setup has "NameVirtualHost *:80" but
	   the MKAdmin configuration says "NameVirtualHost *".  I
	   fixed this by changing the Apache2 setup to match what
	   earlier releases did, and modifying sites-available/default
	   accordingly.

Syntax error on line 19 of /etc/apache2/sites-enabled/ussadmin-dev:
Invalid command 'PerlSetEnv', perhaps misspelled or defined by a module not included in the server configuration

	mod_perl2 is not installed.
	# apt-get install libapache2-mod-perl2

Internal Server Error

	Check the error log, probably /var/log/apache2/error.log or
	/var/log/apache2/ussadmin-error.log
	Cases are dealt with separately below.

failed to resolve handler `HTML::Mason::ApacheHandler'

	The HTML::Mason module is not installed.
	# apt-get install libhtml-mason-perl

Error during compilation of /usr/local/src/git/mkadmin/web/htdocs/jump.html:
Attempt to reload Masterkey/Admin.pm aborted.

	This is pretty horrible.  This is how compilation problems
	seems to get diagnosed in some configuration, such as the one
	that comes with Ubuntu 8.10 -- and NOTHING is written to the
	error log.  I saw this, for example, when the problem was that
	I didn't have the Apache2::Cookie module installed.  The fix
	to the Apache2::Cookie problem is to
		apt-get install libapache2-request-perl
	But that alone doesn't make things work if you are also
	missing other modules.

	To get actual error messages at times like this, try running
	../../../bin/mkatest, which merely loads the Admin modules and
	instantiates the class.

Totally blank page returned from Apache2 (nice one, Apache2!) and a
line in the error log saying "/usr/sbin/apache2: symbol lookup error:
/usr/lib/perl5/auto/APR/Request/Apache2/Apache2.so: undefined symbol:
apreq_handle_apache2"
	
	This one is a total bastard.  You need to
		apt-get install libapache2-mod-apreq2
		a2enmod apreq
	How you're supposed to guess this, I can't imagine.  The first
	time I ran into this, it took _a lot_ of fixing.

