The Pedagogical Web Site

Process of installing the DREW software


For a simple installation of the DREW in version 1.2 (XML version), we provide an installer for your system :

This installer is java programs build by IzPack and can be used on any system with a java virtual machine.

If you don't find proper installer for your system, you must compile and install directly from the source distribution of the Drew
(file Drew-src.tgz - (1427 Ko) or file Drew-src.tgz (updated : 2005.09.08) - (7885 Ko)).

Contents

Software requirement

The Drew tools relie on the following software:

  • an Apache web server. The version does not really matter as it has successfully been tested on 1.3.X and 2.0.X series ;
  • a Perl interpreter version at least 5.6 ;
  • the XML and XSL libraries from xmlsoft.org ;
  • the Perl adapter to the XML and XSL libraries :
    • XML-LibXML-common,
    • XML-NamespaceSupport,
    • XML-SAX,
    • XML-LibXML,
    • XML-LibXSLT.
  • a JavaTm virtual machine. The Drew tools have been developed to work on a JVM version 1.1.8 or higher;

Perl and Apache are standard on the various Linux distributions. If you use the Gnome desktop environment, the XML and XSL libraries should also be installed. If you don't happen to have these pieces of software installed, you must have them installed as they are mandatory for the site to work properly.

This last point is not a requirement by itself but it is strongly advised that you use a web browser which does conform to W3C recommendations. Browsers such as those from the Mozilla family are browsers of choice as they do respect the standards. Moreover this is free software. Internet Explorer, even in the version shipped with Windows XP actually does not conform to these published standards (even if Microsoft claims it does).

Installing the Drew tools

Drew tools work on the principle of a client-server protocol. Both are installed at the same time and both may work on the same machine but this last point is not mandatory. The latest version of Drew is able to work through a proxy/firewall and even without a server (standalone mode).

Depending on the platform you want to install the tools to, you have to choose different types of installation.

  • If you install for Windows, the preferred way is to use the binary package through the IzPack installer -- See this section for details.
  • If you install on an Unix-like operating system, the best method is to build and install the Drew tools from source code. To do so, refer to this section. Please note that Mac-OS X actually is an Unix-like OS.

1. Install from a binary package (installer)

As an overview we can say that we are going to use an automatic installer build using the IzPack free software. This installer may be run on every OS running Java.

Download the 'DrewInstaller.jar' file on the computer you want Drew to be installed and launch it (double-click on it or use the command line 'java -jar DrewInstaller.jar').

Follow the instructions and you're done!

Note : this step may be duplicated as many times as needed on several different computers.

2. Install from source

2.1. Install for an Unix-like OS

You first need to get the source tree, but read the section to this end before doing this. Once the section read and the archive downloaded, uncompress it in a place of your choice.

Copy the file 'drew.conf.dist' in the scale/Drew/Install directory to 'drew.conf' in the same directory.

Edit this configuration file, 'drew.conf', and modify it according to your needs. This means the place you want Drew tools to be installed on your file system (documents and scripts), the relative URI1 in your web server tree and the location of the Perl interpreter (the full path is needed).

Using various Linux distributions, and various OSes we have found that web server files are often located in the same directories. There are two main predefined layouts :

  • /var/www/ with subdirectories for documents named html or htdocs and scripts in cgi-bin.
  • /home/httpd with, usually a subdirectory named htdocs for documents and the same cgi-bin for scripts.

On Mac-OS X, the default Apache installation proposes the following directory layout :

  • /Library/webserver/Documents for the HTML files, and
  • /Library/webserver/CGI-Executables for the scripts.

The main Apache configuration file can be found in '/etc/httpd/httpd.conf'.

The preferred way, is to use the first layout with a Drew subdirectory in each of the html and cgi-bin directory. Of course, you can use which ever you want to suit the layout of your system or even, use another, completely different layout. The key point to keep in mind is that your web server must be able to access this installation.

Here is a list of variables of the 'drew.conf' file you need to set and some comments about each of them (the file contains several examples for well know installation types):

  • $documents
    absolute path of the directory where the DREW documents must be installed to be accessed by your web server.
  • $http_documents
    URI where the Drew documents can be accessed from a web browser. This must be an absolute URI, server wise (begin with a '/'), and must not contain the name of the server, nor http://.
  • $scripts
    absolute path of the directory for the Drew scripts. It is safe to give the same value as $documents, depending on your directories layout.
  • $http_cgi
    URI where your Drew scripts can be accessed from a web browser. This must be an absolute URI, server-wise (begin with a '/'). It is safe to give the same value as $http_documents, depending on your directories layout.
  • $auth
    absolute path of the directory where you want to install authentication files for the Drew administrative mode. It is safe to give the same value as $documents, depending on your directories layout.
  • $perl
    the absolute path of your Perl executable can be found (ie. /usr/bin/perl, /usr/local/bin/perl, C:/Perl/bin/Perl.exe, ...)

Edit the header of the configure file by giving once again the location of the Perl interpreter. Launch the configure Perl script by issuing the ./configure command. This program creates a Makefile file.

Execute the make command to process the Makefile and compile the Drew tools.
Note : there is not need of being root to execute the make process.

Execute the command 'make install'.
Note : you need to have the correct rights to write to the destination directory to install the software. This step may require you log as root.

To access the Drew installation, open the html page from a browser at this URI :

http://myServer/myPath/Drew/

replacing myServer and myPath by the correct values.

2.2. Install for Windows familly OSes

Installing from sources on a Windows OS may be tricky. The problem is, there is no 'make' command and no real shell to execute scripts.

If you still want to try to do it, you have to reproduce each step by hand. For this to work, read the scripts and try to understand the 'Makefile' file.

However, the java compilation phase should not be a problem.

3. Final words

When using Drew for the first time (or whenever the Drew server has been shut down) you must start the Drew server. You must not do this as root. You must use the web interface, in the Administration part of the site. This way, you reduce the security issues and possible problems with your system.

4. Known issues

Under some browsers, the control panel applet may appear clipped. There is no solution at the time except trying to use a different browser.

Apache configuration

The Drew tools use multi-language web pages. Apache has built-in capabilities to handle such sites through the Multiviews option. So, add the following line, whether in your main server configuration file, or in the .htaccess file found in the top level directory of the Drew installation.

Options +Multiviews

These tools also use server parsed HTML files. They are HTML files with directives such as:

<!--#include virtual="CSS/drew_full_foot.html" -->

Apache does not parse HTML files for such directives by default. We need to tell it to do so. There are two steps to make this work: firstly, enable the mod_include modules in the main Apache configuration file, secondly add the following directives to the right .htaccess files:

...
AddHandler server-parsed .html
Options +IncludesNOEXEC
...

Moreover, all the files handled by the server are XML file. The problem is, browsers usually do not know what to do with such files. A CGI script does the job of transforming these XML files into HTML ones. To launch the script when an XML file is encountered, we need to enable the mod_action module in the main Apache configuration file and add two more directives to the .htaccess files:

...
AddType text/xml .xml
Action text/xml /cgi-bin/pws/xml.pl
...

The first one tells the server that files ending with .xml should be considered as text/xml (this is the MIME type).

The second line states that files with a MIME type set to text/xml should be processed using the script xml.pl located in the /cgi-bin/pws directory, server wise.

If you encounter problems with these .htaccess files, this probably means that the Options directive is not allowed. You have to allow it in your main server configuration (see the AllowOverride, Directory and DocumentRoot runtime directives in the Apache manual2).

In the end, if you did not install the Drew tools under the main Apache tree or if permissions are restrictives, you have to modify the main Apache configuration file by adding a section which looks like:

	...
	<Directory "/var/www/html/Drew">
	#
	# This may also be "None", "All", or any combination of "Indexes",
	# "Includes", "FollowSymLinks", "ExecCGI", or "MultiViews".
	#
	# Note that "MultiViews" must be named *explicitly* --- "Options All"
	# doesn't give it to you.
	#
	    Options Indexes FollowSymLinks
	#
	# This controls which options the .htaccess files in directories can
	# override. Can also be "All", or any combination of "Options", "FileInfo",
	# "AuthConfig", and "Limit"
	#
	##    AllowOverride None
	    AllowOverride All
	#
	# Controls who can get stuff from this server.
	#
	    Order allow,deny
	    Allow from all
	</Directory>
	...

Administration

This section describes some actions that might be taken to administrate the Drew tools.

As stated earlier, these tools rely on a client-server protocol. The server works on subjects and generates traces.

1. Managing subjects

The files corresponding to the various subjects can be found in the Drew/Sujet/data directory.

There are two files per subject and two other files common to all the subjects. The common files are named 'list.html' and 'numero.txt'. The former contains the list of available subjects and is displayed in the browser when this list is required. The latter contains the number of the last subject created or 0 if no subject exist.

Each subject is represented by two files : 'modules_N.html' and 'sujet_N.html' (N must be the same for the two files). The latter contains the description of the subject as the students will see it. The former is a file used to launch the Java applet with correct parameters.

When a subject is deleted using the web interface, its name is only removed from the 'list.html' file. The two files related to this subject still exist on the server and the system administrator is then able, either to reinsert its name in the list.html file or to permanently remove it from the server.

2. Managing traces files

The Drew server traces every action taken when using the Drew tools, from logging to quitting. These traces are stored using the XML format and the UTF-8 character encoding. A single trace file is associated with a session and this file is human readable.

On a standard Drew installation, these trace files can be found in the Drew/Sujet/data/ directory. They are named 'sujet-N.utf8', where N is the number of the subject these traces are related to (this is actually the same as the N mentioned in the above section).

Every time the same subject is played, traces are appended at the end of the trace file associated to this subject. If you want to save a file at a given state (for further analysis for example), you need to move or copy it to a different name.

3. Internationalisation

The Drew tools come with the following localisation : English, French, Dutch, Portuguese, Finnish, Hungarian. This section explains how to add other languages.

These tools use the Java internationalisation mechanism. Each drewlet (a single Drew tool, or a Drew applet) is related to a Java filedrewletName.java which contains the default messages displayed by the applet (here the default language is English).

These files are located in the Drew/Locale/Server and Drew/Locale/Client directories of the Drew sources.

To add a new language to the already existing ones, you just have to copy the default file to something that looks like 'drewletName_CT.java', to edit it and then replace the stings by the one in the chosen language. CT represents the ISO2 code of the country using this language (examples : en for England, fr for France, nl for Dutch land, pt for Portugal, fi for Finland and hu for Hungary).
Note : once the new files added, you must recompile the entire application and re-install it.

 

Enjoy the DREW software !


  1. Uniform Resource Identificator
  2. Usually found at the /manual URI of your local web server