tdg

Current Page: Documentation / Installing tdg

We recommend ActivePerl 5.6 (available from ActiveSTATE) and will refer to this distribution in this documentation.

tdg requires version 5.6 (or greater) of Perl. The following packages are also required: "LWP::Simple" (or "libwww-perl"); "Socket"; "CGI.pm" and "GDBM_File". Of these, only "GDBM_File" is not installed as standard with ActivePerl 5.6. REMEMBER: Modules, libraries and packages should be in Perl's "search path" to make them globally accessible to all scripts using Perl on that server.

The installation and maintenance of Perl packages, modules and libraries is easy with the "Perl Package Manager" which is installed as standard with ActivePerl 5.6. The procedure for installing the required packages under ActivePerl 5.6 & PPM is described below. For other installations you should refer to the documentation supplied with your Perl distribution.

Note: In order to run the PPM you will need to have either physical or Telnet access to the web-server that tdg will be installed on. You will also need to have the required operating system permissions (in most cases, your System Administrator or ISP would be responsible for maintaining Perl).

At the shell prompt (DOS) type: ppm

At the "ppm>" prompt type: query

This returns a list of all the installed packages on your server. Page through the list and you should find "libwww-perl" listed. If you are using ActivePerl 5.6 you won't see "CGI.pm" or "Socket" on the list, but they are installed. If you're really lucky you'll also see "GDBM_File", in which case you need do nothing else. In all likelihood though, you'll need to install "GDBM_File" so...

At the "ppm>" prompt type: install GDBM_File

PPM will respond with: install package 'GDBM_File?' (y/N)

Press "y" and PPM will respond with: Retrieving package 'GDBM_File'...

The PPM will then retrieve the module from an Internet repository and automatically install it. It will also display a message about where it has written the resulting file(s). Your Perl installation now consists of everything required to run tdg.

The tdg distribution consists of various files in the following sub-directories:

cgi-local	-	This directory contains the tdg applications ("tdg_library.pl", "tdg_admin.pl", "tdg_entry.pl" and "tdg_view.pl"), a CGI diagnostic package ("doctor.pl") and seven template files that govern the output of tdg at various stages ("*.template")
documentation	-	This directory contains all the documentation for tdg (in HTML format)

For the purposes of this documentation, we assume that you will use an FTP (File Transfer Protocol) client to copy the tdg files on to a remote web-server. If you have physical access to the web-server, then you can, of course, copy the files directly on to the server.

All the files that constitute a tdg installation (Perl files ("*.pl") and templates) should be uploaded as ASCII-type files when uploading them on to your web-server. If the Perl files are uploaded as binary-type files then the application will not run when executed.

Edit the first line of each Perl file ("*.pl") to reflect the physical path to Perl on your server (this is not required for "tdg_library.pl"). In the majority of cases this line will already indicate the correct path, but some servers will be configured differently. Check with your ISP or System Administrator for the correct path or, if you are able to Telnet on to the server, issue a "which perl" command and the server will return the path information you require. If you are installing tdg on a Microsoft Windows® NT server under Microsoft's "IIS" (Internet Information Server) web-server software then you do not need to edit this line (do not remove it though). If installing under Microsoft Windows® NT with any other web-server software ("Apache" for example) then you do need to edit this line

Upload all the files (Perl files and templates) to the CGI-enabled directory on the web-server (often called "cgi-bin", or "cgi-local")

Create a directory on the web-server called "database" This directory must be in the same path as your CGI directory (not inside the CGI directory).

i.e. if the path to the CGI directory is "/users/web/example_usr/cgi-bin/", then the path to the "database" directory must be "/users/web/example_usr/database/"

Adjust the file permissions on the web-server as follows: all Perl applications ("tdg_admin.pl", "tdg_view.pl", "tdg_entry.pl" and "doctor.pl") must have global read and execute permissions (it must be accessible and executable by anyone using your website). On a Unix server use "chmod 755" to set this. The "database" directory should have global read and write permissions (it must be accessible and writeable by anyone using your website). On a Unix server use "chmod 766" to set this. All the template files and "tdg_library.pl" require global read permissions only (they must be accessible by anyone using your website, but should not be executable, or writable). On a Unix server use "chmod 644" to set this

Test the application by accessing "tdg_admin.pl" in your web-browser (for example: "http://www.my-isp.com/cgi-bin/tdg_admin.pl"), click the "Configuration" button and change the options as required (please double-check that the "URL (Address) of Guestbook (Viewer)" and "URL (Address) of Guestbook (Data Entry)" addresses correctly represent your installation - tdg makes a guess at these, but they can be incorrect). Click the "Apply" button when you are finished.

At this stage, if everything is working correctly, you will be returned to the initial administration panel (where the "edit" and "delete" options are displayed). All you need to do now is add a link to your website that points to the "tdg_view.pl" application and your guestbook is up and running.

TIP: As soon as you have confirmed that tdg is working correctly, rename the "tdg_admin.pl" to something obscure (but memorable to you) - don't change the extension though, that should always be ".pl". This will ensure that anyone visiting your website who is familiar with tdg won't be able to access the administration module. If you have physical access to your web-server you can also use the the server's permissions to restrict access to the administration module (if not, then your ISP or System Administrator should be able to set this up for you).

If tdg isn't working at this point, check again that you have followed the installation procedure exactly as described here and test again. If you still encounter problems read "Troubleshooting".

http://www.perl.com/ (Perl)

http://www.activestate.com/ (ActivePerl)

http://www.cpan.org/ (CPAN - Comprehensive Perl Archive Network)

http://stein.cshl.org/WWW/software/CGI/ (CGI.pm website)

http://search.cpan.org/author/GAAS/libwww-perl-5.68/lib/LWP/Simple.pm (LWP::Simple website)

http://www.perldoc.com/perl5.6/lib/GDBM_File.html (GNU GDBM Database Documentation)