Home | About | Download | Docs | Screenshots | Links | Sourceforge | Logo Donate 
to this project

Getting Started

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, if available)
  • 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.

    Configuring MySQL

  • 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.

    Configuring ChartDirector

  • Download and install ChartDirector
  • After installing ChartDirector it is recommended that you replace the library file (chartdir.dll on Windows or on Linux) with the Scratchy-specific version available on the Scratchy download page.

    Configuring GeoIP

  • 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/ file to reflect this location:

    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 Scratchy.

    Modifying your file

    note: You may need to perform the following as root on your Linux-based system
    $ vi /etc/
    --> add a line containing /usr/local/lib
    --> save the file
    $ ldconfig

    Configuring Scratchy

  • 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:
    Parameter Name Notes
    KNOWN_ALIASES Hostnames that your website is known as (such as,, etc)
    DATA_NAME 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 '.')
    MYSQL_USERNAME A valid MySQL username that has permission to create a database (and most other permissions)
    MYSQL_PASSWORD The password associated with the above username
    MYSQL_HOST (default is localhost)
    MYSQL_PORT (default is 3306)
    You may wish to view the complete list of Scratchy configuration parameters.

  • After customizing your config file it is now time to create th MySQL database that Scratchy will use: $ cd scratchy-version/scripts
    $ python -c ../config

    Running Scratchy

    $ cd scratchy-version
    $ python -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)

    Learning more

    Once you have installed, configured and run Scratchy you may wish to read the following documentation for more information:
  • Configuring Scratchy