shrum.net :: Code :: CATS :: Installation Guide - Step by step
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.
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
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.
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:
- Ask your web host provider to install the service (at no cost to you) or,
- 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
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
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:
- As to not overwrite your file with the one included in the CATS distribution, and
- 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
Configuration settings file for
the cats.php script
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):
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
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.
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.