Table of Contents

License Agreement

Program Credits
Software Manual
Software Installation & Upgrade
 This software package is installable on all Linux, Unix, Mac OS X (BSD Unix) and Windows platforms running Perl 5 or higher. It is assumed that before the installation process can begin, your will have an account on a web server, and will have a domain name or IP Address to access their web site. The software package has been fully tested under RedHat Linux, FreeBSD, Sun Solaris, Cobalt RAQ, Mac OS X and Microsoft Windows 2000. Nearly all operating systems capable of running Perl 5 that are equipped with a web server should be able to run this package without difficulty.

The webserver must allow for the execution of web based scripts and recognize '.cgi' as a valid mime type. In addition, the ability to change permissions on files and directories is needed. Windows installations require the presence of ActiveState Perl on the server.

Upgrade Information

If you are upgrading from a previous version, please read this section. The software upgrade works in the following manner:
  1. Install this version following these instructions as if it were a new install. Do not overwrite your previous installation. Most users find it easiest to place the installation directories from this version next to those of the previous version. If you are doing an upgrade, follow installation steps 1-8.

  2. Once you have completed the installation instructions, access the administrator utility's Software Upgrade function and choose to upgrade your software. The upgrade basically copies all of the important data and files from your older version to the new one.

  3. When the upgrade process has completed, you will have two running versions of the software on your server. Fully test the new version and when you are satisfied that everything meets your expectations and has been configured properly, delete the previous installation from your server and change any links in your static HTML pages that pointed to the old version to point to the new one.

  4. As an alternative to changing links in your static HTML pages that pointed to the old version to point to the new one, you can rename the directory or directories that the new installation is located in to match the location(s) of the old installation. If you choose to do this, make sure that you also update your paths & URLs in the modified files in the cgi-bin directory, and change any URLs and cookie settings in the administrator utility under the Global Settings | Manage Program Settings appropriately. This method is recommended if any search engines have indexed the old installation, or if you have a large number of HTML pages linking to the software.
Installation File Formats

The software package installation files are available in two different archive formats: .tar.gz and .zip. These three versions cover nearly all types of installations. The versions and their application are: .tar.gz file, which is for installations on a Linux or Unix server that has telnet or SSH enabled the programs 'tar' and 'gzip', and .zip file for installations where only FTP access to the server is available.

STEP 1: Getting the files to your server

A note about the root web directory on your server: The root web directory on your server is the directory where your web pages are served from. Common names for this directory are: www, web, httpdocs, htdocs, html. You will need to know which directory your root web directory is to complete this installation. The instructions presented below assume the name 'www' for this directory.

If you are using a .tar.gz installation file, login to your site via FTP, browse to your root web directory, and upload the .tar.gz installation file. Next, login to your site via SSH or telnet and cd to your root web directory, then extract the contents of the installation file. This is done using the following commands: 
cd /home/your_account/www
tar -xzpf ccp51.tar.gz
If you are using a .zip installation file, first unzip the file on your local computer using a utility like WinZip. Then, login to your site via FTP, browse to your root web directory, and upload all of the directories and files that were unzipped into that directory.

It is important for FTP installations to ensure that files are uploaded in the proper format. All .gif files in the /ccp51/media/images directory should be uploaded in BINARY format. All .csv files in the /ccp51/data/tables directory should be uploaded in BINARY format as well. All other files, which have the extensions .htm, .txt, .pm, .js, .cgi and .pl, need to be uploaded in ASCII mode. If your images are uploaded in the wrong format, they will appear corrupted. If your .csv files are uploaded in ASCII format, you will see script execution errors when accessing the program scripts.

When the files have been placed on your server, the directory and file structure should match the structure on your local computer.

For both .tar.gz and .zip installation methoids, once you have completed this step, you should have a single folder in your root web directory that contains all of the program's directories and files.

STEP 2: Placing Directories In the Proper Place On The Server

For some installations, particularly those on Unix or Linux servers running Apache webserver where the configuration is set up to allow you to execute scripts from anywhere on your site, you will not have to move directories around to get the program working. If this is your case, you can skip to the next step.

If you have a pre-existing 'cgi-bin' directory on your server already, chances are that the program's scripts will need to be moved into that directory. Pre-existing cgi-bin directories are usually found outside of the root web directory, however they can appear in this directory as well. You will basically want to move the installation directory /ccp51/cgi-bin to the pre-exisiting /cgi-bin directory. When you move it, change the name of that directory to 'ccp51' so that you end up with a directory in your /cgi-bin named 'ccp51'. An illustration is below: 
/home/your_account/www/ccp51/cgi-bin -> /home/your_account/cgi-bin/ccp51
Protecting the files in the /ccp51/data directory is of the highest importance. If you will be running this package on an Apache webserver with .htaccess file protection enabled, you can leave the /ccp51/data directory in the web accessible /ccp51 directory. .htaccess files are provided with the directory to ensure browsing via the web will not be allowed.

If you are installating on a Windows server, or are not running Apache webserver, the /ccp51/data directory must be stored in a non-web accessible portion of your account. On Windows webservers running IIS, there is usually a directory set asside for this named '_private'. You may choose to create a non-web accessible directory and place the /ccp51/data directory there, or you choose to password protect the /ccp51/data directory in it's currently place to secure the data. Assuming you need to move the /ccp51/data directory to a non-web accessible portion of your site, move the installation directory /ccp51/data to a newly created (or pre-existing) directory outside of the root web directory. An illustration is below: 
/home/your_account/www/ccp51/data -> /home/your_account/data/ccp51
STEP 3: Settings Permissions On The Directories And Files

Now that the directories are in their proper place, the next step is to set permissions on them. If you used the .tar.gz file installation method, extracting the file on the server via SSH or telnet, your permissions are set already, so you can skip this step.

You basically want the files in the /ccp51/cgi-bin directory to be executable and the files in the /ccp51/data and /ccp51/media directories to be writable. If you had to change the location of any of these directories above, please note that you permissions changes would be made in the new location of that particular directory. Permissions should be set as follows: 
Directory           Linux/Unix    Windows

/ccp51/cgi-bin      chmod 755     Executable
/ccp51/media        chmod 777     Full Control For Everyone
/ccp51/data         chmod 777     Full Control For Everyone
The permissions levels shown are for *every file and every directory* within the directory listed above. Using the /ccp51/data directory as an example, make sure that all files and all directories within that /ccp51/data directory are writable.

For installations on Unix or Linux servers, you can set permissions on each file/directory using your FTP client's CHMOD function.

For installations on Windows servers, you will need to contact your server's administrator and ask them to change the permissions on the directories for you. Be sure to tell them that this change needs to be made using Windows Explorer, not the IIS control panel and needs to be made to both the /ccp51/media and /_private/ccp51 (change paths to match yours) directories. If you need to send a message to your Windows server administrator, do not continue with the installation until you have received a message from them indicating the permissions changes have been made.

STEP 4: Updating the Paths & URLs in the Executable Files

You now need to edit the path and URL information in the cgi scripts to ensure that the server and URL paths used by the program are correct. If you are installing on a Linux or Unix server, you should edit the files in the /ccp51/cgi-bin directory with the extension .cgi. If you are installing on a Windows server, you should edit the files in the /ccp51/cgi-bin directory with the extension .pl. If you are installing on a Linux or Unix server, you should delete the .pl files in the /ccp51/cgi-bin directory (they are not used). The inverse is true if you are installing on a Windows server.

There are several paths that need to be entered in each of the two scripts in the /ccp51/cgi-bin. The scripts are: 
Name                   Script

cp-app.cgi   or .pl    Online Site & Store
cp-admin.cgi or .pl    Administrator Utility
The paths that need to be entered in each of these scripts are:

Server Script Path ($server_script_path)
This is the full server path to the /ccp51/cgi-bin directory on your server. On Linux or Unix systems this would be entered as '/home/your_account/www/ccp51/cgi-bin' or something similar. On Windows systems this would be entered as 'C:/inetpub/account_name/www/cgi-bin/ccp51' or something similar. Do not include a trailing slash.

Server Data Path ($server_data_path)
This is the full server path to the /ccp51/data directory on your server. On Linux or Unix systems this would be entered as '/home/your_account/www/ccp51/data' or something similar. On Windows systems this would be entered as 'C:/inetpub/account_name/data/ccp51' or something similar. Do not include a trailing slash.

Server Media Path ($server_media_path)
This is the full server path to the /ccp51/media directory on your server. On Linux or Unix systems this would be entered as '/home/your_account/www/ccp51/media' or something similar. On Windows systems this would be entered as 'C:/inetpub/account_name/www/ccp51/media' or something similar. Do not include a trailing slash.

URL Script Path ($url_script_path)
This is the URL for the /ccp51/cgi-bin directory on your server. This typically would be entered as 'http://www.yourdomain.com/ccp51/cgi-bin'. Do not include a trailing slash.

URL Media Path ($url_media_path)
This is the URL for the /ccp51/media directory on your server. This typically would be entered as 'http://www.yourdomain.com/ccp51/media'. Do not include a trailing slash.

The cp-admin.cgi (or .pl) script has two additional URLs that need to be set. These point to the main site script and it's /ccp51/media directory.

Site Script URL ($site_script_url)
This is the URL to the cp-app.cgi (or .pl) script. It should be the same as what was entered in the main site script as the Server Script Path ($server_script_path), with the addition of '/cp-app.cgi' or '/cp-app.pl' on the end.

Site Media URL ($site_media_url)
This is the URL to the /ccp51/media directory for the main site script. It should be the same as what was entered in the main site script as the Server Media Path ($server_media_path).

If you will be using an offline credit card processing method, it is highly recommended that you run the Administrator utility under SSL. To do so, instead of entering 'http://' URLs for the URL Script Path ($url_script_path) and URL Media Path ($url_media_path) variables, enter your 'https://' URLs. This will force the Administrator utility to run completely under SSL and will provide you a secure method to work with card number decryption online. If you are unsure of what your SSL URL is, check with your host.

STEP 5: Password Protecting The Downloads Directory

If you will be selling downloadable items, or using the Administrator utility's accounting file export functions, you will need to password protect the /ccp51/media/downloads directory. If you are not selling downloadable items and will not be using the Administrator utility's accounting file export functions, you can skip this step.

If you are installing on a Unix or Linux server running Apache, this can be done with .htaccess and .htpasswd files. In order to do this properly, you should use whatever tool your hosting provider has available to password protect the directory. For most Unix or Linux servers, your control panel should have a function for this. If you are installing on a Windows server, you will most likely have to contact your Windows server administrator and ask them to password protect that directory for you.

STEP 6: Editing The HTML Files

If in STEP 2 above, you had to move the /ccp51/cgi-bin directory to a different location, you should edit the .htm files in the /ccp51 and /ccp51/admin directories to point to the proper location for the scripts. These .htm files contain redirect code in them so that you can access the .cgi or .pl scripts with short URLs. If you do edit these files, you will be able to access the program scripts in the following manner: 
Script                   URL

Online Site & Store      http://www.yourdomain.com/ccp51
Administrator Utility    http://www.yourdomain.com/ccp51/admin
These .htm file edits can be done via FTP. Just change the URL in each of the files to point to the proper location of each script.

STEP 7: Registering The Program

The first time you access the Administrator Utility, you will be prompted to register the program. Access the Administrator Utility using one of the following URLs: 
http://www.yourdomain.com/ccp51/admin
http://www.yourdomain.com/ccp51/cgi-bin/cp-admin.cgi or .pl
If you see an error instead of the registration screen, read the 'Installation Troubleshooting' section below.

The registration screen prompts you to input your Name, Email Address, URL and Order Tracking Number. Be sure to enter the same URL you've used for this installation. The Order Tracking Number is the Order Number you received when you purchased your license. If you incorrectly enter your Order Tracking Number, your registration will be rejected by the central registration server.

After you have registered the program, you will be prompted for a Username and Password. Your initial username and password is: 
Username: webmaster
Password: webmaster
Be sure to change these immediately after logging in by using the Administrator Utility's Change Password function. After logging in, you will be presented with the Administrator Utility's introductory screen, which includes the License Agreement. Please note, by installing the software and using the Administrator Utility you agree to the terms of the License Agreement.

If you are not presenteded with the Administrator Utility's introductory screen, and are instead sent back to the registration page, there is a problem with the permissions on the /ccp51/data directory. The entire directory needs to be writable by the webserver. Adjust your permissions using the instructions in STEP 3 above, then repeat this step.

STEP 8: Initial Configuration

After you have registered the program, logged in and changed your password, you will need to configure the main program settings for the software. The following settings can be updated using the Global Settings | Manage Program Settings function. Initial configuration requires that the following settings be updated:

Secure Site Payment Script URL

This field is the full SSL URL for the /ccp51/cgi-bin/cp-app.cgi or .pl script on your server. If you do not have an SSL URL, just enter the non-secure URL for the /ccp51/cgi-bin/cp-app.cgi or .pl script. There are notes further down in these instructions on how to obtain your SSL URLs and run the program securely. If you are unsure of what your SSL URL is, check with your host. A typical entry would be: 
https://secure.yourhost.com/yourdomain/cgi-bin/ccp51/cp-app.cgi
Path to Secure Site media Directory URL

This field is the full SSL URL for the /ccp51/media directory on your server. If you do not have an SSL URL, just enter the non-secure URL for the /ccp51/media directory. Do not include a trailing slash. There are notes further down in these instructions on how to obtain your SSL URLs and run the program securely. If you are unsure of what your SSL URL is, check with your host. A typical entry would be: 
https://secure.yourhost.com/yourdomain/media
Cookie Domain & Cookie Path Settings

These fields are the domain and path used by the cgi script to set cookies for users. A sample of what these settings should be is below: 
URL:            http://www.yourdomain.com/ccp51/cgi-bin/cp-app.cgi
Cookie Domain:  .yourdomain.com
Cookie Path:    /ccp51/cgi-bin
If these are set improperly, users may not be able to add items to their shopping carts. The program does not require users to have cookies enabled on their browser to operate, however if these settings are incorrect or partially correct, users who have cookies enabled could experience issues.

SMTP Mail Server Name / IP OR Server Path To Sendmail

Configuration of your mail server selection may prove to be difficult. Below are a few pointers to help:

If you are on a Windows webserver you will not have access to the Unix sendmail program. You will need to specify a server name (mail.yourhost.com, stmp.yourdomain.com, etc.), an IP address (127.0.0.1, 165.236.15.3, etc.) or the default localhost (localhost) designation. Approximately 80% of the time localhost will work on a Windows server.

If you are on a Unix or Linux server you have the same option to use a server name, IP address or localhost designation as those on Windows servers. If you plan on sending HTML formatted emails using the Administrator Utility's Mail List and Contact functions, you will need to specify an SMTP server name, IP address or 'localhost' for you mail server. This option is not available when you use the Unix sendmail program directly.

You have the option to use the Unix sendmail program directly. Using sendmail directly on Unix or Linux server is a more efficient way of handling mail. Sendmail should be called as follows: 
/usr/sbin/sendmail
The path above will work on 90% of the Unix and Linux servers on the Internet. Sometimes sendmail is not installed or aliased in the /usr/sbin directory. If you cannot send mail using the administrator utility, using that path, try the following in the order they are presented:

/usr/bin/sendmail
/usr/lib/sendmail
/usr/local/sbin/sendmail
/usr/local/bin/sendmail
Please note: Calling sendmail with the '-t' option (taint flag), as in '/usr/sbin/sendmail -t' is optional. The program will automatically add the '-t' if it is not present.

If after following these instructions you cannot send mail to yourself from the Administrator Utility and you are using a valid email address for your test messages, contact your host and they will be able to tell you which designation to use.

Server Path To cURL

If you will be using a payment method that utilizes the cURL program (like Linkpoint API), you will need to input the server path to the cURL program here. A typical entry would be: 
/usr/local/bin/curl
Username & Password For media/downloads Directory

If you decided to password protect the /ccp51/media/downloads directory in STEP 5 above, enter the username and password that you selected to use in these fields.

Other settings are available in the Global Settings | Manage Program Settings function, however the settings listed above are what need to be updated immediately after installation. The others are discussed elsewhere in the manual.

STEP 9: Read The Manual

With installation and initial configuration completed, login to the Administrator Utiltiy and read the manual. Just click on the 'Manual' menu choice. The manual contains invaluable information on using the software and additional configuration information and instructions.

STEP 10: Accessing The Online Store

With installation and initial configuration completed, you can access the Online Store. Access the Online Store using one of the following URLs: 
http://www.yourdomain.com/ccp51
http://www.yourdomain.com/ccp51/cgi-bin/cp-app.cgi or .pl
Installation Troubleshooting

If you have followed the instructions above properly and receive a 500 Internal Server Error when accessing either of the cgi scripts, the information below may help you solve your problem.
  1. Do the ./cgi-bin/*.cgi scripts have executable permissions? If not, change them.

  2. If this was an FTP install, did everything upload? Try to send everything up again. Perhaps something is missing (especially from the /ccp51/cgi-bin directory) or did not get uploaded fully.

  3. If this was an FTP install, did you send the /ccp51/data/tables/*.csv files up to the server in BINARY mode?

  4. Are your scripts sitting out a pre-built cgi-bin directory supplied by your host? If your host built a cgi-bin for you, there's a good chance you can't execute scripts outside of it. Move the scripts into your pre-built cgi-bin and try to execute them.

  5. Is your path to perl /usr/bin/perl? If not, change the first line (the pound-bang #! line) of the scripts to whatever that path may be. Another common location for perl is /usr/local/bin/perl.

  6. Does your host allow the execution of cgi scripts under your account? If not, they will need to turn that on for you be updating the webserver configuration.

  7. If you have access to your server error logs? If so, what does your error log say about the problem?



© 2003 Kryptronic, Inc. All rights reserved. This program is distributed under license. The license agreement includes terms and conditions as well as copyright information. ClickCartPro and Kryptronic are registered trademarks of Kryptronic, Inc.

Click here for more information on ClickCartPro.