2009-08-03
QPL Reference Manual

Warning! This page is in the process of being rewritten for QPL Version 6. It may still have references to QPL Version 5.

This section describes the server requirements and one-time set up procedures that must be done before a QPL web questionnaire can be deployed. (See the Deployment section for the steps that must be taken to install an individual questionnaire on the web server.) These instructions are divided into six categories:

  1. Apache
  2. PHP
  3. LDAP
  4. MySQL
  5. Perl
  6. QPL Server Setup Instructions

The discussion here presumes that the person who manages the web server (here called the "web server administrator") is not the same person who is administering a questionnaire project (here called the "questionnaire administrator"). This section is written from the web server administrator's point-of-view in terms of what must be done to support multiple questionnaire projects with multiple questionnaire administrators using the same web server.

The instructions here also presume that PHP and MySQL are already correctly configured on a web server. These instructions just list that changes that may be necessary to run QPL questionnaires from a standard PHP and MySQL installation.

Server Requirements

The requirements listed below are for the web server that will host the QPL questionnaire.

Linux Server Setup

While QPL web questionnaires should run under Windows and IIS servers, I have limited experience with that environment. (GAO runs Linux and Apache servers.) The discussion that follows will focus on Linux/Apache set up issues which may have parallels in Windows/IIS systems.

1. Apache

Each QPL project must be set up in its own directory on a web server. Your Apache configuration, of course, must be set up to make these directories browsable.

In addition, the Apache http.conf main configuration file must be set to recognize public requests for PHP files which have a .php file name extension and should, by default, display files called index.htm (the name used for QPL project home pages).

http.conf

...
AddType application/x-httpd-php .php .phtml .php4
...
DirectoryIndex index.htm index.html index.html
...

2. PHP

The QPL PHP programs have been designed to run under the default php.ini settings as of PHP version 4.2.0. You should implement QPL applications with the following two modifications, if you have not already done so as part of your general installation, to improve the security of the questionnaire web site.

register_globals

The register_globals directive should be set to "off." (This is the default value for the php.ini file beginning with PHP version 4.2.0.) For more information about the related security issues of this directive, see the PHP online documentation.

include_path

The QPL server setup script, setup.sh, will normally install the QPL configuration file, qpl_config.inc, into the default PHP include directory, /php/includes. You may specify another directory when running the setup program, but you must remember to update the php.ini file to add the new location on the include_path.

Later, when deploying individual projects, do not put copies of the qpl_config.inc file in the home location with the rest of the project files. These copies are potentially viewable by internet users and may not be configured correctly for your server. All of the projects on one server should share the same qpl_config.inc file.

error_reporting
display_errors

The error_reporting directive should be set to show all warnings, errors, and notices (E_ALL) and the display_errors directive should be set to "On" when you are building and testing your questionnaire web site. Though the QPL PHP programs should never cause any of these messages to be displayed, setting it to show all messages is recommended, especially if you will be modifying the standard QPL PHP programs, so you may discover any errors in your coding. The display_errors directive should be set to "Off," on your production web server as is recommended in the php.ini file comments.

Any errors that occur within the QPL system, such as a respondent attempting to log in using an expired account, will be displayed with a QPL Notice page and a copy of the error message will be added to the MySQL log table for the project.

php.ini

...
register_globals = Off
include_path = ".:/php/includes"
error_reporting = E_ALL
display_errors = Off
...

LDAP Respondent Authentication

If your organization uses the Lightweight Directory Access Protocol (LDAP) directory service, you can set up QPL questionnaire applications to use it to authenticate respondents when they login instead of using the QPL project's built-in user account table. When doing internal questionnaire projects, this can create an enormous time savings since you would not need to first create user accounts for the QPL project. In addition, the respondents use their regular user names and passwords to log in, which ensures that you can link the data you collect back to other agency or corporate information about the employees.

Before the QPL LDAP authentication function may be used, you will need to get and compile LDAP client libraries and update your php.ini file. (See the PHP web site for more information.)

Next, you will need to modify the QPL configuration file, qpl_config.inc, file with your organization's LDAP data structure (normally installed at /php/includes). (See 5. QPL Server Setup Instructions below.)

Individual projects can use the LDAP directory service by specifying the LDAP option on the QPL System Administrator's Default Project Settings page.

3. MySQL

No special configuration of MySQL is needed to run QPL-generated web surveys.

As mentioned above, care should be taken on (1) the set up and location of the qpl_config.inc file and (2) the QPL-generated survey SQL script so that the data base is created with the same user name and password as will be used when the application accesses the data base when running.

If you expect a lot of traffic to your web survey, you should also make sure that the number of concurrent sessions allowed by Apache are consistent with the number of concurrent logins allowed by the MySQL server. If Apache allows more sessions than MySQL, then respondents could get "Cannot connect to data base" error messages if all MySQL's connections are being used. If respondents were trying to submit their responses when this occurred, their responses (just for the page they were viewing) would be lost and they would need to log in again (the system would then start them at the same page again, but without any of their updated information).

Generally, it is better to run out of Apache sessions first because respondents' browsers will automatically retry to access the site, and thus, not lose any data unless these repeated attempts time-out.

You may set up a QPL application to use a MySQL database that is not located on the same server as the web site. See the readme.txt file in the server set up package (see #5 below) for information on how to modify the QPL configuration file to initiate an SSL handshake with MySQL.

4. Perl

The QPL email functions, which are used to send custom messages to respondents require sendmail and Perl 5 with additional Perl modules that let scripts communicate with MySQL databases.

5. QPL Server Setup Instructions

A setup script (setup.sh) is provided that does the one-time installation of files on the web server that are needed to run any number of individual QPL applications.

This script configures and installs

The setup files are packaged as a tar file called qpl5_server_setup_2004-08-30.tgz (date stamp may vary), which was copied to the questionnaire author's Windows computer when the QPL setup.exe file is run. The location varies according to which version of the QPL software was installed.

QPL Console Edition

C:\Program Files\GAO\QPL\qpl5_server_setup_2004-08-30.tgz

QPL HomeSite Edition

HomeSite 5.x...

C:\Program Files\Macromedia\HomeSite 5\qpl\qpl5_server_setup_2004-08-30.tgz

HomeSite 4.x...

C:\Program Files\Allaire\HomeSite 4\qpl\qpl5_server_setup_2004-08-30.tgz

Copy the tar file to temporary directory on your Linux server and then unpack it using

%> tar -xzvf qpl5_server_setup_2004-08-30.tgz

Instructions on running that setup.sh script are contained in the readme.txt file that is included in the package.

After successfully running the setup program, you will need to give the questionnaire author the MySQL user name and password that will be used by all of the QPL applications so that he can correctly configure his individual questionnaire applications to fit the settings you used on the server.

See Deployment for instructions on deploying individual projects on your server.