---------------------------------------------------------------------- KEYSTONE Installation Documentation (c)1999 Dave Belfer-Shevett (shevett@pobox.com) http://www.stonekeep.com ---------------------------------------------------------------------- $Id: INSTALL 2 2003-01-30 02:12:55Z shevett $ ---------------------------------------------------------------------- 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.