----------------------------------------------------------------------
                               KEYSTONE
                       Installation Documentation
              (c)1999 Dave Belfer-Shevett (shevett@pobox.com)
                        http://www.stonekeep.com
----------------------------------------------------------------------
$Id: INSTALL,v 1.15 2000/12/27 22:15:47 shevett Exp $
----------------------------------------------------------------------

INCLUDED FILES:

	Keystone unpacks (see below) into several directories:

	./keystone		The .php3 files that make up Keystone
	   >-----conf		Configuration files
	   >-----docs		These documents
	   >-----struct		Database structures
	   >-----graphics	Graphics needed for the app
	   >-----support	Various support utilities
	   >-----perl	Perl utilities

PREREQUISITES:

	Before Keystone can be used, several applications must be 
	installed and configured on your server.

	The PHP3 parser, available from www.php.net.  
	A web server, preferably Apache, but keystone can be used
		with others.
	A database server.  At the moment, Keystone has only been
		tested with MySQL, available from www.tcx.se.
	Various n sundry standard Unix support utilities, such as 
		'gunzip'.  (Note that for NT installations, you can use
		'winzip' to unpack '.gz' files.

INSTALLATION

	Keystone is distributed as a single .tar.gz file.  It should be
	unpacked in the directory -above- where it will be run from, since
	it creates it's own directory structure when unpacked.

	1) cd to the directory where your HTML pages for your web server
		reside.

		cd /usr/local/www/data

	2) Unpack the distribution

		gunzip -c keystone-xxx.tar.gz | tar xvf -

		Make sure the directory structure described above is created,
		and all files are dropped in place.  the 'root' Keystone 
		directory should have a bunch of .php3 files, the 'struct'
		directory will have files such as 'slips.mysql', etc.  This
		file (INSTALL) should be in the 'docs' subdirectory.

	3) Copy the 'keystone.conf.default' file to 'keystone.conf'. 
		Edit the file 'keystone.conf', and make any configuration
		changes you want.  This file will hold your localized 
		customizations.  Future upgrades and updates will not 
		overwrite this file.

		You should at least change the default server key in your
		local keystone.conf file.  This key is used to encrypt 
		your login information, and prevent people using
		logins from other systems on your server.

		*IMPORTANT STEP*.  The keystone.conf.default file 
		has the current version number in it.  You should comment
		out this line in the keystone.conf file you use for 
		localization, or else the system wil always report the
		wrong version. 

		Copy the 'colors.conf.default' file to 'colors.conf'. Edit 
		the file 'colors.conf', and make any configuration changes 
		you want. This file will hold your localized color and site
		layout customizations. Future upgrades and updates will not
		overwrite this file.

	4) Create the database within your database server.  Consult
		your database server documentation for the specific 
		procedure for this.  For 'mysql', the command is:
		
		mysqladmin create keystone

	5) Keystone uses approximately a dozen tables for its data.
		Each of these tables needs to be created within the system,
		based on the structures stored in the 'struct' subdirectory.

		These structure files were created using the 'dump' utility
		many Unix SQL servers come with.  To restore a table into
		the server, simply pass the structure file back into the
		command line utility.

		For 'MySQL', the command is:

		mysql keystone < file.mysql

		Do this for all tables for your particular server.  Currently,
		Keystone includes these structure files:

			*.mysql		MySQL (www.tcx.se)
			*.pgsql		PostGres (www.postgresql.org)

		Hint: a shortcut for this can be done in any of the Bourne
		shell derivatives (sh, bash, zsh):

		$ for i in *.mysql ; do mysql keystone < $i; done

	6) Test your login

		Point your web browser at the path you specified, at the
		'index.php3' file.  You should see a login screen.  If
		you do not, or get an error, make sure you have PHP3 
		installed properly.

	7) Login!

		The default login is 'admin', and the password is 'abc123'.

POST INSTALLATION CONFIGURATION

	If you have successfully logged into your system, there's still
	several steps to take to get your system ready for department
	usage.  All these functions may be done through the Maintenance
	menu under Other.  See the user documentation (still under
	construction) for details.

	1) Create user accounts.  
		Every person using the Keystone system requires a unique
		login name and password.  These accounts are created by
		the administrator via the 'Maintenance' functions.  On
		the left side of the screen, select the 'Other' menu,
		then click on "maintenance".  

		From the Maintenance screen, click on 'People'.  A screen
		will come up allowing you to add or modify users in
		the system.  Click 'add' to add a new user.  The fields
		are:

		login		The login ID of the user
		fullname	The users full name. (last,first is best)
		passwd		Encrypted password.  Leave blank for now
		phone		Phone number - freeform
		email		Email address (user@host.com)
		grp		What group the user is part of.  Groups
				can be defined later, the only predefined
				groups are 'tech' and 'admin'. 
		company		A company tag.  Currently for information
				purposes only.

	2) Set user passwords
		The passwords are not maintained in the normal 'people'
		maintenance screen.  Use the 'password' function on the
		Other menu to change passwords.  Users in the 'admin' 
		group may change any users password, while other users 
		may only change their own. 

		After adding all your users in step 1, make sure you go
		through and set their passwords.
	
	3) Assign administrator priveleges, and assign technicians.
		Keystone has the capability of 'granting' administration
		priveleges to a user via the Groups function.  Select
		'groups' from the Maintenance screen.  By default, 
		Keystone has 2 groups defined 'admin' and 'tech', and
		the 'admin' login is a member of both.  Add any other
		users to the groups as necessary.  Usernames go into
		the 'g_people' column, seperated by spaces.

		The 'g_assign' column specifies whether this group
		can be used when assigning slips to certain groups.

	4) Review the Status codes to see if they match your 
		site's requirements.  The 'Status' table contains the
		codes that Keystone uses to tag slips.  The only 
		'required' code is 'C' for Closed.  Any other tags
		may be added here.  There is a default list provided
		in the distribution.

	5) Reset the 'admin' password.  The 'admin' password in the
		keystone distribution is the same for all installs.
		Before making your system publically available, be
		sure to reset the 'admin' password to something
		other than the default.  To do this, make sure you are 
		logged in as 'admin', and use the 'Password' 
		function on the Other menu.  Change the 'Username'
		field to 'admin', and type a new password in.


