Review Site Installation Instructions
Adjust Text:  a a a a
« Table of Contents   |   Obtain Review Site »

NAME

Installing Review Site

SYNOPSIS

This document describes the process of installing the Review Site system on your web hosting platform.

REQUIREMENTS

Review Site requires the following:

  • A web hosting running Apache for the web server. That's about the only way you can expect .htaccess file directives to be honored, and Review Site uses them in both the back end and the front end of the application. In the back end they are used for directory protection. In the front end they are used for SEO purposes - to make extensionless PHP files (with no trailing .php extension) execute as PHP files.

  • A MySQL account on a decent web hosting platform that allows you to run custom Perl CGI scripts, usually from a specially marked directory labelled /cgi-bin. Your web hosting platform must also allow you to implement custom PHP scripts. Virtually all web hosting companies offer these services. Bu if you are unsure about whether your web hosting company offers these services, ask them. If you have trouble installing the program use the forum area at Random Mouse Software to seek advice. If you still have problems, consider installing the program at either Future Quest (the web hosting company that I have used for several years, though they tend to be a little expensive), or BlueHost, somewhat cheaper, and a favorite of my customers.

  • An FTP client to upload the Review Site distribution to your web server. Filezilla works well and is free.

  • A web browser with javascript enabled. Many of the administrative features assume javascript is available and simply will not function without it.

INSTALLING Review Site

Downloading

The Review Site distribution can be obtained from Random Mouse Software at http://www.reviewfoundry.com/reviewsite/.

The distribution itself is made available as a .zip file. Unpack Review Site on your local machine. The resulting (partially) unpacked distribution will include several .tar files which themselves can either be unpacked before uploading to your webserver, OR (and this is why they are still archived) you can upload these tar files as-is and have the installation script unpack them later. This is the easiest thing to do, and is strongly recommended.

When you have (partially) unpacked the Review Site distribution on your PC you should see a directory structure roughly like the one shown below:

/RSITE
      /cgi-bin
      |       /rs
      |          /_lib
      |          |    /RM
      |          |    /templates
      |          |
      |          /reviewsite
      |                    /do
      |                      /admin
      |                            /install
      |                            |       /Archive
      |                            |       |       /Star
      |                            |       |
      |                            |       /defs
      |                            |       /populate
      |                            |       /RM
      |                            |       |  /File
      |                            |       |
      |                            |       /table_defs
      |                            |
      |                            /Reviewsite
      |                                       /Admin
      |                                       /Table
      |                            /templates
      |                                      /admin
      |                                      /cfg
      |                                      /compiled
      |
      /html
           /rs
              /reviewsite

The distribution comes in two parts: a CGI script section which handles the back end database operation required to enter reviews into the system, and an HTML section where the PHP front end scripts reside.

As outlined below, the /rs directory in /RSITE/cgi-bin will be uploaded to the CGI bin area of your web site, and the /rs directory in /RSITE/html will be uploaded to the HTML area (the document root) of your web site. Once you have done this, the file structure on your site will be something like the following:

/mydomain
         /cgi-bin
         |       /rs
         |
         /public_html
                     /rs

Or may it will look like this, if your CGI bin resides in your document root: 

/mydomain
         /public_html
                     /cgi-bin
                     |       /rs
                     /rs

Regardless of wehther your CGI bin exists inside your document root, or not, you will have one /rs directory that contains the CGI related files (mostly in .tar archives), and another that will contain images, PHP scripts, and documentation once the installer has unpacked the .tar files. More information on the upload procedure can be found below.

Finding Perl on your Server

If /RSITE/cgi-bin/rs represents the CGI script section of your unpacked distribution, the following file within it represents the sole executable (administrative) Perl script:

/cgi-bin/rs/reviewsite/do/admin/admin.cgi

When Review Site is up and running, the first line of this file will contain the correct path to Perl on your webserver. Typically this is #!/usr/bin/perl, or maybe #!/usr/local/bin/perl. However, the ONLY file that you MUST ensure has the correct Perl location before you begin the installation is the installer script, install.cgi. This is because the installer will REWRITE the admin.cgi file with the correct Perl location (taken from its own first line) as part of the installation process.

If you are unsure about the location of Perl on your webserver, but you have a shell (command line) account, log in to that account and type:

$ whereis perl

This will give you the location of Perl on your system. Or you can just guess it. If it is not /usr/bin/perl try /usr/local/bin/perl instead. Usually it is one or the other. If necessary, adjust the first line of install.cgi to reflect the correct Perl location. The install script lives in the same directory as your admin.cgi script.

Preparing Installation Directories

  • Connect To Your Web Server
    Before the installation script can be run on your webserver, you must first upload the distribution. Open up your FTP program and use it to connect to your web server.

  • Test Your Server
    As outlined in The Importance Of Web-Server-Is-You Hosting Platforms you should upload and run the good_server.cgi test script on your server to see if there are potential problems with installing Review Site on your server. If there are no reported problems, proceed.

  • Upload the CGI Directories
    Choose where on your webserver you would like to install the CGI section of Review Site and (if not upgrading, but installing for the first time) use your FTP program to create a directory to contain this part of the distribution.

    I recommend that you following the directory naming conventions specified above for the CGI files. That is, create a CGI directory at:

    /cgi-bin/rs

    Use your FTP program to set the permissions of this directory, and any others you create, to 0755. If you are unsure about how to do so, check the Setting Permissions section below.

    Into this newly-created directory you will upload every file and directory contained in the /RSITE/cgi-bin/rs portion of the directory tree shown above. The /_lib portion of the distribution will contain common library files, or modules, used by the administrative part of Review Site.

    You will notice that, initially, these directories are mostly empty, with the bulk of the distribution still bound up in the .tar archives, which are located in the /RSITE/cgi-bin/rs directory. You will upload these archives and eventually expand them on your webserver using the Review Site installer.

    EXCEPT for the .tar files, which you must upload in BINARY mode, everything else (files and directories) must be uploaded in ASCII mode. Do NOT rely on your FTP client to automatically choose the correct upload mode. Sometimes the client will upload ASCII files incorrectly as BINARY, or vice versa, and this can cause problems. Be sure to upload the .tar archive files into the top directory of your CGI section (i.e. into /cgi-bin/rs if you have followed the naming conventions used here), and DO NOT rename any of these tar files, as the file name has embedded within it the path to the directory into which the file will be unpacked.

    Note: In the event that the installer finds itself unable to create directories during installation, you may have to temporarily increase directory permissions on the uploaded branch to 0777. This may be required if the webserver runs with a user id other than your own. Those kinds of web servers are always trouble for Perl scripts. For more information, see the discussion on the CGIWrap and suEXEC environments.

  • Upload the HTML Directories
    As you did for the CGI section, choose a location within your document root (the web-accessible area where you store plain HTML pages) to store the HTML component of your Review Site distribution. That is, everything contained in /RSITE/html/rs of the directory tree shown above. If /public_html represents the document root on your web site, then you might create /public_html/rs and upload the contents of /RSITE/html/rs into it. These are the directories in which the static portion of Review Site will be kept, such as images and documentation files. It is also the place where the PHP scripts live. These are responsible for handling the front end of the application.

    Upload everything here (files and directories) in ASCII mode. Permissions for these directories should be set to 0777, permissions for the files to 0666.

  • Renaming the HTML Directory
    It may occur to you that, for SEO purposes, you should rename the path to the front end portion of Review Site to something other than:

    /public_html/rs/reviewsite

    This would be a good idea. If your niche happened to be Napa wines, then I recommend that you change this to:

    /public_html/napa/wine/

    Something along those lines. Then your reviews would be found at the URL /napa/wine/reviews and your articles at /napa/wine/articles.

    Note that we are talking about the HTML portion of the distribution only. DO NOT rename the CGI paths. They never appear in any of the public URLs.

  • Setting permissions
    You should set the permissions of the CGI scripts (e.g. admin.cgi and install.cgi) to 0755. When permissions are set to 0755, this means that all users on the system have Read and Execute permissions; while only the owner has the extra Write permissions. Other files found in the CGI section can also be set to 0755, or just 0666 (as these only need to be read by the webserver).

    If your FTP client displays permission settings as a series of checkboxes, it should look something like one of the following dialog boxes for a 0755 setting:




    If you are setting permissions through a Unix shell instead, simply use the chmod command on each executable script. For example:

    $ chmod 755 install.cgi

Review Site Installer

  • Invoking install.cgi

    Installing the program from here on out should be fairly straight forward, provided your web host has the necessary (standard) Perl modules installed. Open up your browser and enter into the address bar the URL to the installation script, which is located in the Review Site /do/admin directory. For example:

    http://www.mydomain.com/cgi-bin/rs/reviewsite/do/admin/install.cgi

    You should see the installation screen appear. If instead you get a 500 Internal Server Error error message, go back and check the steps outlined above for uploading install.cgi. Did you set the location to Perl correctly on the first line of the script? Was it uploaded as ASCII? Were the file permissions set to 0755?

    Review Site requires the presence of several standard Perl modules, separate from the Review Site code itself. The first thing the installation script will do is check for these modules and complain if they are not found. The most important of these is DBD::mysql, without which a database connection cannot be made.

    If the script runs successfully, it will say Review Site Installer: Step One and so on.

  • Dealinq With Missing Modules

    If the installer complains that one or more required modules are missing, install them now, using the following instructions:

  • Installing In Steps

    To reduce the resources required to install the program, the installation script is run in 6 steps. These steps perform the following tasks:

    1. Profile Your System
    2. Confirm Paths / URLs
    3. Unpack Review Site Tar Files
    4. Attempt A Database Connection
    5. Create Review Site Database Tables
    6. Activate Administrative Pages

    In Step 1 the installer will check for missing Perl modules. It will also let you know something about the file and directory permissions it intends to use, and whether or not there are any impediments to proceeding to Step 2. If not, in Step 2 you will be presented with a series of paths and URLs which Review Site needs to locate other parts of the distribution. These all need to be correct before you can proceed to Step 3, where, if necessary, the .tar archives will be unpacked and the resulting files written to the relevant Review Site directory. In Step 4 you will provide basic MySQL authentication information and the name of the database in which the Review Site tables will be created. Provided that a database connection can be established, those tables will be created in Step 5. Finally, in Step 6, the Review Site Administrative pages will be activated. Once this is done Review Site will be fully installed and ready for use.

    VERY IMPORTANT SECURITY NOTE:

    Afer running install.cgi successfully, you should visit the Review Site administrative control panels:

    http://www.mydomain.com/cgi-bin/rs/reviewsite/do/admin/admin.cgi

    You will be prompted to set up directory protection on the administrative directory /do/admin. This can be done automatically for you if your webhost is running the Apache webserver. Review Site will prompt you for a username and password to use with .htaccess and .htpasswd files, which it will then create in /do/admin. With these directory protection files in place, each time you return to the administrative pages you will be required to go through a Basic Authentication step to gain access to the program. FAILURE TO PROTECT THE ADMIN DIRECTORY INTRODUCES A MAJOR SECURITY RISK. If you do NOT protect the /do/admin directory, then absolutely anyone can access your Review Site control panels and perform any action that you can as the Administrator. So you should go ahead and protect the directory now.

RUNNING Review Site

Now that you have the system installed, you are ready to start using it.

  1. Either use the link to the admin pages provided at the end of the installation process, or open your web browser and point it at the URL on your site for /do/admin/admin.cgi (as indicated above). If the administrative control panels do not appear, go through the standard check procedures for executable scripts: Did you upload admin.cgi as ASCII? Did you set permissions on it to 0755? You can also check that the first line of the admin script is the same as the first line of the installer, install.cgi, though this should not be necessary as the first line of admin.cgi is rewritten by the installer using its own first line for the Perl location. If all else fails, take a look at Troubleshooting.

  2. Once you have gained access to the administrative pages, the first thing you should do is follow the recommendation presented to you to protect the admin directory by setting up a directory-protection mechanism. This was covered in the installation notes.

  3. Even though Review Site is a VERY SIMPLE application you should nonetheless read the parts of the manual that relate to adding and modifying records in the database BEFORE you actually begin doing so.

IS THE .htaccess FILE WORKING?

When you click on the links in your index page you ought to end up on functioning web pages. If however this is not the case, and you (a) get some kind of error, or (b) the browser shows PHP code rather than executing it, or (c) a dialog box pops up asking you to download code, then it is almost certainly due to the fact that your .htaccess file is not working as it should be. The .htaccess file lives here (assuming the default path names):

/rs/reviewsite/

and the content of it looks like this:

DirectoryIndex index.php
<Files ~ '^(reviews|compare|articles|search|recommends|about|contact|privacy|sitemap|phpinfo)$'>  
  ForceType application/x-httpd-php  
</Files>

Let's presume that your web server is Apache (since you SHOULD NOT be installing Review Site on web servers that do not honor .htaccess files).

On some Apache servers you may find that the ForceType directive is invalid and even outlawed (causes the errors you are seeing). If you think this might be the case, try changing to a SetHandler directive instead:

DirectoryIndex index.php
<Files ~ '^(reviews|compare|articles|search|recommends|about|contact|privacy|sitemap|phpinfo)$'>  
  SetHandler application/x-httpd-php  
</Files>

Another thing to watch out for is that some servers distiguish between PHP 4 and PHP 5, so that X-HTTPD-PHP specification for the interpreter may need to read as follows, with a 5 appended to it:

application/x-httpd-php5

If NONE of these solutions solves the problem it is time to get on the phone with your web hosting company. Tell them that you want to "Cause my extensionless PHP files (those without a trailing .php) to be executed by the web server as PHP files. Can you tell me what is wrong with my .htaccess file in /rs/reviewsite ?" (or whatever the path is to the directory that contains your Review Site PHP files).

Certainly, if your web hosting company cannot help you figure out what the issue is, likely no-one else can either, and it is time to consider moving to a more user friendly web hosting platform, such as BlueHost.

REQUIRED MODULE INSTALLATION STEPS

When you initiate the Review Site installer, it will report to you on the availability of required Perl modules. If a required module is missing, you will need to install it before proceeding with the Review Site installation.

If you need to install DBD::mysql

If your server does not have the required DBD MySQL driver, contact your web hosting provider and ask them to install the DBI module and DBD::mysql so that the administrative part of Review Site can connect to your database.

If you need to install CGI

  1. Connect to your FTP server, and open the directory into which you installed Review Site.

    If a directory called _lib does not exist, create it. Then open that directory.

  2. Download the file at this URL: 
    http://www.randommouse.com/public/cpan/cpan-CGI.tar.gz

  3. Unpack the .tar.gz archive (Need help unpacking archives?).

  4. Upload the file CGI.pm and the directory CGI into the _lib directory.

  5. After uploading, CGI.pm should be located at _lib/CGI.pm, and CGI/ should be located at _lib/CGI/.

ADDITIONAL NOTES

Version of Perl on your server

If you are unsure about which version of Perl your web host runs, either ask them or, if you have shell access to your webserver, telnet into your server and run the following command which will print out the version of Perl: 

$ perl -v

Back to installation instructions

Using CGIWrap or suEXEC

If your webhost has set up either a CGIWrap or suEXEC environment on your webserver, you will find that your CGI scripts run with your own user identity (rather than with a separate webserver identity). This simplifies life because there will no longer be a distinction between you and the webserver. In particular, you will be able to login via telnet and edit files created by Review Site should the need arise. When the web server does not run as you, you will not have permission to do this (which at times can be frustrating). Security is also improved when the web server runs as you, because directories created by Review Site will only be writeable by you.

When the Review Site installer is run, the script will compare the identity of the webserver with that of the owner of the script itself. If they differ it will report that you are (probably) not running under CGIWrap or suEXEC.


Next Section: GETTING STARTED WITH REVIEW SITE

« Table of Contents   |   Obtain Review Site »

Copyright © 2008 Random Mouse Software. All Rights Reserved.