Download PsychoStats 3.2

Introduction

There are several ways to install PsychoStats and choosing the correct process depends on a few factors like where your game server and web server are located. A very common setup is to have a game server running on one machine at a game hosting provider and a web server on another machine in a remote location hosted by another company. While this is a very common setup it is also one of the most confusing for new users. This type of setup will be explained in detail after the basic necessities are explained in the following chapters.

This installation guide has been designed as a walk through. Start at the top and work your way all the way down to the bottom. If a chapter discuses something that you do not need simply skip it and move on to the next chapter.

Minimum Requirements

Before you try installing PsychoStats you need to make sure your system meets the minimum requirements as outlined here. Any software or server that is not above the versions shown here are unsupported. How to install this software will be explained in the next couple of chapters.

These requirements are the bare minimum that ensure PsychoStats will work properly on your system. If you attempt to use older versions you run the risk of stats updates crashing or invalid statistics from being recorded. Users having problems with the software that are running older versions of these requirements can not be supported.

Required Server Software

• A Web server (usually Apache or IIS)
• PHP v4.3 or any version higher.
• MySQL v4.1.11 or any version higher.

Windows

• ActivePerl v5.8 or v5.10

Linux

• Perl v5.8+

Required Perl modules

• DBI (v1.4 or higher)
• DBD::mysql (v3.0002 or higher)

Optional Perl modules

• Net::FTP - This is only required if you need to download logs from a remote FTP server (chances are this will be installed by default with your version of Perl).
• Net::SFTP - This is only required if you need to download logs via an SFTP server (secure SSH file transfer protocol).

Optional Perl modules for Heatmaps

These modules are only required if you want to generate Heatmaps for your map statistics.

• GD
• XML::Simple

Installing Perl on Windows

Perl is required in order for PsychoStats to work. If you try to run stats.pl and Perl is not installed on your system then all you'll see is a Notepad window open with the source code of the file. Which is completely useless to you. So read on my fearless readers!

This chapter is for users who wish to run PsychoStats on their Windows machines. If you will be running on a Linux server then you can skip to the next chapter, after all if you're on a Linux server that doesn't have Perl installed then your server has some serious issues and you need take a sledgehammer and 'fix' it.

For users that have a separate game and web server more details on where to install what will be explained later. But for now, the basics of how to get ActivePerl installed will be explained below.

Download ActivePerl

First things first. You need to download a copy of ActivePerl (hint hint! click that link!).

On that download page you'll see a lot of choices to choose from and it can be quite confusing. The Windows downloads are closer to the bottom of the list. The image to the right shows what it might look like. The highlighted entry is the one you want to download if you're running a standard version of Windows. If you're running a 64bit version of Windows, then obviously download the 64bit version of ActivePerl instead.

You want the 'MSI' package shown and not the AS package because the Windows AS package provides NO uninstall functionality, and is recommended only if you are unable to install ActivePerl using the MSI installer.

Install ActivePerl

Double-click the file you downloaded and start the installation for ActivePerl. Installation is easy, just accept all defaults, there isn't much you can customize in the ActiveState installation anyway. After it finishes installing I recommend rebooting your computer once before proceeding. Don't worry, I'll be here.

Now that you have Perl installed you'll need to make sure the required Perl modules are also installed. Lucky for you this is very simple. Read on to the next chapter!

Install Perl modules with the PPM GUI

ActivePerl (as of v5.8) comes with a GUI that allows you to easily search and install modules, as seen to the right. Click on the image to the right to view the full size image. The screenshot has been annotated with numbers depicting the order of what to click to install the modules. If the GUI is not your style, then see the next chapter for details on installing the modules using the command line ppm program that comes with ActivePerl.

Order of steps to perform in the screenshot

1. 1. Select 'uninstalled modules' button
2. 2. Type in the module name
3. 3. Highlight the module to install
4. 4. Select the 'add to install' button
5. 5. And finally, click the 'run' button to have the modules installed.

Install modules from DOS prompt

Even the PPM GUI can be a little confusing to some users, so ActivePerl has an alternate method to install modules from your DOS prompt which is probably even easier than using the GUI. All it takes is a single command for each module.

Go to your "Start" menu on your Taskbar, then click on "Run" and in the run window that opens type in "cmd". This will open an empty DOS window. Now type in the following commands in order:

1. ppm install DBI
2. ppm install DBD-mysql

Example output:

C:\Documents and Settings\Timmy>ppm install DBD-mysql
Downloading DBD-mysql-3.0002...done
Unpacking DBD-mysql-3.0002...done
Generating HTML for DBD-mysql-3.0002...done
Updating files in site area...done
 14 files installed

Your Web Server

In order to view your PsychoStats player web site you'll need a web server capable of displaying the pages. Almost any web server will suffice but it must have PHP v4.3+ (with the MySQL extension enabled). This documentation will not go into detail on how to enable these extensions, the PHP documentation is very detailed, so please visit the links.

If you already have a web host then you're in good shape and chances are your web site already supports PHP and MySQL. If you're not sure you can ask your hosting provider.

If, however, you will be running the web site off of your home machine, or another server that you maintain and it doesn't already have a web server running you will need to install one. Whether you're on Windows or Linux, I highly suggest installing Apache. Using IIS on Windows has a few quirks that cause a lot of problems for PsychoStats working properly on some systems (mainly user permissions that are confusing).

If someone would like to contribute detailed instructions on properly setting up IIS, please feel free to fill out this documentation with the steps required. But please keep the formatting in sync with the rest of the document.

Before you get too deep in how to install Apache on your server there's a better way to handle this. There's a simple way to get Apache, MySQL and PHP all installed with a single click of a button (ok, maybe a few clicks of a button). A premade Windows system that runs Apache, MySQL and PHP is called a WAMP (Windows ApacheMySQL PHP). The wonderful folks over at the wampserver.com (french) web site (english) have pre-packaged up an entire software suite that combines all of the latest software with a single Install Wizard that installs and sets it all up for you.

It even includes a nice little "systray" utility that allows you to manage the various server configurations and enabling extensions w/o modifying any configuration files directly. The Wamp Server also comes packaged with some useful utilities, like phpMyAdmin which allows you to administer your MySQL database from a web interface. And don't worry, The WAMP Server doesn't install any spyware or annoyware :-).

Your Database Server

If you've installed the Wamp Server that was described in the previous chapter, or if your web host already provides access to the MySQL server then you can skip this and move on to the next chapter.

If you did not install the Wamp Server and you do not already have a MySQL database running then you'll need to install MySQL on your web server. This documentation will not go into detail on how to install MySQL from scratch since the MySQL documentation has a great Installation document in place already.

Once you have MySQL up and running you can proceed to the next chapter.

Creating a MySQL user

This chapter is not required for everyone. It depends on how your MySQL server is setup. If you have a web host that provides MySQL access for you chances are they've provided a user and a database already, in which case you can skip ahead to the next chapter. For users that are not sure, then read on.

Note: This chapter is very streamlined, a lot of users will already have MySQL users available and will not have to create a user themselves.

MySQL is a multi-user database that allows a virtually unlimited number of users to connect to it at the same time. Each user has their own privileges to the server, some users will only be able to access certain databases or even certain tables within a database, while other users may have full "root" access to all databases. Users in a virtual hosting environment will most likely have limited user access to a single database provided by the web host.

If you have the proper 'root' access to create a new user it is strongly suggested to add a user just for PsychoStats. This is a security measure so that if the PsychoStats user is ever compromised by a malicious user they would only have access to the PsychoStats database and not other databases that might be on the system.

If you have phpMyAdmin, which comes with the WampServer or can be downloaded from the officialphpMyAdmin website, then follow the steps below to add a user.

• Login to phpMyAdmin and on the main page click on "Privileges" near the bottom. That will show a list of the current users in the database.
• Below the user list click on "Add a new User".
• On the next screen, in the "Login Information", you'll enter a User name and password. Also, you'll notice a field labeled "Host". For the average user you'll want to leave that set to 'Any host'. This will allow PsychoStats to connect with that user from anywhere in the world. If this setting was set to "Local" then the user would only be able to connect to the database if the connection originates from the server itself (so, from your game server which might be next door or 1/2 way around the world, you wouldn't be able to connect to the database).
• Leave the rest of the input fields on this page at their defaults and click on the "Go" button at the bottom. This will add the user and refresh the page. But now there will be more options below for the user.
• In the section "Database-specific privileges" (about 1/2 way down the page) you'll want to enter the name of the database that you'll be using for your PsychoStats installation. Or if you already have a database setup just select it from the pulldown menu then click the "Go" button.
• On the next page select all the check boxes (you can leave the checkboxes in the 'Administration' section blank) that are shown and click "Go".

Creating a MySQL user manually

If you do not have phpMyAdmin or another GUI tool to access the server but you do have access to the standard 'mysql' command line client then you can use the following queries to add a new user to the system. Be sure to change the appropriate with your personal information before issuing the query.

CREATE USER ''@'%' IDENTIFIED BY '

';

GRANT USAGE ON *.* TO ''@'%';

GRANT ALL PRIVILEGES ON ``.* TO ''@'%';

In case line 3 above does not work try the following:

GRANT ALL ON .* TO ''@'%';

Installing PsychoStats (part 1)

Installing the PsychoStats software is very easy, a web based "Install Wizard" will guide you through the steps needed to get the database setup and initial configuration defaults in place. But first you need to put PsychoStats on your web site.

When you unzipped PsychoStats onto your computer it created a directory resembling: psychostats3.0.0 (where 3.0.0 is the current major, minor and revision). Inside that directory will be lots of files and sub-directories with a structure similar to the list below (some optional files and directories have been omitted from this listing).

• PsychoStats3.0.0
  • \lib
  • \upload
  • stats.pl
  • stats.cfg

All of these files make up the required set of files for PsychoStats to work. For now, the directory you're interested in is upload. The upload directory is the entire web front-end for PsychoStats, these files are what allow you to view your stats online. The contents of this directory need to be copied over to your web server. A common place is a sub-directory called stats within your website root directory. Below are examples for Windows and Linux of how you would copy this directory to your web site.

IIS on Windows

If you're running the IIS web server the document root is usually something like: c:\Inetpub\wwwroot. Thats the directory where you want to copy the PsychoStats upload directory into. However, the real directory may be somewhere different for your system and can be found by opening up the Website in your IIS Admin Console and looking at the web site properties. The 'Home Directory' tab will have the path of where your website directory is located.

Step-by-Step

• Browse to the PsychoStats directory from the archive you unzipped.
• Right click on the upload directory and select "Copy".
• Browse to the document root of your website (ie: c:\Inetpub\wwwroot or wherever it it on your system).
• Right click somewhere in the window of that directory and select "Paste". The files should copy over in a few seconds.

You should now have the upload directory copied into your web server document root. You probably don't want that directory to stay with the name of upload. So rename it to something more meaningful like stats. You can right click on the directory and select "Rename" to change the name.

So in the end you should have a directory of something like: c:\Inetpub\wwwroot\stats and in that directory will be all the PHP files and sub-directories that make up the PsychoStats website.

Apache on Linux

Apache is generally the web server of choice for Linux users. The document root of the website can be almost anywhere on the system. Some common locations include: /usr/local/apache/htdocs, /usr/www/htdocs, ~/public_html. Consult your web server configuration or your web host support for information on where your document root is.

To copy the files to your website do this:

First change your directory to where the PsychoStats archive was untar'd. Then do the commands below. Be sure to use real paths to where you want the files copied and not the path shown below.

mkdir /path/to/document/root/stats
cp -rf upload/* /path/to/document/root/stats

Change the stats directory name to whatever you want it to be.

Upload to remote server

If your web server is being hosted somewhere else you'll need to upload the contents of the upload directory to it using your normal FTP client (or SFTP for certain hosts). This is a standard affair and I will not go into detail. If you don't know what FTP is or how to use it, you can ask a friend or seek help in the forums. This documentation is not the place to explain FTP.

Running the Install Wizard

Once you have PsychoStats uploaded to your web server you're ready to run the installation wizard which will complete your Installation of PsychoStats (you'll still need to setup the stats.pl to run, described in the following chapters).

I'll assume you copied or uploaded the PsychoStats upload files to a directory called "stats" on your web server document root. All you have to do now is browse to the /stats/install/index.php URL with your browser pointing to your website. The installation wizard will guide you through the rest of the installation. For example, You might end up browsing to an URL like: http://example.com/stats/install/index.php

That should open the Install Wizard. From here, just follow the directions and answer the questions that it asks you.

IIS and Windows file permissions

If after the installation you browse to your PsychoStats homepage and see only Smarty Error messages, then perform the following tasks:

• Browse to a folder where PsychoStats keeps its compiled templates (Default: ps_themes_compiled)
• Right-click that folder and choose Properties
• Go to the Security tab
• Click the user "Internet Guest Account" (Notice: The user name may be different if you changed your IIS settings)
• Check the box "Allow: Full Control" to assign all needed permissions to that folder for IIS.
• Click Apply and then OK

You can now refresh the PsychoStats page in your browser and finally see it working correctly.

Initial configuration

Once the install is complete you will have a fully functional PsychoStats website on your server. Although, for the moment, it will be empty and not have any players. The first thing you should do is open the Administrator Control Panel (ACP) and look around at the configuration settings. The first thing you need to configure is a valid logsource. A logsource defines where your game server logs are located and how to read them. Without this, you will not have any stats.

See the section on Setting up a logsource for more information.

Installing PsychoStats (part 2)

At this point you should have a fully functional PsychoStats website up and running on your web server. You should be able to browse to the various pages within the stats (but there won't be any players yet) and you should have a logsource configured. And hopefully you've looked at other settings and have tweaked them as needed for your own personal tastes.

Now you need to install the stats.pl portion of PsychoStats onto your machine. The stats.pl (and related files) make up the 'back-end' of PsychoStats. This is the part that actually runs and populates your database with statistics from the game logs. These files can be put almost anywhere, on your web server, the game server, your home machine, or another remote server 1/2 way around the world. A lot of users are confused when they get to this part of the installation. So, to try and make it easier on you follow the questions below and find the question that relates to your setup.

• A user says ...
  • "My game server and web server are on the same machine and are not on my home machine"
    • Answer: Upload the stats.pl, stats.cfg and lib directory to the game server.
  • "My game server and web server are remote but I want to run PsychoStats on my home machine."
  • Answer: Make a copy of the stats.pl, stats.cfg and lib directory on your home computer. Put them into a PsychoStats directory (it doesn't matter where). I suggest something like "c:\psychostats".
  • Answer: Upload the stats.pl, stats.cfg and lib directory to the game server. You will have a home directory, just upload the files into a psychostats directory within your home directory. Do not put the files inside your web site directory (ie: public_html, or cgi-bin).
  • Answer: Upload the stats.pl, stats.cfg and lib directory to the part of the webhost that is not accessible to the web. Usually this is the home directory, just upload the files into a psychostats directory within your home directory. Do not put the files inside your web site directory (ie: public_html, or cgi-bin).
  • "My game server is on a remote machine and I want to run stats.pl on the game server."
  • "My game server and my webhost are on a remote machine and I'm not sure/ don't care where to put stats.pl"

Configure the stats.cfg file

The stats.cfg file is a very small configuration file that simply holds some basic settings on how to connect to your database. All other settings for PsychoStats are stored in the database itself and can be changed by logging into your stats website and going to the ACP.

Make sure you edit the stats.cfg with the proper settings for your database. The table below shows the settings available. Remember, you're configuring these settings based on where your database server is in relation to the stats.pl. So if your database is on another remote machine you'll need to setup the 'dbhost' to point to the remote hostname or IP address.

A common problem with remote databases is improper user permissions that do not allow you to connect to the database. Another common problem is most free web hosting providers will block remote database connections to their servers which make it impossible to run the stats.pl on a different machine.

Setting Default Purpose dbtype mysql Specify the type of DB to use dbhost localhost Hostname or IP of the DB server (localhost for the same machine) dbport   Port for the DB server. Leave blank for server default dbname psychostats Name of the database to use dbuser   Username to connect as. Leave blank for none dbpass   Password for authentication. Leave blank for none dbtblprefix ps_ Prefix to use for all tables related to PsychoStats. ps_ is a good default.

Running PsychoStats

At this point you have run the 'Install Wizard' from your browser and the database is fully setup and you can view your empty player stats online. Now it's time to finally generate some stats!

How to run stats.pl depends on what type of system you are on. We'll step through the various ways below.

Linux SSH Shell

If your host allows SSH connectivity, simply login and change to the psychostats directory where you put the files, then simply run the stats.pl from the prompt:

./stats.pl -v

Note the added command line option '-v'. This enables 'verbose' mode and will cause some extra feedback while the stats are processing. This is recommended the first time you run it so you can see what is happening.

If you have streaming logs enabled, you may want to use screen to start stats.pl, since the process never actually ends and the user may need to log out. Once screen is installed, simply run it with these parameters:

screen -A -m -d -S ScreenName /ps_installation_dir/stats.pl -v &

Notice that you are not actually running a script, so you can run this command from anywhere. You may replace 'ScreenName' by whatever name you want for the screen and make sure that 'ps_installation_dir' is the full path to stats.pl. To resume (or enter) the screen, simply type:

screen -r ScreenName

To exit (or log off) a screen, use the key combination:

Ctrl+a+d

Windows Server

If your running PsychoStats on your home Windows machine or on a remote host that allows remote desktop connectivity, simply open the folder where PsychoStats is. If you have the 'scripts' sub-directory inside your PsychoStats folder go there and double click on 'psychostats.bat'. That will run the stats.pl in 'verbose' mode and will pause the window so it doesn't close immediately. This will allow you to view any errors that may occur.

Alternatively, just double click on the stats.pl icon directly, however you will not see any output and the window will close immediately after stats.pl is finished. This makes it more difficult to see error messages that occur. However, if you suspect there are errors occuring you can view the stats.log file in the directory (if it doesn't exist then no fatal errors occurred).

Automatic Scheduling of PsychoStats

Now that you've run the stats.pl at least once and have confirmed that you are getting statistics on your website you'll most likely want to setup PsychoStats to run automatically. PsychoStats does not have built in functionality to run itself. So in order to do this you need to use either the Windows Task Scheduler, or Linux CRON depending on which system you're running on.

Windows Task Scheduler

The Windows Task Scheduler is very limited but it will at least let you run PsychoStats on a daily basis. This means you can not run hourly updates. There are other software packages out there for Windows that let you schedule jobs more frequently.

You'll find the Windows Scheduler in your Start menu under the following tree: Programs -> Accessories ->System Tools -> Scheduled Tasks

Screenshots will be added later... For now, use your imagination. Add 'perl.exe' as the application to run on a 'daily' basis. At the end of the Schedule Wizard select the checkbox to 'Open advanced properties for this task when I finish'. When that window opens add the path of your stats.pl to the end of the perl.exe thats already present. Then save.

Linux CRON

CRON is very easy to setup, but there are various ways to set it up depending on your hosting provider. For instance, cPanel has a GUI built in that lets you create a cronjob very easily from your web browser, but other systems may have to do it from their shell. Both will be outlined below.

CRON setup via cPanel

cPanel has a GUI to setup CRON as shown in the screenshot to the left. This is a very easy way to schedule PsychoStats to run automatically. Simply view the screenshot as a guide and setup the time of day that you want to run the stats.pl. Most users will schedule the stats.pl to run every hour and that is a decent recommendation to make here. Maps are generally 30-60 minutes long so every hour allows a single map or 2 to be processed at each update. It's entirely up to you how often you want to update. But I do not recommend anything more frequent than 15 minutes. If you try to update too much you'll end up with multiple stats.pl processes trying to update the same files and your stats will break.

Manual CRON setup

Manual cron setup is easy, but requires that you have shell access to your server. This means you must SSH to the server first. From there you can use the 'crontab' command to add an entry to run automatically. When you run 'crontab -e' it will open up your default editor (for most this will be 'vi' or 'nano'). You simply enter a line of text resembling the example below, save the file and exit. The example below shows a cronjob that would run every hour at the top of the hour. Make sure you change the path to where your stats.pl is actually located.

0 * * * * /home/xxxxxxxx/psychostats/stats.pl

Each number or asterix (*) represents a time. There are 5 ways to customize the time when a cronjob will run, outlined below. Some more advanced details have been left out to keep this simple. Search the Internet for more detailed explanations if you need it. For the most part you'll only ever use the first 2 fields in the cronjob entry.

• The first number represents the MINUTE that the cronjob will fire. An * means every minute. Between 0 .. 59
• The second * represents the HOUR that the cronjob will fire. An * means every hour. Between 0 .. 23.
• The third * represents the DAY of the MONTH that the cronjob will fire. An * means every day. Between 1 .. 31.
• The fouth * represents the MONTH that the cronjob will fire. An * means every month. Between 1 .. 12
• The fifth * represents the WEEK day that the cronjob will fire. An * means every day. Between 0 .. 7

So, if you look at our previous example, we said run at minute ZERO, every hour, every day, every month, on each day of the week. So it runs ONCE every hour (since minute 0 will only be true once per hour.

If we wanted to run stats.pl every 30 minutes we could use a slightly more advanced entry:

*/30 * * * * /home/xxxxxxxx/psychostats/stats.pl

or (this would do the same thing):

0,30 * * * * /home/xxxxxxxx/psychostats/stats.pl

All done

Congratulations, You're all done. You should have a fully functional PsychoStats installation that will automatically update itself.