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

NAME

Installing Review Foundry

SYNOPSIS

This document describes the process of installing the Review Foundry system on your machine.

REQUIREMENTS

Review Foundry requires the following:

  • A MySQL account on a decent webserver that allows you to run custom Perl CGI scripts, usually from a specially marked directory labelled /cgi-bin. If you are unsure about whether your webhost offers this, 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 (especially if you are going to require lots of disk space), and a favorite of my customers.

  • Sufficient disk space. Review Foundry and all the supporting documentation comes in a file about 9 megabytes in size, and expands to about twice that. But the amount of MySQL storage space you will need to accommodate your initial data and any future reviews will naturally depend upon the scope of your project. You may also need a considerable amount of disk space for writing files if you decide to build static pages with the program. This is one of the advantages of going with BlueHost which offers tons of disk space.

  • Perl installed on your server, version 5.004_04 or greater. Don't know what version of Perl you have? Some features also require PHP, such as the Google Map add-on.

  • An FTP program to upload the Review Foundry distribution to your webserver. 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 Foundry

Downloading

The Review Foundry distribution can be obtained from Random Mouse Software at http://www.randommouse.com/foundry/.

You will need to register as a site member to gain access to the download page. The distribution itself is made available as a .zip file. Unpack Review Foundry 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 and have the installation script unpack them later. This is the easiest thing to do, and is strongly recommended as there are roughly 2000 files in the fully unpacked distribution.

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

/RF
   /cgi-bin
   |       /rs
   |          /_lib
   |          |    /Lingua
   |          |    /RM
   |          |    /Template
   |          |    /templates
   |          |
   |          /dbops
   |          |     /do
   |          |
   |          /foundry
   |                   /do
   |                   /my
   |                      /Foundry
   |                      /templates
   /html
        /rs
           /dbops
           /foundry
           /tt2

The distribution comes in two parts: a CGI script section, and an HTML page section. As outlined below, the /rs directory in /RF/cgi-bin will be uploaded to the CGI bin area of your web site, and the /rs directory in /RF/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
         |
         /www
             /rs

Your document root, shown here as /www, might be /public_html, or something similar. Your CGI bin might also be contain inside your document root. It will depend on your host. Either way, you will have one /rs directory that contains the CGI related files (mostly in .tar archives), and another that will contain images 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 /RF/cgi-bin/rs represents the CGI script section of your unpacked distribution, the following files within it are the executable Perl scripts:

/foundry/do/good_server.cgi
/foundry/do/get_page.cgi
/foundry/do/reviews.cgi
/foundry/do/upload.cgi
/foundry/do/wimpy_button.cgi
/foundry/do/admin/admin.cgi
/foundry/do/admin/google_reviews.pl
/foundry/do/admin/install.cgi
/foundry/do/admin/link_checker.pl
/foundry/do/admin/nph-admin.cgi
/foundry/do/admin/nph-test.cgi
/foundry/do/admin/review_alert.pl
/foundry/do/admin/reviews_rss.pl
/foundry/do/admin/top_reviewer.pl
/foundry/do/editor/editor.cgi

When Review Foundry is up and running, the first line of each of these files 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 other executable files 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. If necessary, adjust the first line of install.cgi to reflect the correct Perl location.

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 Foundry 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 Foundry 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. Then open that directory. This must be a web-accessible directory from which Perl CGI scripts can be run. For example: /cgi-bin/rs might be a good choice for the name of the directory you use to store applications from Random Mouse Software. 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 /RF/cgi-bin/rs portion of the directory tree shown above. The /_lib portion of the distribution will contain common library files, or modules, that Review Foundry uses. The /dbops portion represents a low-level database manager that you might find useful for checking over the structure of your database, however it is entirely optional and you need not upload it if you do not wish to (it is a completely separate application from Review Foundry). Note: DBops is a fairly small application, so it won't cost you much time to upload it. Finally, /foundry will contain all the files that make up Review Foundry proper.

    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 /RF/cgi-bin/rs directory. You will upload these archives and expand them on your webserver using the Review Foundry 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 /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. 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 Foundry distribution. That is, everything contained in /RF/html/rs of the directory tree shown above. If /html represents the document root on your web site, then you might create /html/rs and upload the contents of /RF/html/rs into it. These are the directories in which the static portion of Review Foundry will be kept, such as images and documentation files.

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

  • Setting permissions
    You should set the permissions of all of the CGI scripts (e.g. files in /do, /do/admin, and /do/editor, whose names end either in .cgi or .pl) 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 this 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 this 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 Foundry Installer

  • Invoking install.cgi

    Installing the program from here on out should be fairly straight forward, provided your webhost 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 Foundry /do/admin directory. For example:

    http://www.mydomain.com/cgi-bin/rs/foundry/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 Foundry requires the presence of several standard Perl modules, separate from the Review Foundry 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. Any optional modules, such as the Image::Magick module which can be used for thumbnailing, are also checked (note: it is strongly recommended that you get Image::Magick installed on your server if you do not already have it as it represents the best way of performing automatic thumbnails, and you will find you need a good thumbnailing library). If you do not have these optional modules installed you will need to do so before you try to switch on the associated option after installation. Otherwise you can ignore the missing modules if you do not plan to use those particular features.

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

  • Dealinq With Missing Modules

    If the installer complains that one or more required modules are missing, or if you intend to make use of optional modules which are not present on your system, 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 Foundry Tar Files
    4. Attempt A Database Connection
    5. Create Review Foundry Database Tables
    6. Create Review Foundry Administrator Account

    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 Foundry 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 Foundry directory. In Step 4 you will provide basic MySQL authentication information and the name of the database in which the Review Foundry tables will be created. Provided that a database connection can be established, those tables will be created in Step 5. Finally, in Step 6, a username and password will be requested from you and will be used to create the Review Foundry Administrator account. Once this is done Review Foundry will be fully installed and ready for use.

    VERY IMPORTANT SECURITY NOTE:

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

    http://www.mydomain.com/cgi-bin/rs/foundry/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 Foundry 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 Foundry control panels and perform any action that you can as the Administrator. So you should go ahead and protect the directory now. You should likewise visit the DBops URL and set up directory protection on that as well:

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

    DBops allows you to perform basic database operations on ALL tables in ALL your databases, so, as with Review Foundry, you would be foolish not to restrict access if you install these programs.

RUNNING Review Foundry

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. The next thing to do is visit the Configure control panel. Look for the corresponding link in the navigation bar. When you reach the Configure control panel, you will see a list of configuration subsections in a panel on the left side of the page. You can look through these, but, except for the Email settings which you might want to adjust, you can probably leave the configuration of the program alone until you have familiarized yourself somewhat with its operation.

  4. Because Review Foundry is a fairly complex application you should read the parts of the manual that relate to setting up categories, adding items, attaching reviews, and so on, before you start editing any templates. It is a good idea to leave the default template set as is (with the exception perhaps of navigation.pl, which allows you to wrap your site around Review Foundry pages) until you have explored all the relevant parts of the application.

REQUIRED/OPTIONAL MODULE INSTALLATION STEPS

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

If you need to install DBD::mysql

If your server does not have the required DBD MySQL driver, contact your hosting provider and ask them to install the DBI module and DBD::mysql so that Review Foundry 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 Foundry.

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

If you need to install Image::Magick

Because the Perl Image::Magick module relies on a graphics library that must be compiled into your webserver, you will need to request this of your webhost if the module is not currently available to you. Review Foundry can use the Image::Magick module to automatically create thumbnails of uploaded images. However, there are alternatives to using Image::Magick. If you have either the GD or NetPBM graphics libraries on your system Review Foundry can be just as easily configured to use one of these instead.

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 Foundry should the need arise. When the webserver 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 webserver runs as you, because directories created by Review Foundry will only be writeable by you.

When the Review Foundry 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.

« Table of Contents   |   Obtain Review Foundry »

Copyright © 2004 Random Mouse Software. All Rights Reserved.