How to Install Chat Touring on Your Web Server

by Paul Burchard

Release Notes - 1.0 alpha5

Recent Changes.

Network communications are all via legitimate URLConnections now.
Synchronization has been reimplemented so that
- the server doesn't slow down as the log file grows, and
- initial segments of the log file can be removed for file system maintenance without affecting active clients.
However, the new logging format is not compatible with older versions of Chat Touring.
Long lines of text are automatically wrapped when displayed on each client.
The applet works recursively (you'd be surprised how many people try that ;-) and when revisited in the browser window's history stack.
Better URL detection.
Some simple user tracking (automatic <enter> and <exit> messages).
Hopefully NT-compatible now?

Bugs and Limitations.

The current release supports only HTTP polling connections. This approach has the benefit of passing through all firewalls. On the other hand, it has the disadvantage of imposing a heavier load on the server than the equivalent session-oriented connection.
The current release is designed to provide a modular "chat panel" that can be plugged into any applet, and through subclassing to allow modular text filters (like the current URL filter) to be plugged into the chat function. However, these features are not yet documented.
I'm working on reimplementing the chat functionality on the basis of the Shared Objects System (SOS) for Java^®, a distributed objects system optimized for multi-user interactive Web applications.

Portability and Requirements.

Client: Chat Touring requires the Java API at the JDK 1.0 level or higher, corresponding to Netscape 2.0 or higher. It also makes essential use of Netscape's FRAME feature.

Server: The Web server must support CGI/1.0 scripts written in Perl version 4 or higher. Chat Touring's Perl scripts use very few operating system-dependent functions.

License.

This is distributed under the GNU Library General Public License (LGPL), which allows you to use this applet and its classes in commercial products under certain conditions (such making any improvements to this code available for distribution under the same terms). The LGPL works especially well for Java applets.

Installation Directions

Download the appropriate server package and unpack the files into a directory available through your Web server:
- Chat Touring 1.0 alpha 4 (UNIX version)
- Chat Touring 1.0 alpha 4 (NT version)
Make sure your Web server is configured to execute the Perl programs (.cgi files on UNIX, or .pl files on NT) as CGI scripts.
For NCSA httpd and derivatives on UNIX, this is done by:
- turning on the ExecCGI option for the Chat Touring directory (or its parents), in the server's conf/access.conf file;
- adding a line AddType application/x-httpd-cgi .cgi to the server's conf/srm.conf file;
- editing the first line of each .cgi file, if your copy of Perl is not installed as /usr/local/bin/perl (e.g. SGI).
For Website and similar servers on NT, this is done by:
- moving the .pl files from the Chat Touring directory into the server's Perl CGI script directory;
- if the URL of the Perl CGI script directory on your server is not /cgi-bin/, editing the $cgiBase parameter in the express.pl script, and the value of the ChaTour.b parameter in the document chat.html.
Create a log file, and edit the update.cgi script to record its (absolute) location. The HTTP server process must have write permission on the log file, but for security reasons, the log file should not be accessible via HTTP.
Record the BASE URL of the Chat Touring directory as the $docBase parameter in the chat.cgi and express.cgi scripts (or the corresponding .pl scripts under NT).
Edit schedule.html to taste. Chat programs work better when there is a tour schedule that allows interested people to rendezvous. You can also edit index.html to taste, but please don't remove the copyright and credit notice (toward the bottom of the page). For example, you might place your organization's footer at the end of the page.
Test and enjoy! Please let me know about any bugs you encounter.

Troubleshooting Checklist

Try this list if your new installation is not working (e.g. no text shows up in the applet).

Check the server's error logs to see whether permission is being denied for CGI requests to the scripts as you've installed them. If so, look over your HTTP server configuration again.
Check the server's access logs to see whether the requests are being sent correctly, and to the correct location. The requests should look something like
```
GET /scriptdir/update.cgi?z=34&s=10&r=716&n=anon&i=hello HTTP/1.0
```
where /scriptdir is the URL on your server of the directory where Chat Touring scripts are installed, and .cgi is the suffix used for Perl CGI scripts in your installation. If this is wrong, recheck your configuration of express.pl and chat.html.
Check the log file you've set up to see whether input is actually being recorded. If not, the most likely reason is that the HTTP server actually does not have write permission on this log file (on some servers you may need to set both the ownership and permissions correctly to allow this).
In this version of Chat Touring, I don't know of any way that text can show up in the log file even though nothing appears in the applet. So hopefully this is the end of the checklist!

Development of Chat Touring funded in part by the Woodrow Wilson National Fellowship Foundation, a non-profit corporation whose mission is identifying issues in education at all levels, and administering programs which address them.