Installation Guide - Step by step

The README.1ST file (if one existed) of CATS. This document walks through the steps that must be taken in order to get up and running with this script. Defines required elements and provides links to additional resources.

Introduction

This document will attempt to walk you through the simplest process of getting set up to use CATS.  If you're familiar with your web server settings and credentials, everything can be accomplished in about 10-20 minutes.

CATS is not a straight 'out-of-the-box' plug-and-play kind of script but don't let that scare you off.  In 90% of cases, the script will work with most of the default settings.  For the remaining 10%, it requires *some* manual setup (which is outlined in detail below).  Once things are set up, upgrading to newer versions of the script is plug-and-play.

Before you get to that point though, you'll need to jump through a few hoops first, so read on.

Prerequisites

CATS makes use of PHP, which is open-source, free to download, and come at no cost (for personal use).  Since PHP runs on a variety of operating systems (including Windows and Linux), CATS can be used in any environment that runs PHP scripts (although more testing has been done on Windows and Linux boxes).

Before you go any further, you'll need to make sure that the web server you host your site from has PHP installed.  Nowadays, most do.  If you're unsure of what's installed on your server, contact your web host provider as they'll be able provide you with this information. 

No PHP, no CATS.  My suggestion to those in this situation is to:

1. Ask your web host provider to install the service (at no cost to you) or,
2. Look for a new web host provider that has PHP installed already (most do).

If you don't currently have web hosting or are looking to move your site to one that does supply PHP, there are hundreds out there that meet this prerequisite.  One such host is hostgator.com.  At the time of this writing, their basic hosting package (baby croc) is fairly affordable  (~$10/mo) and their support (IM based) is quite good (I personally used their services in the past).  See their website for the current state of their server setups and current pricing.

Additionally (this is not a prerequisite), the ability to create sub domains is recommended (it makes things a little easier to manage).  Again, if you're unsure about your server capabilities, contact your web host provider.

Download the latest distribution

Once you've confirmed that your web server meets the prerequisites listed above, you can download the current release from the files area.  Save this file to your drive and extract the contents to a temporary folder for now (you'll move the files into your site later).

Rename your index.html (or .htm)

If you currently have a file named index.html or index.htm in your web site root folder (and you most likely will if your site is operational ), you'll want to rename that file to something else of your own choosing.  I've named my index files to home.shtml.  The reasons are two-fold:

1. As to not overwrite your file with the one included in the CATS distribution, and
2. To have your web server use the redirecting index.html.

The index.html file that comes in the CATS distribution is a basic redirection page that refers your visitors browsers to the CATS script.

Special note for Apache users

This note applies to those that are running on an Apache server and have the ability to edit the httpd.conf file.

In lieu of using a index.* file, you can add 'cats.php' to the Apache's DirectoryIndex directive in which case, in the absence of an index file, Apache will automatically run the cats.php script without having to call it.  Just make sure that the CATS script is located in the location that you make the call to.  For more complete information on this directive, take a look at the Apache's DirectoryIndex documentation.

Copy the script files

Once you've extracted the contents of the distribution, there are a couple of files that you'll want to place into the root (or roots of each subdomain) of your website.  They are:

1. cats.php
   The script
2. cats.ini
   Configuration settings file for the cats.php script
3. index.html, index.htm
   Basic HTML redirect page to 'cats.php'

Update cats.ini with your defaults

The main purpose of the cats.ini file is to act as the holder of default settings for the (sub)domain for which it is located.  Here you'll define the default parameters that the script will use.  This way, instead of having to type them in on every URL, the script will automatically use the parameters defined in the ini if that parameter is omitted in the URL.  That's right...you can *override* the default values by simply supplying the parameter in the URL call.  Depending on what you want your defaults to be will directly control what the output of CATS will be so feel free to experiment with different values and see what you can create.

Post the files

Once you have the cats.ini and db_credentials.php files updated to suit your site needs, you will need to post them to your web site.  All the files listed will need to be placed into the root of your web site (the first folder from which you serve out your web pages):

1. cats.php
2. cats.ini
3. index.html
4. index.htm

These files do not require any special permissions

Test the install

Once the files are posted, you'll want to make sure that everything is working.  Open your browser and type in your web address.  If everything is set up correctly, your server should send the index.html or index.htm (depending on your HTTPD settings) file first.  This page will cause the browser to redirect into the CATS script from which all your future navigational calls will be made.

If you find that you are getting bad results, no data, etc, use the &debug=y parameter to get more information about what is going on in the background.   This will help you locate most, if not all, of the problems that are happening by having the script output what it's trying to do.

You may find that you might have to play around with the cats.ini files before you get the perfect page back but ultimately you should be able to get back what you want.

Suggested reading

If you haven't already looked at it, take a look in the Script Parameters - A to Z.  This document contains all the various options that can be utilized in you CATS calls that will help to minimize your site maintenance or will help to speed up your page returns along with suggesting some more advanced options that you can use in your implementation.