homefeaturesDOCUMENTATIONpricingcontact us
technical documentationCATI documentationcookbookrobot

Appendix B

Installation instructions

Server software requirements

CallWeb needs the following to be installed on the server:

  • Perl 5 (including the following modules: CGI, CGI::Carp, DB_File, DBI, Fcntl, File::Compare, File::Copy, File::Path, FileHandle, IO::Socket, locale, LWP::Simple, Net::FTP, Net::Telnet, POSIX, Time::HiRes, Time::Local, SOAP::Lite 1.08, Encode)
  • MySQL 4 or better
  • Berkeley DB
  • a Web server (tested with Apache 2 with mod_unique_id enabled)
  • Sendmail
  • (for dialer and robot operations) Asterisk, version 1.2 or better (and the Asterisk::AGI Perl module)

Questionnaire designer client station

The following software has proven very valuable in editing CallWeb .scw files:

  • TextPad is an extraordinary pure-text editor which offers a whealth of functions. In particular, it supports syntax highlighting which makes CallWeb .scw files much more readable. A TextPad syntax highlighting file is available for CallWeb. Alternatively, some like Notepad++ for which CallWeb has a basic syntax highlighting file as well.
  • KeyText is a fabulous keyboard and hot key mapper. For example, one can paste an entire CallWeb question definition by simply pressing a predetermined combination of keys.
  • the free RGBtoHEX provides an easy way to select colours and identify the corresponding hex code.
  • the free Pixie is a colour picker: point to a colour on screen and Pixie tells you the hex, RGB, HTML, CMYK and HSV values of that colour (the hex value can be copied to the paste buffer using a keycoard key combination). ColorZilla, a free Firefox extension implements a similar function, but it is available only within Firefox.
  • there are hundreds of useful Web applications. For example, http://gradcolor.com/ creates a gradient which is very useful to find different intensities of a given coulour (do this by requesting a gradient from that colour to white).

File locations

System configuration file

The system configuration file and the project configuration files may contain several parameters controlling the in-depth behaviour of CallWeb and its default appearance. Some parameters must be supplied in one file or the other. Mandatory parameters are (parameters are case-sensitive):

The following are mandatory in CATI mode:

The following are mandatory to connect an Asterisk server to CallWeb:

The following are mandatory in robot mode:

The following are mandatory in connecting CallWeb to a predictive dialer:

In a project-specific configuration file, if the MySQL host is redefined, the following entry is mandatory:

Any pound instruction can be inserted in the system configuration file. All such pound instructions found in the system configuration file are inserted at the beginning of all questionnaires upon compilation. This means two things:

  • that system-wide defaults can be defined for any of the pound instructions, such as defining a default read access password for all projects with "# cwNav read password = some_password";
  • that such system default values can be overwritten inside any questionnaire by adding the same instruction (with other parameters) in the .scw file.

In addition, optional configuration parameters include (parameters are case-sensitive):

Automated tasks

A number of tasks are performed automatically by various programs once they are scheduled in the cron feature of a Linux server. They are as follows.

One last script cwbounces.pl is a special case. Its purpose is to intercept bounced messages and to update the CallWeb data base with an indication of this bounce. It is not located in the cron system but rather, it is called by Sendmail upon receiving bounced messages for the "bounces" address. A single instance of this program services an entire server and all instances of CallWeb installed on it. Here are detailed installation instructions:

  • put the cwbounces.pl script in the main utilities directory;
  • make cwbounces.pl executable (0755);
  • create a symbolic link cwbounces.pl in /etc/smrsh, pointing to the cwbounces.pl script in the utilities directory;
  • create a virtual user called "bounces.+*@domain.xxx" (adjust the domain name but leave the left side of this expression intact) and send its mail to the "bounces" alias;
  • create a mail alias "bounces" piped to the cwbounces.pl script (|cwbounces.pl).

Note that, for cwbounces.pl to work with a given instance of CallWeb on a server, the following directories and files must be readable by the user or the group "mail" (under which Sendmail runs):

  • the cwroutines.pl file ;
  • the etc directory;
  • the file usager???.conf file within the etc directory (the exact name of this file varies with each instance of CallWeb).

Daemon mode installation

The CallWeb daemon mode is three times as fast as the base mode. In daemon mode, CallWeb runs constantly in the server background, waiting for questionnaire page request files to be placed by cwx.cgi (which replaces callweb.cgi in daemon mode) in the spool directory. The CallWeb daemon processes these request files and places the HTML code of the next questionnaire page in the spool directory for cwx.cgi to display to the respondent.

To use the CallWeb daemon mode, follow the installation instructions and then call the questionnaires with the cwx.cgi module instead of the callweb.cgi module.

CallWeb daemon mode installation instructions:

  • the daemon mode requires that Apache loads the mod_unique_id module. Make sure that the following line is part of the Apache configuration:
    LoadModule unique_id_module modules/mod_unique_id.so
  • create the directory /var/spool/callweb and allow the Web server user to read from it and to write to it, for example:
    mkdir /var/spool/callweb
    chmod 0777 /var/spool/callweb
  • place cwx.cgi in the CallWeb installation master directory and allow the Web server user to execute it, for example:
    chmod 0755 cwx.cgi
  • create the /opt/callweb directory and place callwebd.pl as well as cwroutines.pl in it, for example:
    mkdir /opt/callweb
    cp callwebd.pl /opt/callweb
    cp cwroutines.pl /opt/callweb
    chmod 0700 /opt/callweb/callwebd.pl
  • create the /var/log/callweb directory and make it writable by the Apache user, for example:
    mkdir /var/log/callweb
    chown apache:apache /var/log/callweb
    chmod 0755 /var/log/callweb
  • place callwebd in /etc/rc.d/init.d and give it execution permission by root, for example:chmod 0700 /etc/rc.d/init.d/callwebd
  • request that the CallWeb daemon be started automatically upon server boot: chkconfig --add callwebd (see update-rc.d for Ubuntu)
  • to allow for daemon system updates, add the following line to the usagerXXX.conf file of one instance on the server (probably the most active production instance): update_daemon = 1. That CallWeb instance will control updates to the daemon system.
  • if the system is connected to a Munin server:
    • activate loglevels 1 (for problems) and 4 (for page creation) in /etc/callweb.conf (see below);
    • place the callwebd_pages script in the /etc/munin/plugins directory
    • make callwebd_pages executable
    • restart Munin with service munin-node restart

The CallWeb daemon is started, stopped and restarted with the command service callwebd start|stop|restart. The daemon status can also be probed with service callwebd status. When the "restart" or the "stop" command is issued, the CallWeb daemon waits until the request queue is empty before proceeding with stopping the daemon.

The CallWeb daemon configuration file is /etc/callweb.conf. The CallWeb daemon must be restarted for changes to the configuration file to take effect. Its content is as follows.

Multi-server configuration (CallWeb cluster)

Using the configuration files, it is possible to develop various server implementations of CallWeb. First, CallWeb can run on the same computer as the data base server if the "hote" parameter of the main CallWeb configuration file points locally:

hote = localhost

Another CallWeb server could use the same MySQL server by specifying a distant address for the "hote" in its main configuration file:

hote = 99.99.99.99

If the two CallWeb servers use the same "client" parameters in their main configuration file, both servers will "see" projects from both origins; that would be the typical setup of a multi-site CATI system. If they use different "client" parameters, each CallWeb server will only see its own projects.

Each project used in a multi-server configuration (also called "CallWeb cluster") should possess a # Master compilation server pound instruction to protect the integrity of the questionnaire files. Parallelism of the questionnaire files across servers is ensured by the # Copy questionnaire into instruction which dispatches a copy of the questionnaire (and an empty .scw file) to distant servers (there should be one such instruction for each of the distant servers in the CallWeb cluster which will use the questionnaire). This dispatching of questionnaires requires that a direct SSH connection (with exchange of public keys) exists between the servers; see below for the procedure.

In a multi-server configuration, re-compilation of the .scw script involving changes in data structure should be performed on the computer running the MySQL server. Otherwise, while the compilation will be performed and the data base adjusted if required, no backup of the data will be kept before modifying the data structure.

Note that, for bi-mode projects, the CATI CallWeb server must be the Master for compilation so that the .ccw file is correctly processed.

Exchange of public keys between servers

This procedure must be carried out only once per server connection. In brief, here is the procedure for the exchange of public keys between Linux servers:

  • in this procedure, "computer2" (the server, or the CallWeb computer which will receive the compiled CallWeb questionnaires) is the machine granting access to "computer1" (the client, or the computer which will send the compiled CallWeb questionnaires);
  • on computer1,
    • in a root shell, issue the following commands:
      • passwd apache [when prompted, enter a password for user apache]
      • usermod -s /bin/bash apache
      • chown apache:apache /var/www
    • enter a shell with the apache user ("su apache");
    • as the apache user, issue the following commands in a computer1 terminal window:
      • cd /var/www/
      • [if the .ssh directory does not exist] mkdir .ssh
      • cd .ssh
      • ssh-keygen -t rsa [accept the default options and do not specify a passphrase; this generates two files: id_rsa and id_rsa.pub]
    • in a root shell, issue the following commands:
      • chown root:root /var/www
  • copy id_rsa.pub from computer1 to computer2, in directory /var/www/.ssh (for example, via SFTP);
  • on computer2, in a root shell, issue the following commands:
    • usermod -s /bin/bash apache
    • cd /var/www/.ssh
    • cat id_rsa.pub >> authorized_keys
  • in a shell as the apache user on computer1, initiate an SSH connection and type "yes" when prompted; this needs be done once to accept the exchange of keys.