#################################################################### # Red Queen 2.00 Release Candidate 1 # ----------------------------------------------------------------- # # Red Queen README is © 2004 Random Mouse Software. # # # # ---------------- RED QUEEN IS NOT FREE SOFTWARE ----------------- # # ---------------- IT IS JUST DAMN GOOD SOFTWARE ----------------- # # http://www.randommouse.com | http://www.randommouse.com/redqueen/ # ##################################################################### # Description: Instructions for how to Install RED QUEEN # # This program is being distributed commercially. It may be used # free of charge for the 30 days following the day on which it was # received, after which time it will expire. The program's # longevity is controlled by a 'key', a non-expiring version of # which may be purchased (the initial keys that come with the # distribution are 30-day keys--one which displays the powered-by # notice at the bottom of pages, one which removes the notice). # If your trial keys expire and you have not finished your testing, # you can request a replacement. # # A statement about CGI security matters is always in order. # RED QUEEN has NOT been designed to compile in 'taint' mode. # However, a good deal of consideration has been devoted to # 'untainting' FORM inputs, and you are more likely to regard the # program as excessively fussy about what it will allow through # than to view it as overly relaxed. Even so, by using this # program you agree to indemnify Random Mouse Software from any # liability. You should read the comments found in the file # /do/admin/install/RM/File/Permissions.pm to better understand # the security implications of running this program (you may need # to edit that configuration file by hand anyway). All file and # directory additions will either appear under the cgi-bin # directory in which you place the Red Queen scripts OR in a # specially marked (by you) attachments directory OR under # a subdirectory of your document root that you have explicitly # specified (static review pages appear under the document root, # so as to be spiderable/indexable). # # Selling the code for this program is expressly forbidden. # Nor is redistributing this program over the Internet or in # any other medium permitted. In all cases copyright and # powered-by notices MUST remain intact UNLESS a special key # has been purchased for the purpose of explicitly removing # those notices. # # For a more formal description of your rights regarding the # use of this distribution, please read the accompanying file # LICENSE.txt which spells out the terms of the RED QUEEN # user license. # ##################################################################### INSTALLATION ============ Installing this program is usually not difficult. An installation script is included in the distribution to help automate the process. By following the instructions in this README file (or, alternately, the QUICK_INSTALL file if you want the short version) you should be able to perform the installation yourself. However, if the installer fails to work correctly on your site you should request help. If you would like me to install it for you I can do so (or try). Skip to the next section if you intend to install yourself by using the installer script. See also the later section INSTALLING THE PROGRAM YOURSELF. To make paid-for installations go as smoothly as possible, I've added a 9 point list of things to consider before you request installation services. As you read through the list, jot answers down on a piece of paper, making note of the ones you need to ask your web host about: (1) Presently I charge US$60. This may change at any time. (2) My contact address is stephen@randommouse.com (3) At a minimum I'll need your FTP login username/password as well as the hostname (or IP address) for your site. I will be using WS_FTP Pro to transfer the files. (4) I need to know the path to the CGI directory into which you want the program installed (otherwise I'll choose to place it in /cgi-bin/rs/redqueen). I also need to know the path to your document root (i.e. where your HTML pages are normally found, so that I can place images, and documentation). Unless you spell out the installation location explicitly I will put Red Queen where I THINK you want it (and I might be wrong!). (5) If your main CGI bin doesn't map to http://yourdomain.com/cgi-bin/ then let me know where it does map to so that I can access the installation script after I've uploaded it. (6) Don't bother uploading files. I'll do that myself. (7) Knowing which operating system hosts your site can also be helpful (Linux, Unix, Windows etc). (8) I'll need to know the path to Perl (version 5) on your system. If you're not sure, look at the first line of any Perl CGI script which is currently running on your site. It'll look something like #!/usr/local/bin/perl If you still don't know, ask your web hosting company, or telnet into your web site and type the following at the command line to get the location: whereis perl (9) You'll need to supply your MySQL username/password, the hostname of the database server (it might just be 'localhost'), and the prefix with which you would prefer your RED QUEEN tables to be named (the default being rq_). Also, your web hosting company should have the perl DBI module installed, as well as the DBD module for MySQL in order for the program to interact with the database server. If your web host demands that you connect to your MySQL server using a specified socket file, then I'll need the socket path (though having to specify the socket path is not very common). A note about WHICH database to select when you intend to integrate Red Queen with a member database that already exists: You can put the Red Queen tables into the existing database or you can put them into a separate (new) database. Either way will work as far as integrating with another program like vBulletin, Phorum, etc. It's just a matter of whether you want to add another 30 odd tables to the database for the other application, or put them elsewhere. If you can create databases willy nilly then I'd recommend you create one named 'redqueen'. Otherwise use an existing database. Authenticating logins on the member tables of the other application will be transparent and work the same either way. Please send as much of this information as possible if requesting installation services. If you install the program yourself, please read this file in its entirety before you get started. BACKGROUND INFORMATION ====================== RED QUEEN consists of a collection of CGI scripts, written in Perl, which allow licensed users to manage a directory of Items, Members, and Suppliers (or a subset of these). These are grouped, respectively, into Categories, Teams, and Yellow Pages. Each of these groupings can have its own unique set of rating attributes, and members can review any Item, Member, or Supplier which appears in the associated group. If you're familiar with the review pages of Amazon.com you'll have a good idea about what to expect when it comes to RED QUEEN's user interface (as in the review submission process and the presentation of published reviews). Behind this, you'll discover a flexible series of administrative configuration and control panels, which in conjunction with a selection of customizable templates, allows you to configure RED QUEEN to reflect the look and feel of your site. Everything is fully automated, bar review evaluations and member submissions which generally need to be performed by an assigned editor at his/her leisure (though you can arrange to bypass this step if you wish). Basically, the flow of review submissions follows this pattern: (1) user visits the review-submission page for a particular thing (Item/Member/Supplier), and fills out the review form and submits it. (2) an editor (one assigned to moderate reviews for the given thing) is automatically alerted by email to the new submission, which sits in a "holding area" awaiting evaluation. (3) after one or more new reviews have been collected the assigned editor visits the editor's page (via the browser) and is informed about which things have reviews awaiting. (4) thing by thing, the editor evaluates each new review (of those things they have authority over) and accepts it, declines it, or reassigns it to the holding area. accepting or declining a review causes an email to be sent to the reviewer, telling them of the editor's decision. a note can be attached to a rejection message if the editor has something particular to add. (5) accepted reviews automatically appear on the review page associated with the thing. (6) thing submissions are handled in a manner analogous to thing review submissions. For licensing information, please see the accompanying file LICENSE.txt #################################################################### # # # For a quick-n-dirty installation see QUICK_INSTALL.txt. This # # will allow you to set things up in a matter of minutes to # # determine whether there may be any system problems you might # # need to deal with. If you do that, make sure you come back # # and finish reading this file! # # # #################################################################### WEB DESIGNERS WHO HAVE WORKED WITH RED QUEEN ============================================ If you think you might be in need of a web designer to spruce up your Red Queen implementation, here's a list of possibilities: Dustin Hassard | Captain (in San Diego, CA) http://www.BrandFly.com Design & Other Creative Stuff [ Toll Free ] 888.354.2673 [ Fax ] 888.310.8307 [ Email ] dustin@BrandFly.com Kevin Gosselin (in Seattle, WA) http://www.hcpassociates.com/extranet/kevin/Index.asp [ Email ] kgosselin@hcpassociates.com NOTE ON ZIPCODE / POSTCODE DATA =============================== If you think you'll be offering U.S. zipcode based searches you should download the extra zipcode tar file by going to http://www.randommouse.com/cgi-bin/rms/product/obtain/obtain_zipcodes.cgi (this is a large file so it has been split off from the distribution). If you don't think you'll need it, don't bother. You can always download it later and add its contents to your existing tables if you need to. If you do download it, unzip the file to obtain a file named CGI_redqueen_do_admin_install_zipcodes.tar Place this file with all the other .tar files (for the location, see the later discussion on the .tar files). The zipcode tar file allows zipcode searching out to 10 miles and is meant to be used for testing only. Customers who purchase a key can request a script that will extend zipcode searching out to a maximum distance of 100 miles. See Tutorial Four (accessible from the Red Queen user manual) for information on how to incorporate zipcode searches. Likewise, if you think you'll be offering searches based on U.K. postcodes you should download the extra UK postcodes tar file by going to http://www.randommouse.com/cgi-bin/rms/product/obtain/obtain_postcodes_uk.cgi If you do download it, unzip the file to obtain a file named CGI_redqueen_do_admin_install_postcodes_uk.tar and place it with the other .tar files. Again, this file will allow postcode searching out to a distance of 10 miles. Once you have purchased a Red Queen key you may request a command line script to update your postcode tables to allow searches out to a maximum distance of 100 miles. For more information on activating Zipcode or Postcode searches, see the section in the Red Queen User Manual on ADDING COLUMNS TO A TABLE. UNPACKING ========= If you received this README file as part of the distribution then this paragraph is superfluous (because you've already unpacked the distribution). For those yet to do so, here's how: The distribution comes in the form of a directory structure that is tarred and zipped. It's either a .tgz file or a .zip file, and the best way to decompress it is on your PC with PKZIP which can be downloaded as shareware from www.pkware.com if you don't already have it. Alternatively, for the .tgz case, if you have gzip and tar utilities available to you, you can decompress like this: gzip -dv REDQN_1_0.tgz tar -xvf REDQN_1_0.tar This should produce a directory called /REDQN_1_02 if the zipped file is called REDQN_1_02.zip (corresponding to version 1.02 of the distribution). This directory corresponds to /RQ in everything that follows. Be sure that the letter case of the files/directories in the package match those detailed in this file (some users have reported occurrences of incorrect letter case after unpacking). The initial unpacked directory structure (on your PC, before transferring any files to your web host) should look like the following: /RQ /cgi-bin | /rs | /_lib | | /Lingua | | /RM | | /Template | | /templates | | | /dbops | | /do | | | /redqueen | /do | /admin | | /import_examples | | /install | | | /Archive | | | | /Star | | | | | | | /defs | | | /populate | | | /postcodes | | | | /uk | | | /RM | | | | /File | | | | | | | /table_defs | | | | | /RedQueen | | /templates | | | /default | | /index | | /stoplist | | | /editor | /html /rs /dbops /other /redqueen /tt2 DOCUMENTATION PAGES =================== Although you have unpacked the distribution, you will not be able to consult the documentation pages for Red Queen until AFTER you have run the installer (which unpacks the .tar files found in /RQ/cgi-bin/rs). However, after installation you should be able to type into the browser the address to your Red Queen User Manual: http://yourdomain.com/rs/redqueen/docs/manual/rqmanual.html If you wish to look at the manual before installation, visit the Random Mouse Software site and look for the online version of the documentation. There is a link for it on the RS home page: http://www.randommouse.com/ INSTALLING THE PROGRAM YOURSELF =============================== RED QUEEN is easy to install. In most cases, all that is required is for you to upload the unpacked distribution to your web host and run the installation script to complete the directory structure and establish the tables required to run the program. Of course, you will also need to ensure that the directories and files contained in the distribution have the appropriate permissions. This README file provides explicit details on how to go about this. First up, copy all files in the distribution which are stored in /RQ/cgi-bin into a subdirectory of the main CGI bin on your site. That is, create a directory named /rs in your main CGI bin (note: /rs will be the place you store distributions from Random Mouse Software) and copy into it all the files and directories in the /RQ/cgi-bin/rs portion of the unpacked Red Queen distribution. It is important that, except for the .tar files found in the directory /RQ/cgi-bin/rs (which should be uploaded in BINARY) every other file MUST be uploaded as ASCII. For the associated permission settings, see later in this README file. Before uploading the installer file: /RQ/cgi-bin/rs/redqueen/do/admin/install.cgi you should check the first line of the file. If the path to the Perl interpreter on your web host does NOT match what you see on the first line of the script, edit it so that it does. e.g. you will MIGHT need to change #!/usr/local/bin/perl to #!/usr/bin/perl or #!/perl/bin/perl or something else. Other executable files will have their first line modified (by the installer) to reflect the first line of the installer script after it has completed the installation, so install.cgi is the only file that MUST have the correct Perl path at the top of it. Note: the -w appended to the line containing the path to your perl interpreter means that the program will run with warnings switched on. This is VERY useful, because if something isn't quite right with the installation you should get a warning message produced alerting you to the problem. You can remove the -w when you are confident that things are running smoothly, or you can just leave it in. The permissions of executable scripts other than the installer script (those in /redqueen/do and /redqueen/do/admin and /redqueen/do/editor which have .cgi or .pl extensions) will be set by the installer itself at the end of the installation process according to the permissions specified in the file /redqueen/do/admin/install/RM/File/Permissions.pm (normally 0755). ATTACHMENTS DIRECTORY ===================== During installation you will be asked for the path to a directory where (private) uploaded files can be stored. The best place for storing these files is above your document root so that the files cannot be directly accessed from the web. To create such a directory above your document root you will need to telnet into your account and issue a "mkdir directory_name" command, or have your web host do it for you. If, say, /usr/www is your document root, you might create the following directory for attachments: /usr/attachments/redqueen If you cannot create an attachment directory above the document root, you can just create one IN the document root, e.g. /usr/www/attachments/redqueen (it's not as secure, but if you don't plan on storing anything of high importance as an attachment, then it's fine--though you may wish to use a directory name that is not so guessable as attachments/redqueen). Just be sure to create an attachment directory of some type before proceeding, as you'll need to supply the path for it during the installation. Also, the attachments directory will need to be writeable by the webserver so that Red Queen can actually place documents into it. If your webserver runs as you then this is automatically true. Otherwise, either make the directory owned by the webserver by doing something like this: cd /usr/attachments chown nobody redqueen if your webserver runs as the user "nobody", OR set permissions on the /redqueen directory to 0777 (though that's obviously less secure). ---------------------------------------------------------------------- RUNNING THE INSTALLATION SCRIPT (FIRST TIME RED QUEEN USERS) If this is the first time you have set up the program, your directory structure will need to be completed by running the installation script. Before doing that, however, please read (and be sure that you have understood) the content of the file /redqueen/do/admin/install/RM/File/Permissions.pm which explains the default permission settings that will be used by the installation script when creating your configuration files. If you know for a fact that the web server runs with your own user id, then very likely you will have no problems running the installer. This is because the Red Queen directories and files which you uploaded are owned by you (and therefore also by the web server) so the webserver will have no problem creating new directories and files as it performs the installation. If, however, the web server runs with a user id other than yours (such as the "nobody" or "www" user) then you will run into problems. In this case you'll need to arrange things so that the web server will have the permissions it currently lacks to complete the installation. If this represents your situation, see the section below entitled PROBLEMS UNPACKING? for instructions on how to proceed. Assuming that the installer has the appropriate permissions to unpack the .tar files that you uploaded (and if it doesn't you'll simply get an error message relaying the problem), point your browser to: http://yourdomain.com/cgi-bin/rs/redqueen/do/admin/install.cgi If a page does not appear which presents itself as Step One of the installation procedure, then see the section on PERMISSIONS, ETC below for suggestions on how to get the installation script running correctly. Once the page appears, you will be presented with a summary of the steps that will be performed to complete your installation. If any Perl modules are missing you will be informed of that too. If all looks good you will be presented with a link to Step Two. Follow the instructions and make your way through each step, supplying any requested information. When you have finished the installation you will be presented with a link to the administrative control panels. ################################################################### # # # By the way, you should really PASSWORD-PROTECT your /do/admin # # directory. If your web server is Apache, Red Queen can set up # # .htaccess and .htpasswd directory protection files for you. # # You will be presented with the option to create these files # # when you visit the administrative control panels. There is # # presently NO login for the admin directory, so unless you # # add directory protection it will be wide open! # # # # P.S. Red Queen comes with a helper application named DBops # # which also requires directory protection. Click on the DBops # # link on the top administrative control panel to get started # # on directory protection with that. Don't forget to do it! # # # ################################################################### ---------------------------------------------------------------------- PROBLEMS UNPACKING? If you run into problems with permissions during the install--presumably because your webserver is running as "nobody" or "www"--you may want to do the following. Move into directory /cgi-bin from a telnet command line and issue the command: chmod -R 0777 rs Issue the same command from /html if that is your document root. This sets the permissions on EVERYTHING in these rs directories high so that the webserver will have no problem unpacking the .tar files and creating directories. Once you have installed the software you can check what the new permissions are (the installer will attempt to set permissions on all the files at the end of the installation according to the permission values in /do/admin/install/RM/File/Permissions.pm). If the final permissions on the /rs directories are too high for your liking you can reset them by issuing something like: chmod -R 0755 rs By this stage the webserver will own /cgi-bin/rs/redqueen/my which is the directory in which configuration files and templates are stored, and it should have no problem rewriting these files when it needs to. If you want to tighten permissions after the install you can reset permissions to 0755 and change ownership of all files and directories to the webserver. ---------------------------------------------------------------------- UPGRADING FROM AN EARLIER VERSION OF RED QUEEN Rather than reproduce the information here, please consult the section in the QUICK_INSTALL file entitled UPGRADING FROM A PREVIOUS VERSION. This gives a very thorough discussion of the issues involved with preforming an upgrade, and outline the steps necessary to ensure that data from previous versions of the program is preserved. ---------------------------------------------------------------------- PERMISSIONS, ETC. At the end of the installation process, the installer will attempt to reset the permissions of all files and directories in the Red Queen distribution according to the permissions found in /redqueen/do/admin/install/RM/File/Permissions.pm For those parts of the distribution that it does NOT own (all the directories and files that you explicitly uploaded, if the webserver is running with a user id other than your own) it will fail to change the permissions. That's fine. Those that are changed will now have permissions something like the following (representing the default settings found in the permissions file--which you can probably leave as is): 'cgi_directory' => 0755, 'cgi_scriptfile' => 0755, 'cgi_datafile' => 0666, 'html_directory' => 0777, 'html_datafile' => 0666, For those parts of the distribution that the web server does NOT own (again, the explicitly uploaded directories and files if your own user id differs from that of the web server) you can set permissions as you feel appropriate. At the very least, you need to be sure that the executable scripts can in fact be read and executed by the web server. So you'd likely want to set the following executable scripts to 0755 (though if the web server is running as you, more secure permissions of 0700, or even 500 might be appropriate). Standard permissions for the "nobody" web server will be indicated with square brackets, e.g. [755] while the more secure alternative (for the webserver-is-you environment) is indicated by round brackets: /redqueen/do redqueen.cgi (700) -rwx------ [755] -rwxr-xr-x get_recent.cgi (700) [755] upload.cgi (700) [755] wimpy_button.cgi (700) [755] /redqueen/do/admin admin.cgi (700) -rwx------ [755] -rwxr-xr-x google_reviews.pl (700) [755] importer.pl (700) [755] install.cgi (700) [755] link_checker.pl (700) [755] nph-admin.cgi (700) [755] nph-test.cgi (700) [755] review_alert.pl (700) [755] reviews_rss.pl (700) [755] top_reviewer.pl (700) [755] ---------------------------------------------------------------------- CONFIGURATION ============= To begin your configuration of RED QUEEN (following the creation of the configuration directories with install.cgi, if you are installing for the first time) point your browser to the URL of the script admin.cgi which, for example, might be http://www.yoursite.com/cgi-bin/rs/redqueen/do/admin/admin.cgi You should be presented with the Red Queen control panels. Click on the Configure link in the navigation bar near the top of the page. When the Configure control panel appears you will see a list of possible configuration pages on the left side of the page. You should go through these, checking the current values for the configuration variables. In particular, check the path and email settings. Most other variables can be left as they are for the moment, until you have familiarized yourself with the operation of the program. For details on how to use Red Queen, please consult the available documentation (including tutorials) at: http://www.yoursite.com/rs/redqueen/docs/manual/rqmanual.html There is plenty of documentation to get you started, and more should be added as the program is further developed. INSTALLATION PROBLEMS ===================== * 500 Server Errors. Hopefully you don't see any of these, but if so, check the following: - Did you upload/ftp the executable files in ASCII mode? - Is the path to Perl right? (e.g. #!/usr/local/bin/perl) - Is the path to Perl to a version of perl5? - Are the executable files set to the right permissions? The web server needs to be able to read and execute install.cgi 500 server errors are almost always the result of uploading the executables in BINARY mode, or else the path to perl is wrong, or it does not point to perl version 5. * Fatal Error: You've probably uploaded something in BINARY mode! Make sure you transfer EVERYTHING BUT the .tar files in ASCII mode. Only the .tar archive files need to be uploaded in BINARY. Don't trust your FTP program's AUTO-DETECT mode, but instead transfer in ASCII/BINARY as appropriate. If you run into other problems, or have questions, please visit the forum area: http://www.randommouse.com/forum/ Good luck with your Red Queen implementation. Stephen, Random Mouse Software www.randommouse.com ~//~