The Pedagogical Web Site

Process of installing the PWS software
on a computer running Linux (not Debian)


This file describes the process of installing the PWS software on a computer running Linux (not Debian) using the provided installer PwsInstaller-perlX-glibcY.jar (X and Y denote the version of you perl and glibc libraries).

Contents

Introduction

Depending on how your Linux has been installed, you will need to add some components required by the PWS :

  • a Perl interpreter,
  • an Apache web-server
  • and a Java Virtual Machine (a Development kit -- JDK -- or a Runtime Environment -- JRE).
On most Linux distribution, Perl is already installed as it is nowadays a highly useful language.
Apache is sometimes installed, but this is not the case of Java.

Installing the required software

1. Perl

As stated earlier, Perl should already be installed on your Linux distribution. If not, you need to grab a package suited to your distribution and install it. You only need to remember where you installed it, as you will be asked later.
The PWS works well with perl 5.6 or newer.

2. Apache

Apache is the most used web server on the Internet. Although, it is a free software and you can easily install it on your system.
Find a package that fits your system and install it. In the case of a PWS-only use, you will not need any additional components such as php or perl modules. The PWS has been successfully tested on version 1.3.2X and 2.0.X of the Apache web server.

Refer to section 5.1 of the next chapter for PWS-specific Apache configuration.

3. Java

Java is required by the PWS to run the Drew tools (applets).
Java components are sometimes distributed as distribution packages, but this is quite rare.
You can get a Java Virtual Machine (JVM) either from sun directly at

http://java.sun.org/

or at BlackDown (Linux-only Java distributions) at

http://www.blackdown.org/

You can get either a full JDK or only a JRE, which is smaller and contains everything needed to have the PWS run smoothly.

The PWS is made to run with Java 1.1.8 or earlier. It is known to work well on version 1.3.1 and has been tested with success on version 1.4.1.

3.1. Java as a plugin for your browser

In the case of the PWS, java is used as a plugin for your web browser.
The Java install, on the latest Linux distributions, sets up correctly its plugin for the most common browsers. If it does not work, please refer to the Java documentation to learn how to install the plugin correctly.

Installing the PWS

Here, you should already have downloaded the installer archive called PwsInstaller-perlX-glibcY.jar. If not, please do so.

The installer is launched by issuing the

java -jar PwsInstaller-perlX-glibcY.jar

Then, you only need to follow the steps described below :

1. Choosing your language, about the PWS and the license

The first thing to do is to choose the language you want the installer speak into. This does not affect the language of the final installation (where all the proposed languages are installed), but only the one of the installer.
After that, a brief explanation of what the PWS is, is displayed, and there comes the license panel. Please, read carefully ,this license (the LGPL) and tell whether or not you agree with the terms. You will then be able to go on the installation process unless you do not accept the terms of the license.

2. Choosing where to install the files

The next panel asks you where, on your filesystem, to install the files of the PWS. At this point, you have two main choices : whether you install this software in the install directory of your Apache web server, whether you install it in a its own directory. There is no preferred way ; you choose.

To install it in the default Apache directory, you need to enter the following path (which should already be given) :

/var/www/pws

If you do so, the pws directory will be created and everything will be put there. Nothing will appear elsewhere.

The resulting file hierarchy will be as follow :

          /var/www/pws
                     |
                     +- html
                     |      +- pws (All the required xml and xsl files)
                     |      +- classes (the Drew Client applets)
                     |
                     +- cgi
                     |      +- pws (The xml engine)
                     |
                     +- auth
                     |
                     +- classes (The Drew server)
                     |
                     +- libs (The Perl modules and some mandatory xml/xsl libs)

If you choose to install it elsewhere, only the root directory will be altered, not the file hierarchy.

3. Giving the path to the Perl interpreter and choosing how to access your installation through a web browser

The next panel asks you the last two questions of this install process.

In the first part, you need to give the path where the Perl interpreter is located (/usr/bin is correct most of the time).

The second part, asks you to choose the URI, relative to your web-server root, under which the PWS will be available. This is something you choose depending on your local web-server layout. Usually, the default '/pws' is OK, but you may want to change it. Assuming the web-server of your machine is reachable by the following URI :

http://foo.bar.org/

the PWS will show under this one

http://foo.bar.org/pws/

So, when the installation is completed, you can access the software by pointing a web browser to this URI.

4. Some clicks later...

The following panels are only informative and allow you to check if what you have entered is correct, and to launch the install itself.
The last panel creates an automatic installed, which is useful if you want to duplicate the same installation on other computers without having to retype everything.

5. What we get at the end

Once you have closed the installer, the biggest part of the installation process is done. You end up with the complete file hierarchy of the PWS copied to you computer, a file named 'pws.conf' and an automatic uninstaller located in the Uninstall directory, both at the root of your installation (/var/www/pws if you chose the default).

But unfortunately, there are some few steps you have to do by hand.

5.1. Modifying the Apache configuration

NOTE : all the steps below require super-user access.

You need first to tell Apache that some new documents have been added to its hierarchy.

There are several ways to acceive this, whether or not your distribution of Apache has a conf.d directory in /etc/httpd/.
If this is the case, just copy (or move) the file named 'pws.conf' located in the root directory to /etc/httpd/conf.d/.
If you do not have such a directory, you will need to edit the Apache configuration file (usually 'commonhttpd.conf' or only 'httpd.conf' in the /etc/httpd/conf/ directory), including the directive found in the header of the 'pws.conf' file (the one begining by Include).

Then you need to enable the use of some more modules. To do so, uncomment the lines related to theses modules in the apache configuration file (if you have both 'httpd.conf' and 'commonhttpd.conf', these directives are located in the former). The modules we use are mod_env, mod_action, mod_mime and mod_auth.
Following are the lines to uncomment in the file :

...
LoadModule env_module libexec/httpd/mod_env.so
LoadModule action_module libexec/httpd/mod_actions.so
LoadModule mime_module libexec/httpd/mod_mime.so
LoadModule auth_module libexec/httpd/mod_auth.so
...
AddModule mod_env.c
AddModule mod_actions.c
AddModule mod_mime.c
AddModule mod_auth.c
...

5.2. Restarting Apache

The last step is then to restart Apache. To do so, use whether the 'init.d' script or, easier, the 'apachectl' (or 'apache2ctl', or 'httpctl' or 'httpdctl') command.

You may want to first check the syntax of the file by issuing a 'apachectl -t' command in a terminal window.

Using this command actually restarts the server and do some more checking in the syntax of the config file.

Please note that restarting Apache is mandatory !

6. About passwords

The PWS site has several sub sites which can only be accessed via password authentication (administration and teacher parts).
The default login/passwords are :

  • teacher/teacher for the teacher part
  • admin/admin for the admin part

We strongly encourage you to change these defaults by something less easy to guess. At this time, you need to use the terminal to do it. The command to use is 'htpasswd' (or 'htpasswd2'), and following is an example of how to use it (default installation path is used for this example, adapt it to your installation) :

htpasswd -m /var/www/pws/auth/pws.auth admin new_admin_password
htpasswd -m /var/www/pws/auth/pws.auth teacher new_teacher_password

Passwords created for students groups are stored in this same file, but are created and modified via a web interface inside the PWS.

 

Enjoy the PWS software !