----------------------------------------------------------------------
                               KEYSTONE
                         Upgrade Documentation
          (c)2000 Dave Belfer-Shevett (shevett@stonekeep.com)
                        http://www.stonekeep.com
----------------------------------------------------------------------
$Id: UPGRADE,v 1.1 2000/01/18 14:56:17 shevett Exp $
----------------------------------------------------------------------

INTRODUCTION
	This document describes the basic procedure on upgrading an
	existing Keystone installation to a new version.  Note this
	is a set of guidelines only, and is not intended to be 
	the perfect reference for all possible situations that
	may arise during upgrade.

	Having said that...

	This assumes that you have a running Keystone system 
	installed, and are familiar with the basic setup of
	the system.  If this is not the case, you should read
	through the INSTALL document to get familiar with how
	Keystone operates.

CHOOSING YOUR UPGRADE

	You have 2 possibilties to choose from when upgrading
	an existing installation.  One is downloading the latest
	released version, the other is updating via CVS.  

	The advantage of working from released versions is you 
	can be pretty sure the code you're working with is clean
	and works. 

	The disadvantage is you may not have the most recent
	patches and fixes.

	The advantage of working with CVS updates is you have the
	latest changes, with the latest updates.

	The disadvantage is you may take an update while the system
	is unstable.  Stonekeep is fairly careful to keep things
	stable while doing development, but occasionally things break.

STEP 1 - Preparing for the Upgrade 

	Make a BACKUP of your existing databases and system.  The
	best way to do backups is to run the 'dumptables.pl' script
	in the support directory.  This will make mysql dumps of
	all your database tables, which can be restored later.

	Make a backup of your Keystone installation.  Use the unix
	'tar' utility or the like:

		$ cd /usr/local/apache/keystone
		$ tar cvf ~/keystonebackup.tar .

STEP 2 - Download and install the software

	For releases, get the latest .tar.gz file from www.stonekeep.com
	(this will be 'keystone-0.60.08.tar.gz' or something similar).

	If you are installing a release, simply untar the new version
	of Keystone over the old one.  (if you've modified any of your
	Keystone sources, you should be aware this will overwrite them.
	It will _NOT_ overwrite your database tables or any configuration
	changes you've made in keystone.conf, as long as you've followed
	the directions regarding keystone.conf and keystone.conf.default.

		$ gunzip keystone-0.60.08.tar
		$ cd /usr/local/apache/keystone
		$ tar xvf ~/keystone-0.60.08.tar

	If you are installing a CVS update, simply follow the directions
	on the download page for Keystone at www.stonekeep.com.  If you
	have a previously installed version of Keystone that was not
	sourced from CVS, you'll probabyl need to do a scratch install
	via CVS - make sure you make a copy of your keystone.conf file.

	If you are installing a CVS update, simply follow the directions
	on the download page for Keystone at www.stonekeep.com.  If you
	have a previously installed version of Keystone that was not
	sourced from CVS, you'll probabyl need to do a scratch install
	via CVS - make sure you make a copy of your keystone.conf file.

STEP 3 - Bring your database structures up to date

	As of 0.60.08, there is a utility included in Keystone
	called 'schecker' which will help you bring your database
	tables up to the latest revision.  This utility will _ONLY_
	work for MySQL installations.  Postgres support is coming

	To run schecker, point your web browser at the file 'schecker.php3'
	in your keystone installation directory, and follow the
	instructions on the screen.  schecker should, after it checks
	your structures, tell you what needs to be updated or altered
	in your mysql tables.

	If you're running a system other than MySQL, you'll have to
	do the structure checks by hand.  Use whatever utility your
	database supports to display the structure of the table installed,
	and compare that against the files in the keystone/struct
	directory appropriate for your database.  (.pgsql files are for
	PostGres, .oracle are for Oracle, etc).  Make any changes to
	your local database installation that are needed.

STEP 4 - Review keystone.conf.default 
	
	Thumb though 'keystone.conf.default' in the 'conf' directory
	and see if there are any new options you'd like to work with.
	DO NOT EDIT THIS FILE!!!  Copy the options you want to work with
	into your local 'keystone.conf' file, and manipulate them 
	there.  keystone.conf.default is only for default values, and
	will get overwritten during updates!

STEP 5 - Log in and enjoy!
