Introduction

This page contains the installation instructions for the GSA Do-It-Yourself Keymatches. All the appropriate files can be found in the zip file that is available in the downloads section.

Details

To have the Do-It-Yourself KeyMatches Software running with Google Search Appliance, you will need MySQL, Apache and PHP. For your convenience, we suggest you to use XAMPP which is an easy to install Apache distribution containing MySQL, PHP and Perl. XAMPP is very easy to install and to use - just download, extract and start. XAMPP is free of charge. We recommend you to use XAMPP. If you already have MySQL, Apache and PHP installed, you can use that too.

==> NOTE: Google does not warranty or in any way guarantee the reliability of this code. Use it at your own risk.

Step 1

Go to http://www.apachefriends.org/en/xampp.html and select XAMPP for your Operating System (For example, "XAMPP for Linux", "XAMPP for Windows", "XAMPP for Mac OS X", "XAMPP for Solaris"). XAMPP is free of charge.

If you select "XAMPP for Windows", in next page you will have the option of downloading XAMPP for Windows using three different variations: Installer, ZIP archive and Self-extracting ZIP archive. Also, you will find three different packages - XAMPP Windows 1.6.3a(Basic package), Devel Package 1.6.3 and Upgrade Package 1.6.3a.

If you like to use the ZIP version, just click on Zip under Basic Package and save the zip file (xampp-win32-1.6.3a.zip ) on your C drive under the directory C:\. Make sure to extract XAMPP in a top level folder like c:\xampp . You need a single-xampp folder like c:\xampp(apache, mysql etc. sub-directories and files will be under C:\xampp\).

If you have IIS or any other Web Server running on your Windows machine, please stop those services first (Go to Control Panel, click on "Administrative Tools", click on "Services", select "IIS Admin", right click on "IIS Admin" and stop the service.) This will release the port 80 and 443 for Apache to use.

Alternatively, if you like Apache to use different port for Apache other that 80 and 443, go to the directory C:\xampp\apache\conf, open httpd.conf file and search for the line Listen 80. Change 80 to 81. (If Port 81 is used by another service, select an available port). Also search for the line ServerName localhost:80 and change 80 to 81.

Next edit the file httpd-ssl.conf under the directory C:\xampp\apache\conf\extra. Open httpd-ssl.conf file and search for the line Listen 443. Change 443 to 444. (If Port 444 is used by another service, select an available port). Also search for the line ServerName localhost:443 and change 443 to 444.

Make sure MySQL and Apache are running. If either MySQL or Apache is not running, go to C:\xampp and click on xampp-control. Select Apache and click OK to install the Apache service. Select MySQL and click OK to install the MySQL service. Start Apache and MySQL.

(NOTE: If you like you can also install MySQL, Apache and PHP individually from web, and do your setup. These three are available free of charge. We recommend Apache HTTPD 2.2.4, MySQL 5.0.45 or 5.1, PHP 5.2.3).

Open the URL http://localhost, select your language, click on Status and verify that all services(MySQL database, PHP, HTTPS, CGI, SSI) are running. Now you should make sure the XAMPP administrative console is password protected. Click on Security. On next page, click on the URL http://localhost/security/xamppsecurity.php . Under "XAMPP DIRECTORY PROTECTION (.htaccess)" section, enter User name and password. You can check the box "Safe plain password in text file?" Then click on "Make safe the XAMPP directory". If password set is successful, you will see the following message - SUCCESS: The XAMPP directory is protected now! All personal data was saved in the following file:

C:\xampp\security\xampp.users
C:\xampp\htdocs\xampp\.htaccess
C:\xampp\security\xamppdirpassw

(For example, User name and password can be admin and welcome respectively). Next time if you like to access http://localhost, you will have to enter above User name and password.

You need to set a "root" password in MySQL. Go to the C:\xampp\mysql\bin directory on console and enter: C:\xampp\mysql\bin\mysqladmin -u root password secret (for example, secret is "root" password).

Then you need to update the password for PHPMyAdmin. Go to the directory C:\xampp\phpMyAdmin and open the file config.inc.php . Search for the following lines and make sure in each of these lines variables are set to correct values. These lines should be exactly as follows -

$cfg['Servers'][$i]['user'] = 'root'; // MySQL SuperUser
$cfg['Servers'][$i]['auth_type'] = 'http'; // HTTP MySQL authentication
$cfg['Servers'][$i]['password'] = 'secret'; // Set the correct root password. In this case the root password is secret.

Edit and save the above file config.inc.php.

Start XAMPP Control Panel by changing to directory C:\xampp and clicking on xampp-control. Stop both Apache and MySQL services. Wait for 10 seconds and start Apache and MySQL services again.

Remember if you like to access http://localhost page, you will use the XAMPP DIRECTORY PROTECTION User name and Password(admin, password). If you like to access phpMyAdmin( http://localhost/phpmyadmin), use the MySQL user name and password(root, secret).

You can open the URL http://localhost, click on Status and verify that all services(MySQL database, PHP, HTTPS, CGI, SSI) are running.

Step 2

Download the do-it-yourself-keymatches zip file from http://code.google.com/p/diykeymatches/ . Extract the above zip file under the directory C:\xampp\htdocs\ . You will see the sub-directory do-it-yourself-keymatches under C:\xampp\htdocs\ . If the sub-directory do-it-yourself-keymatches is not created directly under C:\xampp\htdocs\, move the sub-directory do-it-yourself-keymatches under C:\xampp\htdocs\ . The sub-directory do-it-yourself-keymatches contains all files.

Step 3

Database Creation:

Go to the directory C:\ on console. Run the following command:

C:\xampp\mysql\bin\mysql -u root --password=secret < C:\xampp\htdocs\do-it-yourself-keymatches\createdb.sql

The above command will create the database "diy" and the table name WikiResults in "diy" database.

You can go to MySQL interactive session by running the command: C:\xampp\mysql\bin\mysql -u root --password=secret

You can then execute MySql commands to see the structure of your database and table. Look at http://mysql.com to learn more about MySQL commands. Alternatively, in your browser go to the page http://localhost/phpmyadmin/ and you will be able to see the structure of your database and table.

If you like to give remote access to database, make sure to follow the following procedure:

Go to Windows Control Panel. Click on Windows Firewall. Select the tab Exceptions. Under Programs and Services, if you already have MySQL entry , double click on MySQL and make sure Port Number is 3306. Click on "Change Scope" and verify you have the correct box checked so that the database can be accessed from the trusted computers only. If you do not have any MySQL entry under Programs and Services, click "Add Port", enter (Name: MySQL, Port number: 3306), check TCP, click on "Change Scope" and verify you have the correct box checked so that the database can be accessed from the trusted computers only and finally click OK.

Create a database user. Go to MySQL interactive session by running the command:

C:\xampp\mysql\bin\mysql -u root --password=secret

Run the SQL query:

grant all on diy.* to 'tester'@'%' identified by 'test';

Here, user name is tester and password for this user is test. You can select your own user name and password. Then run the SQL query:

flush privileges;

Now an user can remotely connect to this database host using the following command:

C:\xampp\mysql\bin\mysql -h database_host_name -utester -ptest

Here, database_host_name is the name of the host where your MySQL server is running. This will take the MySQL interactive session. The user can run SQL queries such as "use diy" and "show tables".

CAUTION: It is generally a good to have the database accessible only from the local host machine and not remotely. The above SQL query "grant" provides read, write and delete to the user "tester" from any remote machine. You may decide what permissions you like to give to an user and whether the database host can be accessed from any remote machine. Look at http://mysql.com to learn more about database permission.

Step 4

Edit configuration file: Go to the directory C:\xampp\htdocs\do-it-yourself-keymatches and open the file diykeymatchesconfig.php . The content of the file is given below. Follow the instructions inside the comment to edit the variables.

/**

 * This variable baseURL simply declares the base URL where the various
 * Do-It-Yourself Keymatches files reside.  Edit this variable
 * when using to point to the right directory where you installed
 * this software. You need to replace xyz.google.com
 * (where xyz.google.com is the name of web server) with the name of your web server.
 */
$baseURL = 'http://xyz.google.com/do-it-yourself-keymatches/';

/**
 * Edit the lines below. You will need correct database hostname,
 * username, password. For example, in this case database hostname
 * is xyz, userid is mrabc and password is mypwd.
 * Database name is diy, but you do not need to change the database name.
 */
 
function getDIYKeymatchesDatabase() {
  $db =  mysql_connect(xyz', 'tester', 'test') or
    die('Could not connect: ' . mysql_error());
  mysql_select_db('diy') or die('Could not select database: diy');
  return $db;
}

/**
 * Edit the name of Google Search Appliance in the line below. For example,
 * in this case the name of Google Search Appliance is srchapp. Replace this
 * with the name of your Google Search Appliance.
 */
$gsaURL = 'http://srchapp/search?access=p&output=xml_no_dtd&' .
'client=default_frontend&proxystylesheet=default_frontend&q=';

/**
 * This variable controls the maximum number of Do-It-Yourself Keymatches
 * results that will be displayed on search result page. Currently, this is set to 5.
 * But you can change this value.
 */
$max_result = 5;

/**
 * In the line below, replace xyz.google.com with the name of your
 * web server.(Here, xyz.google.com is the name of web server)
 */
$vBottomLeft = 'http://xyz.google.com/do-it-yourself-keymatches/images/corner-bl.gif';
$vBottomRight = 'http://xyz.google.com/do-it-yourself-keymatches/images/corner-br.gif';

Caution: Edit the PHP file in a PHP editor and save the file.

Step 5

Edit Google Search Appliance Stylesheet: Login to your Google Search Appliance Admin Console. Click on Serving and then click on Front Ends. Edit the front end that you are using. Click on Edit and go to XSLT Stylesheet Editor.

Locate in your stylesheet the following consecutive lines of code -

<!-- **********************************************************************
 Logo template (can be customized)
     ********************************************************************** -->
<xsl:template name="logo">
    <a href="{$home_url}"><img src="{$logo_url}"
      width="{$logo_width}" height="{$logo_height}"
      alt="Go to Google Home" border="0" /></a>
</xsl:template>

Once you locate the above lines of code, insert the following lines of code below the above line </xsl:template> .

<!-- **********************************************************************
 Do-It-Yourself Keymatches template
     ********************************************************************** -->
<xsl:template name="diykeymatches">
    <!-- *** html_escaped_query: q = /GSP/Q *** -->
    <xsl:variable name="aqval">
      <xsl:value-of select="/GSP/Q"/>
    </xsl:variable>

    <xsl:variable name="ahtml_escaped_query">
      <xsl:value-of select="normalize-space($aqval)" 
        disable-output-escaping="yes"/>  
    </xsl:variable>

    <!-- Escape the quote for form INPUT field. -->
    <xsl:variable name="ahtml_quote_escaped_query">
      <xsl:call-template name="escape_quot">
        <xsl:with-param name="string" select="$ahtml_escaped_query"/>
      </xsl:call-template>
    </xsl:variable>

    <div id="momawiki">
      <link href="http://xyz.google.com/do-it-yourself-keymatches/diykeymatches.css.php"
            type='text/css' rel='stylesheet'></link>
      <script src="http://xyz.google.com/do-it-yourself-keymatches/diykeymatches.js"
              type="text/javascript"></script>

      <!-- For some reason, the script isn't picking up referrer, so we
           need to manually add the query as a URL parameter -->
      <xsl:text disable-output-escaping="yes">
        &lt;script src=&quot;http://xyz.google.com/do-it-yourself-keymatches/diykeymatches_loader.js.php?q=</xsl:text>
      <xsl:value-of disable-output-escaping="yes"
          select="$ahtml_quote_escaped_query"/>
      <xsl:text disable-output-escaping="yes">&quot;&gt;&lt;/script&gt;
      </xsl:text>

    </div>
</xsl:template>

In the above lines, replace xyz.google.com with the name of your web server (Here, xyz.google.com is the name of web server). Also, make sure the above links (http://xyz.google.com/do-it-yourself-keymatches/diykeymatches.css.php, http://xyz.google.com/do-it-yourself-keymatches/diykeymatches.js, http://xyz.google.com/do-it-yourself-keymatches/diykeymatches_loader.js.php) are working.

Next, locate in your stylesheet the following consecutive lines of code -

    <!-- *** Handle results (if any) *** -->
    <xsl:choose>
      <xsl:when test="RES or GM or Spelling or Synonyms or CT or /GSP/ENTOBRESULTS">
        <xsl:call-template name="results">
          <xsl:with-param name="query" select="Q"/>
          <xsl:with-param name="time" select="TM"/>
        </xsl:call-template>
      </xsl:when>
      <xsl:when test="Q=''">
      </xsl:when>
      <xsl:otherwise>

Once you locate the above lines of code, insert the following lines of code below the above line <xsl:otherwise> .

    <!-- *** Beginning of Do-It-Youself Keymatches *** -->
        <xsl:call-template name="diykeymatches">
        </xsl:call-template>
    <!-- *** End of Do-It-Youself Keymatches *** -->

Finally, locate in your stylesheet the following consecutive lines of code -

  <!-- *** Output results details *** -->
    <div>
    <!-- for keymatch results -->
    <xsl:if test="$show_keymatch != '0'">
      <xsl:apply-templates select="/GSP/GM"/>
    </xsl:if>

Once you locate the above lines of code, insert the following lines of code below the above line <xsl:if> .

    <!-- *** Beginning of Do-It-Youself Keymatches *** -->
        <xsl:call-template name="diykeymatches">
        </xsl:call-template>
    <!-- *** End of Do-It-Youself Keymatches *** -->

Save XSLT code.

You can open the file stylesheet_code.txt under the sub-directory C:\xampp\htdocs\do-it-yourself-keymatches . You will see the exact of sequence of lines in the file stylesheet_code.txt . Make sure to have the exact sequence of lines in your stylesheet.

Yo can also look at the stylesheet default_frontend_stylesheet.en.xslt under the sub-directory C:\xampp\htdocs\do-it-yourself-keymatches for the exact of sequence of lines.

Do-It-Yourself Keymatches Dashboard

Copy the URL http://xyz.google.com/do-it-yourself-keymatches/dashboard.php in your browser. Make sure to replace xyz.google.com with the name of your web server. You can use the Do-It-Yorself Keymatches Dashboard to monitor Recent Keymatch Additions, Recent Keymatch Deletions, Most Clicks and Stale Results. We also provided a search box to help you search URLs.

Troubleshooting

If you have difficulty to get your Do-It-Yourself Keymatches software working, please try the following steps - Copy the URL http://xyz.google.com/do-it-yourself-keymatches/ in your browser and press Enter. Here xyz.google.com is the name of the web server. If you do not get any response, this means your Apache server is not responding. Please make sure to restart your Apache web server.