Smart Search (v4.34) Setup Instructions

Setup If you're installing new or upgrading from a version of Smart Search earlier than 4.0, follow the standard installation directions. If upgrading from version 4.0 or later, follow these instructions.

Installation Directions

With Remote Shell (Telnet) Access:

1. Upload setup.pl and setup.dat to your server (ASCII mode) in the directory where you want Smart Search to store its files
2. Open a Telnet (or other remote shell) connection to your server
3. Change to the directory which contains setup.pl and setup.dat
4. Type "which perl" and hit enter - this will tell you where Perl is located on your server. You will need to give setup.pl this information.
5. Run "perl setup.pl"
6. Type in the server path to Perl and hit enter.
7. Confirm that you've entered the proper path
8. setup.pl will create all necessary directories and files with the appropriate file permissions, and will automatically write the path to Perl that you've entered in CGI files that need it
9. You can now close Telnet
10. Finish upgrading or complete the installation

Without Remote Shell Access:

1. On all .cgi files in the main directory, put the path to Perl on your server at the top of the file, using your favorite text editor. On most servers the path is either /usr/bin/perl (this is the default - all necessary files in the .zip already have this) or /usr/local/bin/perl - the line at the top needs to have a #! before the server path, so if your directory is /usr/bin/perl, the line you need to put at the top of the main .cgi files is "#!/usr/bin/perl" (without the quotes). You do not need to do this to any .cgi files in the include directory.
2. Open include/functions.cgi in your editor. The first three lines will look like:

   $accounts_dir = 'accounts';
   $data_dir = 'data';
   $adminkey = 'qxxopz';
   

   Let me explain. Those who are familiar with the Smart Search directory structure could open your data directory in their browsers and open the file containing your admin password and attempt to crack it. To avoid this, you can (and should) create random directories for "accounts" and "data" and at the same time you should set a new value for $adminkey (this is used for some encryption on your site). To do this, change the variable values to a random value of the form 'accounts-asdfls' for accounts and 'data-eriuas' for data (use whatever random string you want), and change adminkey to any random string (should be between 6-8 characters, containing only letters and numbers). Make sure you remember the values you gave to $accounts_dir and $data_dir, as you will later have to create directories with these names.

   Do not change anything else in functions.cgi

3. Upload all files except setup.pl and setup.dat to your server in the appropriate directory. When uploading files, recreate the directory structure on your server. Many FTP programs can do this easily - simply select all Smart Search files and directories and select upload (ASCII mode).
4. Rename the accounts and data directories to whatever you placed in functions.cgi earlier.
5. Now it's time to change some file permissions. For the following instructions, if your program uses checkboxes, use the following:

   Permission setting: 755 Owner Group Other Read X X X Write X Execute X X X

   Permission setting: 777 Owner Group Other Read X X X Write X X X Execute X X X

6. CHMOD the main Smart Search directory to 755, so your scripts can run
7. CHMOD directories "accounts", "data" (both of these have random names now), "cached", "keywords", "templates", and "translations" to 777.
8. CHMOD subdirectories "a"-"z" and "misc" in directory "keywords" to 777 (if the program you use for .zip files doesn't extract empty directories, you may also need to create this directories before changing the permission)
9. CHMOD directory "include" and all .cgi files inside it to 755
10. CHMOD all .cgi files in the main directory to 755
11. CHMOD rebuild.pl and update.pl (in the main directory) to 755
12. CHMOD the following data files to 777:
    • cached/reset.txt
    • DATADIR(whatever you named the data directory)/admin.data
    • DATADIR/directories.txt
    • DATADIR/ccpay.data
    • DATADIR/confirm.data
    • DATADIR/paypal.data
    • DATADIR/settings.data
    • DATADIR/submissions.data
    • keywords/catchall_data.txt
    • keywords/free.db
    • All files in the "templates" directory except for index.html

13. Finish upgrading (directly below) or complete the installation

Upgrade from a version earlier than 4.0

• Clean up your old installation, i.e. delete old files, approve or deny any pending submissions, etc.
• Once you've set Smart Search up to this point, open update.cgi in your browser. Update.cgi will prompt you for the directory containing the old version. Type that directory name in and submit the form. Update.cgi will then copy the old data files into the new directory in the new format.
• When update.cgi is finished, go to admin.cgi in your new installation and click on the link that says "Rebuild Keyword Database" in the Miscellaneous section.
• Once you've tested and confirmed that the new installation has successfully copied over your old settings and other data, feel free to delete your old installation and rename the new directory to take its place.
• Remove update.cgi from the new installation's directory
• Update.cgi will copy most, but not all, of your old settings and other data files. (See Below)

Complete the Installation

• Open admin.cgi in your browser and use any name and password to log-in.
• Be sure to create an administrator account, and set up other aspects of Smart Search from admin.cgi. Most important are setting an encryption word and inputting the directory and URL of the Smart Search scripts.
• If you used setup.pl to set up Smart Search, you can now remove setup.pl and setup.dat from your server. You should also remove install.log, but you may want to download it before deleting so that you have a copy on your server. Install.log is useful for verifying that the setup was successful, but it should not be left on your server
• If you need to accept payments from Smart Search, set up the R3N3 Payment Gateway script and register Smart Search with the gateway via the Financial Settings of admin.cgi, but remember to set the URL and directory of the Payment Gateway scripts first.
• You are done! Test it out now...

What setup.pl Does:

• Sets up the Smart Search directory structure and copies files to their appropriate locations with the correct file permissions
• Assigns the accounts directory and data directory a partially random name. This is to prevent people who are familiar with how Smart Search stores data from accessing your information directly from a browser.
• Stores the values of the random directories so that the script knows where to store data
• Puts the path to Perl at the top of every CGI file that needs it

Special Notes on Editting Templates:

The ability to control every aspect of Smart Search's output is a very powerful feature, but you need to be made aware of a few things:

• To insert dynamic information into a template, special tags such as <<NAME>> are used. When editting templates from admin.cgi, the script will show a list of valid insertion tags for that template. When the template is saved, the script checks to make sure that all tags present in the template are valid and that required tags aren't left out. So, after saving a template, make sure to check if there's a message below the line that says "Changes Saved."
• On e-mail templates, the script checks the e-mail headers for validity and warns if it discovers an unrecognized header. The script also checks to make sure that there is a "To:" header present, and that there is a blank line between the e-mail headers and the body of the message.
• On many templates, there is a <<RESULTS>> or similar tag, where a list of items is inserted into the template. Another template is used to determine how this list appears, and that template is used once for each item in the list. This second template (in some cases a third template as well) will be displayed below the main template on the editting screen.

  If you're having a tough time visualizing this, go to the Templates section of admin.cgi and edit the Search Results template under Smartsearch.cgi Templates. The first file defines the main page, which contains a <<RESULTS>> tag. Where this tag is found, the script will insert a list of matching search results, according to the second or third template, depending on whether or not the bid is a free listing (or comes from an external search engine other than Searchfeed) or a paid listing.

  In the default templates, you can see that each listing has its own paragraph inside of a list, but the tags to start and end the list (<ol> and </ol>) appear in the main Search Results template.

Take some time to customize the look and feel of your site. The default templates are very bare and minimal, but they should give a good idea of how to use the template system.

Upgrading an Existing Installation

• Open "include/functions.cgi" in your favorite text editor and change the lines at the top that read:

  $data_dir = 'data';
  $accounts_dir = 'accounts';
  $adminkey = 'qxxopz';

  to match the data and accounts directory names on your server. The value of adminkey is used for certain encryption purposes. Either match this value with your current functions.cgi or make sure that when changing adminkey, you use only letters or numbers. Also, this only needs to be about 4-8 characters long.

• Follow the specific directions for the version you're upgrading from:
  • from v4.0 or v4.10
  • from v4.11-v4.16
  • Instructions for v4.17-v4.33 appear below:

Upgrading from Smart Search v4.17-v4.33

• Unless the path to Perl on your server is "/usr/bin/perl", before uploading you will need to change the top line of admin.cgi (and signup.cgi, smartsearch.cgi go.cgi, include.cgi, and update.cgi if upgrading from a version that requires an update to these files) to be your server's path to Perl:
• Upload the following .cgi files to the appropriate directory on your server in ASCII mode and CHMOD them to 755. Overwrite the existing version of these files on your server:
  • admin.cgi
  • go.cgi ( from v4.17-v.26 )
  • include.cgi ( from v4.17-v.26 )
  • signup.cgi ( from v4.17-v.25 )
  • smartsearch.cgi
  • update.cgi ( from v4.17-v4.23 )
  • update.pl ( from v4.17-v4.23 )
  • include/accounts_edit.cgi ( from v4.17-v4.22 )
  • include/accounts_manage.cgi
  • include/accounts_payment.cgi
  • include/accounts_search.cgi ( from v4.17-v4.20 )
  • include/accounts_stats.cgi ( from v4.17-v4.23 )
  • include/admin_email.cgi ( from v4.17-v4.20 )
  • include/admin_finance.cgi ( from v4.17-v4.32 )
  • include/admin_functions.cgi ( from v4.17-v4.32 )
  • include/admin_members.cgi ( from v4.17-v4.32 )
  • include/admin_misc.cgi ( from v4.17-v4.29 )
  • include/admin_search.cgi ( from v4.17-v4.22 )
  • include/admin_summary.cgi ( from v4.17-v4.30 )
  • include/bids.cgi ( from v4.17-v4.22 )
  • include/crawl.cgi
  • include/functions.cgi
  • include/listings.cgi
  • include/payment.cgi ( from v4.17-v4.32 )
  • include/search.cgi (from v4.17-v4.24)
  • translations/admin-settings.txt (from v4.17-v4.27 - for the new Searchfeed setting)
  • translations/admin.txt (from v4.17-v4.32 for E-gold strings - if you've translated, you can just check out the new entries and add them to your existing translation file)
  • translations/general.txt (same as above)

• (v4.17-v4.22) Upload translations/admin-templates.txt to update the template information for most popular keyword searches (affiliate username can be used in template)

Upgrading from Smart Search v4.11-v.4.16

• Unless the path to Perl on your server is "/usr/bin/perl", before uploading you will need to change the top line of the following .cgi files to be your server's path to Perl:
  • admin.cgi
  • go.cgi
  • include.cgi
  • smartsearch.cgi
  • update.cgi

• Upload the following .cgi files to the appropriate directory on your server in ASCII mode and CHMOD them to 755. Overwrite the existing version of these files on your server:
  • admin.cgi
  • go.cgi
  • include.cgi
  • smartsearch.cgi
  • rebuild.pl
  • update.cgi
  • update.pl
  • include/accounts_edit.cgi
  • include/accounts_manage.cgi
  • include/accounts_payment.cgi
  • include/accounts_search.cgi
  • include/accounts_stats.cgi
  • include/admin_email.cgi
  • include/admin_finance.cgi
  • include/admin_functions.cgi
  • include/admin_members.cgi
  • include/admin_misc.cgi
  • include/admin_search.cgi
  • include/admin_summary.cgi
  • include/affiliate.cgi
  • include/bids.cgi
  • include/crawl.cgi
  • include/functions.cgi
  • include/listings.cgi
  • include/payment.cgi
  • include/search.cgi

• Upload translations/admin-templates.txt to update the template information for most popular keyword searches (affiliate username can be used in template)
• (v4.11-v4.13) Create a directory named "misc" in your "keywords" directory and set its permission to 777. Adding this directory will prevent problems with non-alphabetical keywords.

Upgrading from Smart Search v4.0 or v4.10

• Unless the path to Perl on your server is "/usr/bin/perl", you will need to change the top line of every .cgi file in the main directory to correspond to where Perl is located on your server.
• Copy all .cgi files in the main and "include" directories to your server in ASCII mode, overwriting the old files.
• Upload rebuild.pl and update.pl to your server in ASCII mode. These two files are used to rebuild the keyword database and update your installation from the shell, respectively. These are needed for installations with a large amount of members and keywords, as doing things through a browser may cause time-out errors.
• CHMOD the files you just uploaded to 755 (all .cgi files, rebuild.pl and update.pl)
• In your "translations" directory, delete any existing files and replace them with included in this version's "translations" directory - admin-templates.txt and admin-settings.txt (upload in ASCII).
• If you haven't already customized your templates, then upload all templates (in the "templates" directory) in ASCII mode. If you have customized your templates, then the differences in v4.13 are as follows:

  From v4.0:

  1. In the Accounts.cgi Affiliate Page (found under Accounts.cgi (Other) in admin.cgi Templates), change any instances of [username] to <<USERNAME>>
  2. In the included Accounts.cgi Header template (templates/accounts_header.tpl), copy the JavaScript to your header to prevent a JavaScript error.
  3. Examine the Accounts.cgi listings display page (templates/accounts_manage_display.tpl) to update the listings page to support a checkbox that can select/de-select all listings on the page.

  From v4.10:

  1. References to "functions.js" have been erased from all signup templates and the accounts.cgi payment template.
  2. All search templates have access to the username of the referring affiliate as <<AFFILIATE>>.
  3. The multiple listing upload template (templates/accounts_manage_multadd.tpl) has been changed to delete two unneeded hidden form elements for Excel uploads.
  4. There are 5 new templates, 4 of which are used as header/footer templates in smartsearch.cgi and signup.cgi, and the other is an e-mail you will receive to notify you when a user makes a deposit.
  5. In the
• Make sure that you CHMOD 777 any templates you upload, so that you can edit them from admin.cgi later.
• Create a directory named "misc" in your "keywords" directory and set its permission to 777. Adding this directory will prevent problems with non-alphabetical keywords
• Update the R3N3 Payment Gateway Script to v1.05

General Instructions:

• Send people to signup.cgi to create an account, to accounts.cgi to add listings (and more), and smartsearch.cgi to perform searches. All output templates for these scripts can be changed via admin.cgi
• Run admin.cgi to approve submissions, add money to user accounts, and more.

• If you want to include bidded listings on your site somewhere, use the following SSI tag:

<!--#include virtual="/path/to/cgi/include.cgi?keywords=your_keyword&show=show_number" -->

Replace your_keyword with the keyword you want to show listings for. Replace show_number with the number of listings you want to display (default is 5).

This will display the listings according to the templates for include.cgi. See admin.cgi to change these templates.

If you want to use a Javascript tag instead of SSI, just add "&java=1" to the end and put it in a tag like the following:

<script src="http://www.mysite.com/include.cgi?keywords=your_keyword&java=1"></script>

• If you want to display the top keywords searched for this month, put the following tag. Replace pop_number with the number of keywords you want to display.

SSI: <!--#include virtual="/path/to/cgi/include.cgi?pop=pop_number" -->

JavaScript: <script src="http://www.mysite.com/include.cgi?pop=pop_number&java=1"></script>

• All information displayed with the include.cgi file can be used by your affiliates too (and they will get credit). For example:

SSI: <!--#include virtual="/path/to/cgi/include.cgi?keywords=your_keyword&username=my_username" -->

Java: <script src="http://www.mysite.com/include.cgi?keywords=your_keyword&username=my_username&java=1"></script>

• You can provide affiliates with a database style print out of your search results if you want. This can be used by programmers who want to include your search results in their search engine script. The search listings will be printed out one per line, in tab delimited format (data is seperated by tab spaces). Just tell them to use the following URL:

  http://www.yourdomain.com/cgi-bin/include.cgi?keywords=your_keywords&username=your_username&db=1

• You can also display the results in XML. Simply use the following URL:

  http://www.yourdomain.com/cgi-bin/include.cgi?keywords=your_keywords&username=your_username&xml=1

• If you also want to include external results (e.g. Searchfeed, Dmoz, etc.) via include.cgi, use a tag like the following:

  http://www.yourdomain.com/cgi-bin/include.cgi?keywords=your_keywords&username=your_username&external=1

• Have your affiliates refer new advertisers with a link of the form:

  http://www.yourdomain.com/cgi-bin/signup.cgi?referrer=username

• If you want your keywords to be in organized in categories, put something like the following inside the directories.txt file:

tech/hardware/computers/computer accessories/monitors
tech/hardware/computers/computer accessories/printers
tech/hardware/computers/computer accessories/scanners
tech/hardware/computers/ibm
tech/hardware/computers/compaq
tech/hardware/computers/mac
tech/hardware/laptops
tech/hardware/keyboards
tech/software

Now I'll explain... You can put as many directories as you want. You don't have to list the main directories, just the deepest sub-directory. In the example above I don't need to put:

tech
tech/hardware
tech/hardware/computers
tech/hardware/computers/computer accessories
tech/hardware/computers/computer accessories/monitors

I only need to put:

tech/hardware/computers/computer accessories/monitors

The CGI can figure out by itself the directories above that one. Also, DO NOT repeat any directories in another group, the CGI will just match the keyword to the first one it finds. For example, if you have:

software/downloads
music/news
music/mp3/downloads

The "downloads" is repeated, that's not good. What you should put is something like this:

software/software downloads
music/news
music/mp3/mp3 downloads

You wouldn't get an error message if you didn't do this, but the CGI would simply take the first directory it finds. In the above example (the red one), if someone searched for "downloads", the CGI would tell them they are in the "software/downloads" category.

If this was too confusing, you will figure it out as you test the directories out :)

• If you want to let your visitors pick which external search site's results should be used, you can give them a form like this:

Dmoz.orgMSN.comSearchFeed.comAltaVista.comRevenuePilot.comNone

The HTML for this is:

<form method="POST" action="smartsearch.cgi">
<div align="left"><p><input type="text" name="keywords" size="10"><select name="crawlsite"
size="1">
<option selected value="1">Dmoz.org</option>
<option value="2">MSN.com</option>
<option value="3">SearchFeed.com</option>
<option value="4">AltaVista.com</option>
<option value="5">RevenuePilot.com</option>
<option value="0">None</option>
</select><input type="submit" value="Search" name="submit"></p>
</div>
</form>

This is done by passing on the variable "crawlsite" with the appropriate number. 1 is Dmoz.org, 2 is MSN, etc. and 0 (zero) is none (no external search results). If you don't use this type of form, the default one will be used (as set via admin.cgi).

• If you want to allow people to upload Microsoft Excel Spreadsheets to submit search listings, you will need to install the Spreadsheet::ParseExcel perl module on your server. Ask your web host to install it if you don't know how. Important note: this module requires the OLE::Storage_Lite module to work. And THAT module requires the following modules: IO::Handle (included in IO), IO::File (included in IO), and IO::Scalar. I know that's a lot of modules, and I hesitated adding the Excel feature to Smart Search because of all the modules required, but I figured you might still want this great feature. So it's up to you if you can and want to install the required modules. You can find perl modules here, and module installation instructions here. Good luck!

Note: Generally this CGI and its data files should not use up too much space on your server, except for the click logs which might add up if you have a heavily used site. For most people 5 MB would be more than enough for this CGI.

If you experience any problems with the results pulled from any of the other search engines (LWP module feature), e-mail webmaster@smarterscripts.com

Special Notice to Resellers:

You can use this script on any site of yours, but if you sell one of these sites, you are required to FIRST purchase a new copy for the new owner. If you don't, it's considered copyright infringement and we will prosecute any offenders. WE MONITOR EBAY.COM AUCTIONS, SO BEWARE. Reseller prices are very low, for more information, go to: http://www.smarterscripts.com/resellers.shtml

Support:

Go to http://www.smarterscripts.com/contact.shtml for support issues.


Check out http://www.smarterscripts.com for updates to the CGI.
Send suggestions for future versions to webmaster@smarterscripts.com