QUOTE
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).
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 Apache MySQL 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 official phpMyAdmin 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".
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.
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".
"My game server is on a remote machine and I want to run stats.pl on the game server."
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).
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.
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.
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).
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 Apache MySQL 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 official phpMyAdmin 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".
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.
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".
"My game server is on a remote machine and I want to run stats.pl on the game server."
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).
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.
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.
