Red Queen Installation Instructions
Adjust Text:  a a a a
« Table of Contents   |   Obtain Red Queen »

NAME

rqinstall - Installing Red Queen

SYNOPSIS

This document describes the process of installing the Red Queen system on your machine.

REQUIREMENTS

Red Queen 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 Future Quest--this is the web hosting company that I have used for several years.

  • Sufficient disk space. Red Queen itself is around 3 megabytes in size, 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.

  • Perl installed on your server, version 5.004_04 or greater. Don't know what version of Perl you have?

  • An FTP program to upload the Red Queen distribution to your webserver.

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

INSTALLING Red Queen

Downloading

The Red Queen distribution can be obtained from Random Mouse Software at http://www.randommouse.com/redqueen/.

You will need to register as a site member to gain access to the download page. The distribution itself is made available as a .tar.gz file. Unpack Red Queen 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, and strongly recommended, thing to do, as there are roughly 900 files in the fully unpacked distribution.

(Need help unpacking archives?).

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

/RQ
   /cgi-bin
   |       /rs
   |          /_lib
   |          |    /Lingua
   |          |    /RM
   |          |    /Template
   |          |    /templates
   |          |
   |          /dbops
   |          |     /do
   |          |
   |          /redqueen
   |                   /do
   |                   /my
   |                      /RedQueen
   |                      /templates
   /html
        /rs
           /dbops
           /redqueen
           /tt2

The distribution comes in two parts: a CGI script section, and an HTML page section. As outlined below, the /rs directory in /RQ/cgi-bin will be uploaded to the CGI bin area of your web site, and the /rs directory in /RQ/html will be uploaded to the HTML area (the document root) of your web site. More information on the upload procedure can be found below.

Finding Perl on your Server

If /RQ/cgi-bin/rs represents the CGI script section of your unpacked distribution, the following files within it are the executable Perl scripts:

/redqueen/do/redqueen.cgi
/redqueen/do/admin/admin.cgi
/redqueen/do/admin/google_reviews.pl
/redqueen/do/admin/install.cgi
/redqueen/do/admin/link_checker.pl
/redqueen/do/admin/nph-admin.cgi
/redqueen/do/admin/nph-test.cgi
/redqueen/do/admin/review_alert.pl
/redqueen/do/admin/reviews_rss.pl
/redqueen/do/admin/top_reviewer.pl
/redqueen/do/editor/editor.cgi

When Red Queen is up and running, the first line of each of these files must 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, itself. 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 webserver
    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.

  • Upload the CGI Directories
    Choose where on your webserver you would like to install the CGI section of Red Queen 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 everything contained in /RQ/cgi-bin/rs of the directory tree shown above. The /_lib portion of the distribution will contain common library files, or modules, that Red Queen uses. The /dbops portion represents a low-level database manager that you might find useful for checking over the structure of your database and doing the odd modification to tables, however it is entirely optional and you need not upload it if you do not wish to (it is a completely separate application from Red Queen). Note: DBops is a fairly small application, so it won't cost you much time to upload it. Finally, /redqueen will contain all the files that make up Red Queen 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 /RQ/cgi-bin/rs directory. You will upload these archives and expand them on your webserver using the Red Queen 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 Red Queen distribution. That is, everything contained in /RQ/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 /RQ/html/rs into it. These are the directories in which the static portion of Red Queen 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

Red Queen 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 Red Queen /do/admin directory. For example:

    http://www.mydomain.com/cgi-bin/rs/redqueen/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?

    Red Queen requires the presence of several standard Perl modules, separate from the Red Queen 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. Optional modules are those that can be used to implement the optional features (such as thumbnailing). If you do not have these installed you will need to do so before you try to switch on the 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 Red Queen 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 Red Queen Tar Files
    4. Attempt A Database Connection
    5. Create Red Queen Database Tables
    6. Create Red Queen 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 Red Queen 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 Red Queen directory. In Step 4 you will provide basic MySQL authentication information and the name of the database in which the Red Queen 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 Red Queen Administrator account. Once this is done Red Queen will be fully installed and ready for use.

    VERY IMPORTANT SECURITY NOTE:

    Afer running install.cgi successfully, you should visit the Red Queen administrative control panels:

    http://www.mydomain.com/cgi-bin/rs/redqueen/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. Red Queen 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 Red Queen 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 Red Queen, you would be foolish not to restrict access if you install these programs.

RUNNING Red Queen

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 Red Queen 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 Red Queen pages) until you have explored all the relevant parts of the application.

REQUIRED/OPTIONAL MODULE INSTALLATION STEPS

When you initiate the Red Queen 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 Red Queen 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 Red Queen 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 Red Queen.

    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. Red Queen 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 Red Queen 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

Unpacking .tar.gz Archives

The Red Queen distribution, plus additional supporting Perl modules, are packaged in .tar.gz format--these are gzip-ed TAR archives. The distribution can be unpacked on Unix by applying the gunzip and tar utilities:

$ gunzip distribution.tar.gz
$ tar -xvf distribution.tar

If you are unpacking the distribution on Windows you can use PKZip, or Winzip in classic mode. Macintosh users can unpack the distribution with Stuffit Expander.

NOTE: Take care if you unpack the distribution with Winzip. If you use the program's wizard mode instead of classic mode you may find that Red Queen's directory structure is NOT preserved, and all files are unpacked into a single directory. This will mitigate the installation. You should ensure that the unpacking results in a clearly-defined directory structure.

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 Red Queen 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 Red Queen will only be writeable by you.

When the Red Queen 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 Red Queen »

Copyright © 2004 Random Mouse Software. All Rights Reserved.