Before you run Scratchy you must install the following required dependenciess:
MySQL client/server v3.23 or greater (v4.x is recommended since Scratchy takes advantage of the new features,
MySQLdb - The python database module for MySQL (obtain the version corresponding to your MySQL version)
Optionally, the following modules are recommended:
ChartDirector - A Python chart generation tool.
ChartDirector Scratchy library - Replaces the ChartDirector trial version yellow banner with a
customized transparent image for the Scratchy project.
GeoIP - C and Python libraries in order to lookup country names for each ip address
Visit the Scratchy links page to obtain any of the above packages.
You must configure a username for Scratchy to use. Please refer to the MySQL user administration guide.
Record the username and password of the newly created MySQL user, you will need to add this information to the
Scratchy config file.
Download and install ChartDirector
After installing ChartDirector it is recommended that you replace the library file (chartdir.dll on Windows
or libchartdir.so on Linux) with the Scratchy-specific version available on the Scratchy download page.
Compile and install the GeoIP C library.
Install the GeoIP Python interface.
Ensure that the C library is in your library path. By default, on Linux, the GeoIP C library is installed in
/usr/local/lib). It may be necessary to modify your LD_LIBRARY_PATH environment or edit /etc/ld.so.conf file to reflect
Modifying your environment
$ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
note: You may wish to add this to your shell profile such that you do not need to enter it each time that you run
Modifying your ld.so.conf file
note: You may need to perform the following as root on your Linux-based system
$ vi /etc/ld.so.conf
--> add a line containing /usr/local/lib
--> save the file
Copy a config.dist file, included in the Scratchy release to a new file, config.
Edit the config file. The config template that is included specifies the most frequently used
Scratchy variables. At the very least you should modify the following values:
You may wish to view the complete list of Scratchy configuration parameters.
Hostnames that your website is known as (such as www.yourwebsite.com, yourwebsite.com, etc)
||The name of the MySQL database to be created. This value is also used when creating reports
for your site. Since this value is used as a MySQL database it should adhere to MySQL database naming rules
(Namely: Any character that is allowed in a directory name, except '/', '\', or '.')
||A valid MySQL username that has permission to create a database (and most other permissions)
||The password associated with the above username
||(default is localhost)
||(default is 3306)
After customizing your config file it is now time to create th MySQL database that Scratchy will use:
$ cd scratchy-version/scripts
$ python create_database.py -c ../config
$ cd scratchy-version
$ python parse.py -c config access_log access_log.1 access_log.2 ... access_log.3
Viewing Scratchy reports
Launch your favorite web browser
Open the index.html file in your Scratchy reports/DATA_NAME subdirectory. (eg. if your DATA_NAME is "test" then
open the file reports/test/index.html)
Once you have installed, configured and run Scratchy you may wish to read the following documentation for more