############################################################################################ #                                                                                           #  Project           : USD eVoter                                                           #  File name         : INSTALL                                                              #                           
#                                                                 
#  eMail             : evoter@mail.com                                                      #                
#  Purpose           : INSTALLATION         
#
#  Developers	     : Courtney, D. Kitt, D. O'Dwyer, J. 
#  Sponsor			 : University of San Diego, CA, USA
#  Licence			 : GPL
#  
#  Copyright (C) 2001, USD eVoter. All Rights Reserved.
#                                                                                                              
############################################################################################                

##############
Introduction:
##############

Note: Please read the LICENSE file included in the distribution to get the license
      this program is subject to.

eVoter has been designed to setup a simple and secure online voting booth on your server. eVoter's primary intention is to facilitate secure online voting for students voting in student government elections. The intuitive structure of eVoter easily allows you to setup, administer, conduct and view polls in a quick and simplified manner. 

To see this script in action, you can browse the following websites:
- http://evoter.sourceforge.net
- http://scweb.sandiego.edu/~elections

###########
Requires:
###########

- PHP v3.x OR above
- mySQL 
- Apache


############
Changelog:
############
 
1.00   	(YET/TO/DECIDE): 	First public release.

##############
Installation:
##############

- unzip the distribution file into your http documents directory.

- create the mysql database  

- create the mysql tables.  


##########################
Setting Up The Database:
##########################

The database used in eVoter is MySQL v3.23 and the table structure looks something like below. The SQL file to import is located in the admin directory of eVoter (file: 'elections.sql'). To import this into your database type the following fromthe command line:

./mysql -u<your_mysql_user> -p<your_mysql_pass> elections < elections.sql

NOTE: Please note the '(' ')' brackets are not part of the command AND als

+---------------------+
| Tables_in_elections |
+---------------------+
| AUTH                |
| BALLOTS             |
| CANDIDATES          |
| POSITIONS           |
| VOTES               |
+---------------------+

Sample of tables in eVoter | AUTH:

+--------+-------------+----------+--------+--------+---------+
| AUTHID | RANDOM      | USERNAME | TOKEN3 | TOKEN4 | ACL     |
+--------+-------------+----------+--------+--------+---------+
|      1 |     141237  | odwyer   | 123    | 123    | 0,1,2,3 |
|      2 |     3257682 | useroy   | 1278   | 4235   | 0,1,2,3 |
|      3 |     4232123 | guest    | 123    | 123    | 0,1,2   |
+--------+-------------+----------+--------+--------+---------+

Sample of tables in eVoter | BALLOTS:

+----------+--------------------+--------+
| BALLOTID | BALLOTNAME         | ACTIVE |
+----------+--------------------+--------+
|        1 | AS Elections       | 1      |
|        2 | Sophmore Elections | 0      |
+----------+--------------------+--------+

Sample of tables in eVoter | CANDIDATES:

+-------------+------------+----------+-----------+
| CANDIDATEID | POSITIONID | LASTNAME | FIRSTNAME |
+-------------+------------+----------+-----------+
|           1 |          2 | Doe      | John      |
|           2 |          1 | Caesar   | Julius    |
|         	3 |          3 | Sinatra  | Frank     |
|           4 |          4 | Clapton  | Eric      |
|           5 |          4 | Jagger   | Mick      |
+-------------+------------+----------+-----------+

Sample of tables in eVoter | POSITIONS:

NOTE ON ACL: ACL is the Access Control List. In eVoter we use 0, 1, 2 and 3 to reference the following: 
0 = Freshmen	
1 = Sophmore
2 = Jumior
3 = Senior
So, a POSITION with an ACL such as '0,1,2,3' means that everybody is eligibel to vote, and an a POSITION with an ACL of 
'0,1' means that a Freshman and a Sophmore are eligible to vote. 


+------------+----------+-------------------------+-------------------------------+---------+-------------+
| POSITIONID | BALLOTID | DESCRIPTION             | NAME                          | ACL     | NUM_CHOICES |
+------------+----------+-------------------------+-------------------------------+---------+-------------+
|          1 |        1 | Executive Board         | President                     | 0,1,2,3 | 1           |
|          2 |        1 | Executive Board         | VP of Academics               | 0,1,2,3 | 2           |
|          3 |        1 | Executive Board         | VP of Programming             | 0,1,2,3 | 2           |
|          4 |        1 | Executive Board         | VP of Finance                 | 0,1,2,3 | 2           |
|          5 |        1 | Executive Board         | VP of Multicultural Relations | 0,1,2,3 | 2           |
|          6 |        1 | Executive Board         | Secretary of Athletics        | 0,1,2,3 | 2           |
|          7 |        1 | Executive Board         | Secretary of Student Orgs     | 0,1,2,3 | 2           |
|          8 |        1 | Freshmen Class Senators | Freshmen Senator              | 0       | 2           |
|          9 |        1 | Sophmore Class Senators | Sophmore Senator              | 1       | 2           |
|          10|        1 | Junior Class Senators   | Junior Senator                | 2       | 2           |
|          11|        1 | Senior Class Senators   | Senior Senator                | 3       | 2           |
+------------+----------+-------------------------+-------------------------------+---------+-------------+


Sample of tables in eVoter | VOTES:

+--------+-------------+------------+----------------+--------+----------------+
| VOTEID | CANDIDATEID | POSITIONID | TIMESTAMP      | TOKEN3 | IPNUMBER       |
+--------+-------------+------------+----------------+--------+----------------+
|      1 |           9 |          3 | 20010905110254 | 123    | 199.106.15.158 |
|      2 |           8 |          3 | 20010905110254 | 123    | 199.106.15.158 |
|      3 |          23 |          2 | 20010905110254 | 123    | 199.106.15.158 |
+--------+-------------+------------+----------------+--------+----------------+




######################
PHP Files in eVoter :
######################

NOTE: A more comprehensive desription (for those interested :) is located at 'How.txt'

1) Login.php
This is the main file in eVoter.

2) Admin.php
Looks after the insertion, deletion, and editing of Positions and Candidates for each Ballot created.

3) Config.php
The configuration file is a 'one-stop' information point for the deployment of eVoter. Global variables located here
include: $host (e.g. localhost), $username (username of database being used, MySQL in this case), $password (the 
database password), $token3 (this can be any extra form of security you wish for e.g. we have used the students college 
ID number). $token4 (as for token3, we have opted for SSN). It should be noted here that variables $token3 and $token4 
are optional security measures. If you would only like to authenticate your users by username(eMail handle) and password
(eMail password) then leave token 3 and token4 blank. Example: $token3=""; $token4"";

4) Voted.php
This file is called after a user has logged in successfully and voted.  

5) Viewvotes.php
This file tallies the votes for a particular Ballot giving percentages and totals of votes casted.


####################
Support & Comments:
####################

In making eVoter as robust and useful as possible we would appreciate any comments, help or advice. Please send an eMail
to evoter@mail.com 


####################
Upgrade:
TBD

####################


####################
Future Features:
TBD

####################


__________________________________________________________________________________________
 
Copyright (C) 2001 USD eVoter By Courtney, Kitt, O'Dwyer for the University of San Diego.
All Rights Reserved.
