Introduction

This document describes the process of installing and configuring the SurveySolutions Enterprise Server for use on your Unix Web server. Please contact techsupport@perseus.com if you have any trouble with the configuration process.

Requirements

The SurveySolutions XP Enterprise Server scripts are CGI programs written for Perl 5.
In order to function properly, the following components need to be installed:

• Web server that supports CGI functionality.(e.g. Apache)
• A relational database.
  For additional information on database requirements, click here.
  (currently we support Oracle, DB2, and MySQL)
• Perl version 5.0 or higher.
• CGI, GD, and DBI Perl modules.
• Appropriate DBD driver for your database.

Additional Requirements

• A C language compiler
• The graphing library libgd, version 1.8.3 or higher.

For more detailed help on configuring Perl click here.

Steps

There are three main steps to setting up the Enterprise Portal:

1. Installing the software on your server.
   
2. Configuring an Alias. (Apache)
   
3. Running the configuration utility.

Installing the software on your server

1. Copy the files to your server. This can be accomplished using FTP or other means such as Samba.
   
   
2. Log into the server as root.
   
   
3. Move the server files to your web servers cgi-bin (i.e. /home/httpd/cgi-bin).
   
   
4. Create an empty file named perseus.conf in your cgi-bin

You will need to change the ownership of the configure program to the user that your web server runs as using the chown command. For example:

    shell> chown webuser:webgroup pdcconfigure5.pl

You will also need to change permissions to make the configure program executable using the chmod command. For example:

    shell> chmod 755 pdcconfigure5.pl

Alias Configuration

Apache

1. Open the http config file usually in /etc/httpd/conf/ (commonhttpd.conf or httpd.conf)
2. Find the section where Aliases are configured (usually #Aliases:)
3. Assuming your server root is /home/httpd/. Add the following aliases:
   /pdctsv/ /home/httpd/pdctsv/
   /pdcimages/ /home/httpd/pdcimages/
   

Running the configuration utility

After all of the scripts have been installed you should be able to access the install script through a web browser.

   Apache Server: http://Your Web Server/cgi-bin/pdcconfigure5.pl

If the page reports a server error click here.

The first page of the install script allows you to configure parameters that the rest of the scripts need. The script pre-fills with common default values but you should override with your servers setting.

The second page will allow you to set parameters to connect to your database. When you click the Test Connection button it will test the connection and write the default tables Perseus' uses to track surveys in your database.

You should now be able to access the front door to the Portal:

    Apache Server: http://Your Web Server/cgi-bin/pdcportal5.pl

Appendix A: Perl Configuration Help

You can obtain the latest release of the Perl modules from:
http://www.perl.com/CPAN-local/index.html
http://search.cpan.org/

Normally, if you already have Perl installed, you can use the command line interface to CPAN to install the modules. You can launch an interface to CPAN by typing the following:
    shell> perl -MCPAN -e shell

To install CGI:
    cpan> install CGI

You will need to install the graphing libraries zlib, libpng, and libgd if they are not aleady installed. These libraries must be installed correctly before the GD perl module is installed. For more information on this process, click here.

To install the graphics module:
    cpan> install GD

To install the database interface:
    cpan> install DBI

Then install the appropriate driver for your database:
Note: Please see Appendix B for more information about database configuration.
    cpan> install DBD-Oracle

Appendix B: Relational Databases

If your database product resides on a separate machine than that of your web server, you may need additional, vendor specific networking libraries. In this case your web server will in essence become a "client" to the database server. The DBD driver modules assume that these libraries are in place and have been tested for remote connection. The DBD module installation process will likely fail if these libraries are missing or improperly installed. Please consult your database administrator or database vendor for more information about these networking libraries. For your convenience, we have listed the commom requirements for the various DBD modules to install correctly.

Oracle - SQL*Net or Net8.

DB2 - DB2 Application Development Client.

Appendix C: Installing the Graphics Library

The Enterprise Portal requires the libgd graphics library, version 1.8.3 or higher, for dynamic image generation.

Package Installation

Solaris - There are libgd packages for most sparc versions of Solaris

• Solaris 2.3 SPARC
• Solaris 2.4 SPARC
• Solaris 2.5 SPARC
• Solaris 2.51 SPARC
• Solaris 2.6 SPARC
• Solaris 7 SPARC32
• Solaris 8 SPARC32

Installation from Source

If one of the above packages does not work for you, then you can procede with the standard install procedure described below to install libgd from the source.

zlib

The zlib compression library can be acquired from ftp://ftp.freesoftware.com/pub/infozip/zlib/zlib.tar.gz. This is a link to the latest version. Download the archive and extract it. Read the installation documentation and the license. On most systems (Solaris is an exception) you will not have to build the zlib library if you don't want. When you build libpng, it incorporates the source files rather than the actual lib files. If you choose to build and install zlib (or your system requires that you do) Then do the standard install procedure:

	$ ./configure
	$ make
	# make install (as root)

libpng

Installing libpng is a little more complicated. You can acquire the latest version from http://download.sourceforge.net/libpng/. Look for something like 'libpng-x.x.x.tar.gz', where x.x.x is the newest (i.e. highest) version number. Download this and extract it. Read the installation documentation and the license. You need to have the zlib, that you just uncompressed, on the same level as the libpng directory and they should both be named without their versions. Your directory structure should look like this:

	|
	+- zlib
	|
	+- libpng

Something like this should do it, but may differ from system to system. You'll have to remove the archive before doing this (rm *.tar or rm *.tar.gz depending on your tar version). You should choose one of the makefiles in the libpng/scripts directory according to your system (e.g. scripts/makefile.linux for Linux or scripts/makefile.sunos for Solaris).:

	$ mv zlib* zlib
	$ mv libpng* libpng
	$ cd libpng
	$ cp scripts/makefile.stf Makefile
	$ make
	# make install (as root)

libgd

Installing libgd should then be straight-forward. Download the latest version from ftp://ftp.boutell.com/pub/boutell/gd/. Again, it will look something like 'libgd-x.x.x.tar.gz', where x.x.x is the newest (i.e. highest) version number. Download this and extract it. Read the installation documentation and the license. Read the notes in the Makefile for more information. You can then build the library with the standard:

	$ make
	# make install (as root)

Appendix D: Finding Perl

We ship the scripts with the first line set to the following:
    #! /usr/local/bin/perl

The system uses this information to look for the Perl interpreter. If your copy of Perl is installed to a different location you will need to change this before proceeding to the next step. On Unix you can find where Perl is installed in your system by typing:
    shell> which perl

After determining the path, open the script named pdcconfigure5.pl in an editor and change the first line to reflect this value. Then you should be able to run the configure script in a browser.

Appendix E: Helpful Links