INSTALL.txt

From PHP-EMS-Tools

This is the basic installation instructions file that is included in the package.

Version 3.0

PHP EMS Tools
Version 3.0 INSTALL.txt
http://www.php-ems-tools.com

$Id: INSTALL.txt,v 1.3 2007/09/28 22:01:10 jantman Exp $

-----------------------------------------------------------------
PHP EMS Tools Installation
-----------------------------------------------------------------

Prior to installation, please review the documentation at
http://www.php-ems-tools.com and in the /docs folder. Please view the
README.txt file. Please also remember to read the LICENSE.txt file - PHP EMS
Tools is licensed under Version *3* of the GNU GPL.
-----------------------------------------------------------------

First, download the package (php-ems-tools-*.tar.gz) and drop it in a
directory that is served by your web server. Un-tar (tar -xzvf
php-ems-tools*.gz) the package. It will create a php-ems-tools directory.

Please note that this package includes its' own versions of HTML_QuickForm,
etc. so it should be ready-to-run out of the box. If you want to use your own
versions, just replace the included ones (files PEAR.php, Common.php, and
directory HTML) with symlinks to your own (assuming that your server/PHP is
told to follow them).

Please be sure to view the online or included docs, paying special attention to the system requirements.

There are two methods of installation - 
1) the install.php script
2) manual installation

install.php makes the following assumptions:
i) You are running in a *nix environment.
ii) You are able to run the script as root in order to create the MySQL
databases.
iii) You have PHP5 available as SAPI_CLI (in other words, you can run PHP
scripts from the command line).

NOTE: install.php is intended to run from the COMMAND LINE. It operates in an
interactive mode and will prompt the user for input. It will *not* run through
a web server. It will *not* run on a Windows or Mac machine. if you're running
one of them, please visit our web site and contact the developer for
assistance - something *will* be coded just for you! That's how nice we are.

APACHE NOTES - Please make sure that your Apache installation is setup to
serve PHP files properly. You can test this by creating a file called test.php
containing just: <?php phpinfo(); ?>
If you can see lots of stuff on this page, it is ok. If not, please be sure
that Apache is loading the php5 module (in a LoadModule directive) and that
there is an AddType directive for php (and that the
application/... cooresponds to a type in mime.types).
**Also please be sure that the DirectoryIndex directive for your root folder includes "index.php".

-----------------------------------------------------------------
1 - Installation using install.php

*In order to edit the config files, you should be roughly familiar with the
 syntax of PHP.

A) Make sure you have uncompressed the archive in a directory under your web
server's root.
B) Get a command line on the machine, as root. You can "su" or use
"sudo". Change into the directory that you extracted the archive in.
C) Open a text editor and edit config/config.php. There are instructions in
the file. You'll have to edit more config files later, but for now, we're only
concerned with config.php. You'll need to set the five variables to their
proper values, and be sure to remember them.
D) run the script with php5, like "php ./install.php" or "php5 ./install.php"
E) Follow the on-screen instructions. You will need to know:
   -The five values you entered in config.php
   -What web server you're running and where the root for documents is (you
   should have extracted the archive here).
   -You'll need to have MySQL installed, and the mysql and mysqladmin programs
   in your path
F) Assmung everything goes well, you'll be able to view the pages in a web
browser. I recommend hacing a GUI-based system to test this on.

-----------------------------------------------------------------
2 - Manual Installation

***This is NOT recommended for novices. You should have already ensured that
   all requirements are met, and that you know what you're doing.

WARNING: The installation script creates a first (administrative/master) user
in the Roster table. If you install manually, you will need to do this
manually as well. You will need to insert a user in the roster table for
yourself. At a minimum, this must include the following fields:
EMTid,LastName,FirstName,password (plain text), rightsLevel (=2), and pwdMD5
(an MD5 hash of your password).

To get an idea of what's going on, it is helpful to look at fileList.txt which
lists all files in the package and what they do.

The manual installation begins with steps A, B, and C as above. Instead of
running the script (install.php) please change to the admin/directory.

D) Create a database in MySQL having the name that you specified in
config/config.php. 

E) Grant privileges on this table for all normal operations (SELECT, etc.) as
well as CREATE TABLE to an anonymous user with no password. Please limit this
to localhost. 

F) run 'php dumpTableSQL.php'. This will show you the SQL that will be used to
create the tables in your new database. If all looks well, then run again and
redirect the output to the correct database, i.e. 'php dumpTableSQL.php >
mysql dbName'

G) Verify that the tables are there by running the MySQL client ('mysql'),
changing to the database ('USE dbName;') and listing the tables ('SHOW
TABLES;'). 

H) Verify creation of new tables. Do this by opening the PHP EMS Tools index
page in a web browser and clicking on "schedule". If you run "SHOW TABLES" in
MySQL again, you should see a pair like "schedule_YYYY_MM_day" and _night.

You should now be finished.

-----------------------------------------------------------------
POST-INSTALLATION:

Once installation is finished, go back and edit the other relevant
configuration files in config/. These files are rigCheckData.php,
rosterConfig.php, and scheduleConfig.php. Instructions are included as
comments in the files. Their names give away which components they are
responsible for.

A side note for the schedule - by default, it displays members using the
"ShownAs" field of the roster. When you add new users, this should be added.
For the administrator that you created during installation (if you used the
script), you will need to go back and edit the ShownAs field (In the Roster
Administrative View) in order for the user to show up on the
schedule. Alternatively, you can run the admin/makeShownAs.php script to fill
in this field for any users that don't have it.

-----------------------------------------------------------------

FINISHING UP:

A) Please take a moment to complete the user survey on
http://www.php-ems-tools.com or at least email jason@php-ems-tools.com with
your comments. This especially goes for people who don't like the software or
feel that something is missing. I *will* code it for you.

B) Please subscribe to our mailing list on SourceForge. The link is on the
homepage (www.php-ems-tools.com). Our "announce" list is the best way to stay
up-to-date on bug fixes, etc. Traffic is *very* light - at the moment, rarely
more than one post per month.

C) If you like the software, please feel free to donate to Midland Park
Volunteer Ambulance Corps. We're a 501(c)(3) non-profit, and the original user
of PHP EMS Tools. Any donations (or letters of thanks) are welcome. The
address is in the README.txt file.
-----------------------------------------------------------------

IN CASE OF PROBLEMS:

Please visit http://www.php-ems-tools.com. This site will have reminders about
all known issues.

If you have problems, please submit a bug using the "Bug Report" link. If you
need installation help, please follow the same link, and under "Category",
select "Support Request". This system will expedite the process of my
analyzing the problem and getting back to you.

If you submit a big report involving problems/errors/etc. please include all
relevant information (operating system and version, PHP version, web server
version, etc.)

-----------------------------------------------------------------

KNOWN ISSUES:
as of version 3.0:

None. However, the system has not been tested on anything other than x86 Linux
and Apache 2.x.