Installation of the gpoll program

This page will detail all of the steps needed to get the gpoll program up and running. Make sure that you have followed all the steps from the download, verifying, and unpacking page before proceeding.

Don't worry: although the directions are fairly long and detailed, the actual installation should go quick and easy. There are four basic steps to install gpoll:

• 1. Creating the database and user
• 2. Editing the two scripts
• 3. Creating the tables and images
• 4. Taking it for a test drive

1. Creating the database and user

By default, the scripts use a database named gpoll and a user named gpoll - if you decide to use something else, be sure to change the values when editing the script (the next step). For most database systems, the command to create the database is as simple as
CREATE DATABASE gpoll
- but your system may vary. The command to create a user and set a password is nowhere near as standard, but should be easy to find in your database system's documentation. You are welcome to use an existing database and/or user, but creating separate areas is a good practice.

The next step is editing the two scripts

2. Editing the two scripts

The second step to installing the gpoll program is to edit the two scripts, gpoll and gpolladmin, so that they will work on your system. Although there are many options that can be set inside each one, you will probably only need to change a few.

Before we begin, here is a brief overview of each file:

• gpoll This is the script that users will call through the web. It records votes, and displays results. It is designed to be quick and efficient. If you are using mod_perl it will be very quick and efficient.
• gpolladmin This is the script that is used by the administrator of the polls and does all the work as far as creating and editing polls, viewing statistics, creating and editing images, etc. It is designed to be featureful and complete, and speed was not a design factor. It depends on parts of gpoll, but gpoll does not depend on gpolladmin.

Editing the gpoll script

Everything that you will need to change will be at the top of the script. Scroll down until you see the line

## Begin user-configurable variables.

Each item is commented and should be self-explanatory, but is explained in detail here as a reference.

$GP{SSIPASS}

This is the password needed for SSI access to the script. You must put a password in here before the SSI access will work.

$GP{DBPASS}

This is the password to get inside the database: the default user is named "gpoll." Make user this matches exactly what is set inside the database.

$GP{TITLE}

This is the title that appears above each poll. This will appear above the question for the poll. You may leave this blank, if you wish.

$GP{IMAGEURL}

This is the URL of the directory the images are in. Make sure that this matches the value of $G{IMAGEDIR} inside of the gpolladmin script. The default value is http://$ENV{'SERVER_NAME'}/Pics

$GP{T_TAGD}

This is the default title tag, and specifies what HTML to wrap the value of $GP{TITLE} inside of. It can be left empty, in which case the title will not be displayed. This can be overridden when using SSI.

$GP{Q_TAGD}

This is the default HTML tag to wrap around the question. This can be overwritten when using SSI.

$GP{DBTYPE}

This indicates the type of database you are using. Valid choices are: postgres, mysql, oracle, or sybase. Please make sure that they are entered in lowercase, exactly as they appear here.

$GP{DBSUBS}

This indicates whether or not the database can do subselects. Currently, every database except mysql can. If you are using a version of mysql that can handle subselect, you can change this value.

$GP{DBLOCKS}

This indicates whether or not the database can create exclusive locks. Again, only mysql cannot do so.

$GP{DBNAME}

This is the name of the database. The default is "gpoll" but you are free to use whatever you want, as long as you have a place to create the four tables and two indexes that gpoll uses.

$GP{DBPORT}

This is the port that the database uses. When in doubt, you can usually just remove the whole ";port=$DP{DBPORT}" section from the connect string later on, and the driver will find the correct port.

$GP{DBUSER}

This is the user that will connect to the database. This goes with the $GP{DBPASS} setting above. The default is (you guessed it) "gpoll."

$GP{POLLTABLE}

This is the name of the table that holds information about each poll. The default value of gpoll_polls should be fine.

$GP{VOTETABLE}

This is the name of the table that holds the votes for each poll. The default value of gpoll_votes should be fine.

$GP{LOGTABLE}

This is the name of the table that holds the error logging. The default value of gpoll_logging should be fine.

$GP{SLEEP}

When someone attempts some trickery (such as ballot stuffing), the script will try to defend against this by sleeping for a certain amount of time. This value is how long to initially sleep for: the default value is "1.5" seconds.

$GP{DEEPSLEEP}

This is how much to increase the sleep time by (in seconds) every time an additional "attack" is detected. The default value is two tenths of a second (0.2).

$GP{VIEWRESULT}

This is the text that is shown in the "view results" link, which allows people to see the poll results without first voting. "View results" is the default value.

$GP{SLEEPMAX}

This specifies the maximum sleep time (in seconds) that can be reached by a combination of the previous two variables. We want to set a maximum because at some point it will not matter anymore and something else (the webserver, their browser, etc.) will start timing out. The default value is 60 seconds.

$GP{VOTEBUTTON}

This is the text that appears on the voting buttons. It should be kept short to keep the polls looking good. "Cast your vote" is the default value.

$GP{SHOWCLOSEDATE}

This is the text that appears when the closing date is displayed on polls. The actual date will follow immediately after this value. "This poll closes:" is the default value.

$GP{NOCLOSEDATE}

This is the text that appears when the closing date is displayed on polls, but no closing date has been set.
Important: This value is passed directly into a SQL statement, so make sure you escape it as needed (e.g. single quotes). "No closing date has been set" is the default value.

$GP{NOPOLLVOTE}

This is the message that appears when somebody tries to vote, but does not indicate which poll. This is only likely to happen if someone is trying to break the system on purpose. Sorry, but you must vote for a specific poll is the default value.

$GP{NOPOLLVOTE}

This is the message that appears when someone tries to view a poll, but the results are not allowed to be seen. The poll results are not visible" is the default value.

$GP{NOTVALIDPOLL}

This is the message a user will see if they give a poll number that does not exist. Sorry, that is not a valid poll is the default value.

$GP{NOVOTECLOSED}

This is the message users receive when they try to vote on a poll that has been marked as closed for voting. Note that this is not the same as closing a poll because of the closing date. "Sorry, this poll is closed for voting" is the default value.

$GP{NOVOTECOOKIE}

This is the message the user will receive when they try to vote, but they have a cookie in place that indicates they have already voted in this poll. The poll (without a voting form) appears below the message. "Sorry, you may only vote once" is the default value.

$GP{NOVOTEIP}

This is the message the user will receive when they try to vote, but the database already has an entry from their IP address, within the time frame specified. The poll (without a voting form) appears below the message. "Sorry, you may only vote once." is the default value.

$GP{NOVIEW}

This is the message the user will see if the poll is marked as not viewable. "Sorry, but this poll is not viewable." is the default value.

$GP{POLLCLOSED}

This is the message the user will see if the poll has passed its closing date. The actual date will appear immediately after this, and will look something like this: "Sun, Apr 1, 2001"; the string "Sorry, but this poll closed on " is the default value.

$GP{INVALIDVOTE}

This is the message the user will see if they try to vote with an invalid value - in other words, if there are only four choices in the poll and they try to pick number 7. You can view these events (and others like it) in the security section of gpolladmin. "Sorry, that is not a valid vote for this poll." is the default value.

$GP{GOODVOTE}

If the vote was successful, this message will appear at the top of the screen, and the poll will be redisplayed below it. "Thank you! Your vote has been recorded!" is the default value.

$GP{COMMA}

This indicates two things: whether or not we should add commas to numbers (6,023,042 vs. 6023042) and what format the comma should take: some parts of the world use a period instead of a dash to break apart a number. The default is a single comma.

$GP{DECIMAL}

Those same places that use periods in their numbers also use commas to separate the fractional part of numbers. Leave this blank for the default behavior of your perl system (most likely a period) or set it with a comma if you used a period in the previous value.

$GP{COOKIENAME}

This is the name of the cookie that is set when someone has voted and cookies are enabled for that poll. The default value is gpollvoted.

$GP{COOKIEDOMAIN}

This is the name of the domain that the cookie is set for. It is very unlikely that you need to use anything other than the default value, which is $ENV{'SERVER_NAME'}

$GP{COOKIEPATH}

This is the path that is set inside the cookie. The default value of a single forward slash should be fine in most cases.

$GP{COOKIELIFE}

This is how many days until the cookie expires. Set this longer than you think the poll will last. The default value is 360, or just under a year, and should be plenty.

$GP{ALTCHAR}

This is the character to use inside the "alt" tags for the bars in the polls. This is what the "bars" will be made of for non-graphical browsers such as lynx. The default value of an asterick ("*") is an excellent choice for this.

$GP{SHADEHEIGHT}=5;

This is the default height in pixels of the shade bar that helps give the polls a three dimensional effect. It is not recommended that you go below the default value of 5 pixels, nor above 10.

$GP{OFFSET}=10;

This is the "minimum" pixels that each image bar will have, which allows small numbers (and zeroes) to show up when the poll also contains large values. The default is 10 pixels.

Everything past this point in the file should not need to be changed. You can now save the file and move on to the gpolladmin script.

Editing the gpolladmin script

Everything that you will need to change will be at the top of the script. Scroll down until you see the line

## Begin user-configurable variables.

Each item is commented and should be self-explanatory, but is explained in detail here as a reference. Unlike gpoll, there are only a few items here:

$G{USERNAME}

This is the username needed to enter gpolladmin through the web form.

$G{PASSWORD}

This is the password needed to enter gpolladmin.

$G{COOKIENAME}

This is the name of the cookie that is set for gpolladmin access. The default value is "gpolladmin"

$G{COOKIEDOMAIN}

This is the domain name set for the cookie. The default value of $ENV{'SERVER_NAME'} should work for most cases.

$G{COOKIEPATH}

This is the path that the cookie will use. A single forward slash should work just fine.

$G{COOKIELIFE}

This is how many days before the cookie expires. Set this to 0 for maximum security, and the cookie will only last as long as the browser is open, and will not be saved to your hard drive.

$G{POPHELP}

This indicates whether you would like the help system to create a new window when the help links are clicked on within gpolladmin. The default is to not do this.

$IMAGEDIR

This is the directory where the images are located on the server. It should match the value of '$GP{IMAGEURL}' inside the gpoll script. The default value is the Pics directory, located off the main directory for the server. In other words, $ENV{DOCUMENT_ROOT}/Pics. Make sure that this directory exists and is writeable by the process running the web server.

$HELPDIR

This is the location of the help files: feel free to set these wherever you want. The default is to put them into the directory set by $gpoll::GP{IMAGEURL}, which is where the images are stored. Now would be a good time to move all the html files that came with the distribution into this directory if they are not already there.

That is all for gpolladmin. Save the changes: it is now time to run the scripts.

Getting the scripts to run

The next step is to install the scripts on the server. Detailed instructions on how to do this depend on your server, but in general you will want to put them into the proper directory (usually "cgi-bin" or "perl"), set the permissions so that they are executable by the process running the web server (usually "nobody", "apache", or "www"). Make sure the path to the perl executable is correct: the default is "/usr/bin/perl" which should be fine for most unix-like systems.

The next step is to call up gpolladmin through the web. If it works correctly, you should see a simple login page asking for a name and password. If that page does not appear, you will have to troubleshoot the script. Make sure the script will run from the command line. Doublecheck the permissions on the script. Check the error log for the webserver to learn more about the error. Once you have the form displayed, enter the username and password you set inside the gpolladmin script, and a cookie will be set allowing you to go inside gpolladmin.

Next, you should see the main menu for gpolladmin appear at the top of the screen, which has links to the six main sections of gpolladmin: Images, New Poll, Edit Poll, Statistics, Security, and Help. The first time you log in, you should see a message indicating that the tables could not be found. This brings us to the next step, creating the tables and images.

3. Creating the tables and images

Once the gpolladmin script is up and running, you need to create the tables and images. There are two ways to do this: automatically and manually. When you first log in to gpolladmin, it should detect that the tables are not yet created, and offer to do it for you. If all goes well, it will not only create the tables, but create all the images for you as well. If this works, you can jump ahead to the final step, the test drive. If the tables were successfully created, but not the images, then jump ahead to the create images manually section.

Creating the tables manually.

The tables may not have been created automatically. This is usually because the database account you are using is not allowed to create the tables. The SQL you need to create the tables (and indexes) should appear on the webpage when you first log in. You can also generate the SQL by running gpolladmin from the command line with a -dumpsql argument. Either way, you will need to manually run this SQL inside the proper database. Instructions on doing so depend on your database, but the easiest way is to simply use the command-line tool that comes with each database. PostgreSQL uses psql, mysql uses mysql, Oracle uses sqlplus, and Sybase uses isql. Once you have the tables created, gpolladmin should detect this and offer to create the images for you. If it cannot do so, you will have to create them manually:

Creating the images manually.

A standard set of very small gif images is used by gpoll to create the colored bars used for the polls. Although you can add your own images later, these images must be created for the program to work. The program will try to create these in the directory "Pics" off of the main directory, or whatever you have set the $G{IMAGEDIR} variable to.

To add the images manually, you can run gpolladmin form the command line. Make sure that the tables have already been created inside of the database. Now, simply run gpolladmin with a argument of -makeimages dirname, where "dirname" is the name of the directory in which you wish to place the images. 139 small gifs will be created in this directory, and information about them will be entered into the database as well. Make sure that the permissions and ownership are changed if needed.

You should now be ready for the final step, taking it for a test drive.

4. The Test Drive

Once the scripts have been edited and uploaded, the database and tables have been created, and the images have been written, you should be ready to start creating polls. Take the program for a test drive by creating a new poll - this will also allow you to test out the gpoll script.

Once you have a poll created, play around with all the parameters. Trying adding your own images, and creating your own gif. Flip a poll from horizontal to vertical. Give it some funky colors. Run it as an SSI. Try and cheat by voting more than once. Send me some feedback and let me know if it works, what database you are using, and anything else you want fixed, added, or just need to say. Enjoy!