====== Running the Interactive Services Examples ======

**For Module**: EG-259 Web Applications Technology 

**Lecture**: [[eg-259:lecture15|Interactive Services]] 

**Written By**: Dr C.P. Jobling 

To run the examples you will need an installed Perl interpreter and a web server capable of running CGI and PHP scripts. The ''lamp-server'' package from Ubuntu [1] is a (L)AMP [(Linux) Apache MySQL PHP] "stack" that provides most of what you need in a single installable package. On windows, you can also use the Apache Friends XAMPP package that was installed earlier in the module.

Once installed, PHP and very simple Perl CGI scripts should work immediately. You simply start the Apache web server; in Windows [and the Mac?] there's a nice little control panel for this.  On Ubuntu Linux, the servers are started automatically. If you make any changes to the configuration files, you use this command line to restart Apache:

<cli>
$ sudo /etc/init.d/apache2 restart
</cli>

Windows users should note that the version of Perl that comes pre-installed with XAMPP for Windows is insufficient for running the CGI example that I described in the lecture. I would recommend that you install ActiveState's ActivePerl [3] which is a fully featured Perl distribution that has been specially designed to run well on Windows. If you prefer, Apache Friends provides an add-on package that provides a Perl that should be suitable for CGI programming [3]. However, as I have not tried it myself, I cannot vouch for it's suitability for applications other than CGI.

Once you have acquired and installed a suitable web server and Perl, you should configure the scripts that I have provided as described below. The scripts and documentation are in a zipped file you will find on the Blackboard site.

===== Customize the Perl CGI Script =====

The first line of the Perl CGI script ''cgi-bin/echo_params.cgi'' is the so-called "hash-bang" line which is set (for ActiveState's Perl as installed on my laptop) to:

  #!c:\Perl\bin\perl.exe -wT

Unless you also have a Perl interpreter installed at ''c:\Perl'', you will almost certainly need to change this. If you are using Linux/Unix and Perl is installed, the hash-bang line will probably need to be:

  #!/usr/bin/perl -wT

In Linux/Unix you can always find out where (or if) Perl is installed by issuing the command:
<cli>
$ whereis perl
</cli>

===== Configure deploy.bat for Windows =====

If you are working on windows, edit the batch file ''deploy.bat'' and change the line:

  set SERVER_ROOT=e:\xampp\lampp

to reflect your local situation (if you used the default installation directory for XAMPP on windows, you would replace ''e:\xampp\lampp'' with ''C:\xampp''). Now run ''deploy.bat'' either from ''cmd'' or by double-clicking ''deploy.bat'' from the file view.


===== Configure deploy.sh for Linux/Unix =====

On Linux/Unix (probably including Mac OS X), edit the bash-shell script ''deploy.sh'' and change the lines:

  SERVER_ROOT=/etc/apache2
  DOCUMENT_ROOT=/var/www
  CGI_BIN=/usr/lib/cgi-bin

to reflect your local situation. (Some examples for the servers I know are in the file commented out.) 

Now run deploy.sh as root:
<cli>
$ sudo ./deploy.sh
</cli>

===== What Does Deployment Do? =====

Whichever version you use, the deployment script first copies the contents of the directory ''htdocs'' into ''$SERVER_ROOT/htdocs'' and ''cgi-bin'' into ''$CGI_BIN/cgi-bin''. On the Linux version it then ensures that the HTML and PHP files added to ''$SERVER_ROOT/htdocs'' will be readable by the web server and the Perl CGI script in ''$CGI_BIN/cgi-bin'' will be executable by the web server. The second step doesn't seem to be required in Windows.

===== Testing Your Installation =====

When configured and installed, you should be able to open a web browser and navigate to http://localhost/beer_get.html. This should open the web form shown in the lecture. Submitting the form should execute the Perl CGI script with URI http://localhost//cgi-bin/echo_params.cgi, passing the form arguments as parameters in the first line of the GET request.

For your convenience, the other demos are:

  * Beer with POST request: http://localhost/beer_post.html 
  * Beer with PHP request (POST): http://localhost/beer.php 

If you are using the Firefox browser and have Firebug installed [5], you will be able to see the messages that are actually sent to the web server and returned by it.

===== Trouble Shooting =====

If any of the demos fails, the most likely reason will be file permissions. Check that the resource ''$CGI_BIN/echo_params.cgi'' is executable by the web server and also that the "hash-bang" line is correctly set to the full path of your installed Perl interpreter. The example PHP scripts with ''beer.php'' and ''echo_params.php'' need only to be readable by the web server.

Another possible problem, especially on Unix-based operating systems (Linux/Mac) may be due to line endings. Ubuntu provides a package that provides tools to correct this:
<cli>
$ sudo apt-get install tofrodos
$ cd /usr/bin
$ sudo ln -s fromdos dos2unix
$ sudo ln -s todos unix2dos
</cli>

Then change the line endings of the cgi-script:
<cli>
$ cd $CGI_BIN/cgi-bin
$ sudo dos2unix echo_params.cgi
</cli>

If these tips don't help, it would be worth noting the error message returned by the web server and looking into the server error log ''sudo tail /var/log/apache2/error.log'' for a hint about what might be wrong.

===== References =====

[1] Installing LAMP On Ubuntu For Newbies. URL: http://www.howtoforge.com/ubuntu_lamp_for_newbies.

[2] Apache Friends XAMPP. URL: http://www.apachefriends.org/en/xampp.html. 

[3] ActiveState ActivePerl (current version 5.8.9.826) is available from http://www.activestate.com/store/activeperl/download/.

[4] Apache Friends provides Perl and mod_perl for Windows as an add-on. Download from http://sourceforge.net/projects/xamppaddon/. 

[5] Mozilla Plugin Firebug. URL: http://getfirebug.com/.