Project Name Retriever 2.0
Publication Name Installation Guide
Publication Date December 2005
Maintainer mlesswing@realtors.org
Installation Guide Table of Contents
3.0 Install the Distribution
Installation of this version of the package is significantly different than those found in earlier versions. Do not use older installation procedures with this version because they will not work.

From the DISTRIBUTION_DIRECTORY, locate the DISTRIBUTION_FILE .

Unix and Mac users should issue the command: tar xvzf {DISTRIBUTION_FILE} Windows users should "unzip" the file like this: pkunzip {DISTRIBUTION_FILE} This process creates the INSTALLATION_DIRECTORY . The layout of this directory contains the following important elements: Execute the appropriate installation script for the operating system you are using. This would be either install.bat (for Windows) or install.sh (Mac OSX, Unix or Linux). The script creates three directories:
  • combined sources directory - A directory containing definitions of all data connections to that are actually combinations of two or more sources referred to in other parts of this documentation as COMBINED_SOURCES_DIRECTORY.

  • displays directory - A directory that contins other "display" directories that you will be referred to in other parts of this documentation as DISPLAYS_DIRECTORY.

  • sources directory - A directory containing definitions of all data connections to MLS servers referred to in other parts of this documentation as SOURCES_DIRECTORY.
Now configure you web server to recognize the INSTALLATION_DIRECTORY . You will be able to specify a more user-friendly location to make the URL look nicer to consumers. We will call this the SITE_URL .

Files found in the root directory of the SITE_URL include index.php and admin.php. The index.php file is the Consumer Interface and admin.php is the Administrative Interface . The Administrative Interface allows you to control how the package output looks to consumers and to access the system documentation.

You should consider removing the Administrative Interface from the public site after configuration is complete. Any consumer reading this documentation could figure out how to invoke it, giving them access to the "look and feel" of your website as well as your account and password for the MLS.

The most important directory to protect is the sources directory. It includes account names and passwords given to you by your MLS to access their server.

Examples of a couple of web servers are provided below. These samples should not be considered authoritative. You should consult manuals or seek professional assistance before deploying this package in a production environment.
Apache (UNIX):
Assuming you installed the distribution into the /work/projects/retriever-2.0 directory, add the following to the http.conf configuration file:
# # Retriever 2.0 # Alias /retriever "/work/projects/retriever-2.0"
After this change is made, the http server should be restarted. If the server was configured to serve localhost (unlikely, unless you are in a test-only environment), the following URL (SITE_URL) would access the RETS client:

http://localhost/retriever/index.php
Apache (Windows):
Apache for Windows includes PHP modules by default. The configuration is similar to the UNIX version.

Add the following lines to the httpd.conf file usually found in %APACHE HOME%\Apache\Conf. %APACHE HOME% can be many places based upon your Apache version and other installed software. For example, previous to Apache 1.3.x, the typical installation directory was C:\Apache, however, the current installation directory defaults to C:\Program Files\Apache Group\Apache. If you are using the Oracle 8i or 9i application server, Apache will be found in %ORACLE HOME%\Apache.

The following additions to the http.conf file will configure the package. In this case, the virtual address of "retriever" corresponds the the INSTALLATION_DIRECTORY of C:\RETS\retriever-2.0:
# # Retriever 2.0 # Alias /retriever "C:\RETS\retriever-2.0"
Add the following line to the ScriptAlias section of the Apache Configuration file. The directory should be the same as the directory where php.exe was installed.
ScriptAlias /php/ "C:/php/"
Add the following to the AddType section of the Apache Configuration file.
AddType application/x-httpd-php .php AddType application/x-httpd-php-source .phps
Add the following to the Action section of the Apache Configuration file.
Action application/x-httpd-php /php/php.exe
Add " index.php" to the end of the "DirectoryIndex index.html" line.

IMPORTANT NOTE ON PHP TEMP FILES

Create the directory C:\tmp if it does not already exist and grant read and write privileges to the PHP user on this directory. This directory will contain the RETS metadata cache files. If C:\tmp is not created, PHP will try to place temp files in default Windows temp directories. Often, these directories deny certain permissions that cause caching to fail and they should not be used if if possible.
IIS (Windows):
If you used the PHP Windows Installer and selected IIS for your Web Server, the configuration for PHP with IIS is complete. Please follow the instructions for IIS Configuration with PHP.

The following additions to the http.conf file will configure the package. In this case, the virtual address of "retriever" corresponds to the INSTALLATION_DIRECTORY of C:\RETS\retriever-2.0.

Retriever uses a virtual directory under the existing Default Web Site. To create a virtual host under IIS, open the IIS Console, right click on Default Web Site and click New-Virtual Directory. Configure the virtual directory using the IIS wizard. The virtual directory MUST be named:
retriever
The root directory of the virtual directory should be:
%RETS INSTALLATION DIRECTORY%\php
where the %RETS INSTALLATION DIRECTORY% is C:\RETS\retriever-2.0.

After successful creation, right click on the virtual directory home and choose Properties. Under the Documents tab, add "index.php" to the list of default files and move this entry to the top of the list.

IMPORTANT NOTE ON TEMP FILES

Create the directory C:\tmp if it does not already exist and grant read and write privleges to the PHP user on this directory. This directory will contain the RETS metadata cache files. If C:\tmp is not created, PHP will try to place temp files in default Windows temp directories. Often, these directories contain certain permissions that cause caching to fail and they should not be used if possible.

Errors and solutions for installing and using PHP under IIS are detailed on the PHP Project site located at:

http://www.php.net.
OmniHTTPd (Windows):
If you used the PHP Windows Installer, the configuration for PHP is a manual process best described by the Omni documentation.

RETS uses a virtual directory under the existing Default Web Site. The virtual directory can be named:
retriever
IMPORTANT NOTE ON TEMP FILES

Create the directory C:\tmp if it does not already exist and grant read and write privleges to the PHP user on this directory. This directory will contain the RETS metadata cache files. If C:\tmp is not created, PHP will try to place temp files in default Windows temp directories. Often, these directories contain certain permissions that cause caching to fail and they should not be used if possible.

Errors and solutions for installing and using PHP under OmniHTTPd are detailed on the Onmi Project site located at:

http://www.omnicron.ca.
Installation Guide Table of Contents