Here's the preliminary version of the "long form" of the docs for Debian. Please post comments or changes. Use at your own risk.
-samuel

Installing WeBWorK on a Debian GNU/Linux 2.2 System

Samuel Hathaway, <sh002i@math.rochester.edu>;
Chris Harrington, <ch003i@math.rochester.edu>;

Installing WeBWorK on Debian GNU/Linux is very similar to installing it on other UNIX systems, with several exceptions. Most of the support packages needed are available within the Debian distribution, so compilation is not necessary. Several distribution conventions are different on debian, necessitating the modification of some pathnames.

Most steps in the installation process can be done as a normal user. However, some steps must be done as the root user. While attempts have been made to minimize the number of commands that must be executed as root, it is still important to be cautious whenever using the root account.

Within this document, commands given by root will be prefixed with "#" while commands given by a normal user will be prefixed with ">". Note that throughout this document, all references to a "normal user" refer to the same normal user.</>

Step 1: Installing additional Debian packages

As root, use apt-get to install additional packages needed for WeBWorK. Additional packages on which these packages depend may need to be installed as well, depending on the state of your system. apt-get handles this automatically.

We'll start with the perl modules: (The backslashes allow us to split this command over multiple lines.)

# apt-get install libgd-perl libhtml-parser-perl 
                  libmime-base64-perl libnet-perl 
                  libcgi-pm-perl

Next, we'll install LaTeX2HTML (used for rendering of WeBWorK problems), apache (the web server), gcc (a compiler), and libc-dev (used in the compilation of TTH).

# apt-get install latex2html apache gcc libc-dev

Apache requires some degree of configuration. apt-get will run apacheconfig as part of the installation process. libpaperg, a package required by LaTeX2HTML, will prompt you for a default page size during it's installation. It is safe to accept the default size of "letter".

LaTeX2HTML is broken with respect to the WeBWorK system when installed. To fix it, set the following configuration variables as follows in the file /etc/latex2html.config

$PK_GENERATION = 1
$DVIPS_MODE    = 'toshiba'
$METAFONT_DPI  = 180

Step 2: Installing the WeBWorK package

WeBWorK can be downloaded from following URL: http://webhost.math.rochester.edu/downloadwebwork/

If you haven't already, you need to register to be able to download files. The WeBWorK archives are named in the following form:

webwork_VERSION_SUBVERSION-MONTH-DAY.tar.gz
templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz

As a normal user, download the latest versions of these two archives. The templates archive is not necessary during installation, but is useful later. Untar the WeBWorK archive using:

> tar -xzf webwork_VERSION_SUBVERSION-MONTH-DAY.tar.gz
(replacing the file name with the file you actually have.)

This results in the creation of several readme files and the webwork.tar archive, which contains the actual webwork system. Next we must copy the webwork.tar archive to /usr/local, where we will untar it and remove the archive. As root, run:

# chmod 777 /usr/local

As a normal user, run:

> mv webwork.tar /usr/local
> cd /usr/local
> tar -xf webwork.tar
> rm webwork.tar

As root, run:

# chmod 755 /usr/local

The WeBWorK files are now in their initial location. Next, a user group must be created for users who are allowed to modify all WeBWorK files. It is recommended that this group be named wwadmin. As root, execute:

# addgroup wwadmin 
# adduser <username> wwadmin

You can add any number of users with the second command, replacing <username> with the name of the user to add. Make sure that you add the user account that you are going to be using to finish setting up the system.

We'll make webwork directories on apache's document root and cgi-bin directory. /var/lib/webwork will contain symlinks to each course homepage. /usr/lib/cgi-bin/webwork is used in the next step. As root, create the following:

# mkdir /usr/lib/cgi-bin/webwork
# mkdir /var/www/webwork

Now, well give you ownership of these files so you can add courses later without becoming root. As root, execute:

# chown <username>.wwadmin /usr/lib/cgi-bin/webwork
# chown <username>.wwadmin /var/www/webwork

We need to allow apache access to WeBWorK's cgi and html directories. Because debian's default apache installation follows symlinks, we can simply use a couple of symlinks to achieve this. As a normal user, type:

> ln -s /usr/local/webwork/system/cgi /usr/lib/cgi-bin/webwork/system
> ln -s /usr/local/webwork/system/system_html /var/www/webwork_system_html

The next step uses your normal user account, and requires membership in the wwadmin group. Thus, you'll need to log out of this account and then log back in. Next, we'll set the group of the entire WeBWorK system to wwadmin and give it some default permissions. As a normal user:

> chgrp -R wwadmin /usr/local/webwork/
> chmod -R 755 /usr/local/webwork/

These are very lax permissions, but that will be fixed when we run the setup script. As a normal user:

> cd /usr/local/webwork/system
> ./system_webwork_setup.pl

This script will ask you several questions about the environment in which WeBWorK will be running. Read the information given with each choice carefully. Recommended choices are as follows:

Q: Do you wish to setup a "working" or a "demo" version (w or d)? 
A: w
Q: Is the web server running in a chroot environment (y/n)?
A: n
Q: What is the full path to perl?	
A: press ENTER
Q: What is the cgi-URL?
A: press ENTER
Q: What is html-URL?
A: press ENTER
Q: Enter the group name:
A: wwadmin
Q: Set courses permissions?  (y or n)
A: y
Q: Do you want to set the group for all directories and files?
A: y
Q: do you want to set default "working" permissions for the system
   directory and files?
A: y

WeBWorK assumes that LaTeX2HTML is installed in /usr/local rather than in /usr as it is on Debian. There are two lines at the end of the file displayMacros.pl which must be changed. The path of this file is: /usr/local/webwork/system/courseScripts/displayMarcros.pl

change: system("/usr/local/bin/latex2html ...
to:     system("/usr/bin/latex2html ...

WeBWorK uses TTH, a C program which typesets TeX as HTML, using tables and other markup. TTH cannot be distributed with WeBWorK because of licencing issues. It can be obtained from the following URL: http://hutchinson.belmont.ma.us/tth/

As a normal user, download TTH to your home directory. Then untar, build, and install it with the following commands:

> tar -xzf tth_C.tgz
> cd tth_C
> gcc -o tth tth.c
> mv tth /usr/local/webwork/system/scripts/

There are some user-definable settings that you should customize in the file Global.pm. This file is located at: /usr/local/webwork/system/Global.pm

$feedbackAddress
	The address used for Feedback buttons on WeBWorK's HTML
	pages.
$legalAddress
	A perl regular expression which email addresses must in order
	to be considered valid.
$webmaster
	The email address of your site's webmaster.
$smtpServer
	Your sendmail server. It should usually be set to 127.0.0.1,
	unless you elected not to set exim up during the debian
	installation. In that case, specify another server.
$dirDelim
	The character which separates directories in a path name: "/"

Okay, now you've finished installing WeBWorK. However, there is one nuance which needs to be considered before proceeding.

Step 3: Separating Static and Variable WeBWorK data

Right now, all WeBWorK files are located under /usr/local. While this is the simplest setup, it is not the best way to do things. The WeBWorK "system" is fine under /usr/local as it is static data which is not going to change during the life of the system, does not need to be backed up frequently, and can be located on a read-only storage medium (after initial configuration, of course). However, the "courses" data should really be located under /var/local, as it is variable data and should be on storage that is mounted read-write and is backed up regularly. If you want to do this the "right" way, follow the instructions below.

As root, create a webwork directory in /var/local and set privileges on it:

# mkdir /var/local/webwork
# chown <username> /var/local/webwork
# chgrp wwadmin /var/local/webwork

As a regular user, move the courses directory into your new webwork directory:

> mv /usr/local/webwork/courses /var/local/webwork

Now, a slight modification to the structure of the WeBWorK system structure must be made. The directory /usr/local/webwork/system/courses contains symlinks to each course directory, for use by system scripts. These symlinks must be created manually for each course. Instead of this, we would like this directory to point to the actual courses directory. Therefore, as a normal user, run:

> rm -r /usr/local/webwork/system/courses
> ln -s /var/local/webwork/courses /usr/local/webwork/system

Also, it is a good idea to "crosslink" the courses and system directory so that we can easily move between them without typing out the absolute paths:

> ln -s /var/local/webwork/courses /usr/local/webwork
> ln -s /usr/local/webwork/system /var/local/webwork

Some WeBWorK documentation will instruct you to maintain symlinks in /usr/local/webwork/system/courses. After you make these modifications, you no longer need to do this.

Step 4: Installing the Demonstration Course

Not only is the demo course important to the verification of your WeBWorK installation, it also serves as the basis for any additional courses you create. In setting up this course, you'll gain a basic understanding of how the course architecture works.

Each course has a UNIX user group associated with it. The group should contain any users who should be able to view or edit the course files directly (such as the professor and any teaching assistants), and the user under which the web server runs, www-data. The convention on Rochester's installation of WeBWorK is to name each group after the course it represents, only using capital letters. However, because Debian's verison of addgroup complains about capital letters in user and group names, we'll user the --force-badname switch to allow it.

As root, create a group for demoCourse and add yourself and the web server to it. Since we're adding the web server to a new group, we have to restart it:

# addgroup --force-badname DEMOCOURSE
# adduser www-data DEMOCOURSE
# adduser <username> DEMOCOURSE
# /etc/init.d/apache restart

Now, log out of your normal user account and log back in so that your group membership will be recognized.

Each course has a "visible" interface in the webwork directory on the web server's document root. This allows the course home page to be accessed via http://servername/webwork/courseName rather than having to call the login script directly. As a normal user, create this link:

> ln -s /usr/local/webwork/courses/demoCourse/html /var/www/webwork/demoCourse

WeBWorK comes with a script which completes the setup of a new course. We'll run it now, as a normal user:

> cd /usr/local/webwork/courses/demoCourse
> ./course_webwork_setup.pl

This script will ask you several questions about the environment in which the course will be used. Read the information given with each choice carefully. Recommended choices are as follows:

Q: Do you wish to setup a "working" or a "demo" version? (w or d)
A: w
Q: Do you want to create missing directories (if any)? (y or n)
A: y
Q: ENTER course URL
A: press ENTER
Q: ENTER cgi WeBWorK URL
A: press ENTER
Q: ENTER course link (i.e. classID) name
A: press ENTER
Q: ENTER group name
A: DEMOCOURSE
Q: Do you want to create a new webworkCourse.ph...?
A: y
Q: Do you want to create a new index.html...?
A: y
Q: Do you want to set the group for all directories and files?
A: y
Q: Do you want to set default "working" permissions for all directories
   and files?
A: y

Now, we're going to run some scripts to finish setting up the course. Now would be a good time to add the scripts directory to your search path, so that you don't have to type the full path of the command each time. If you are using bash, add this line to the bottom of the .bash_profile file in your home directory:

PATH = "/usr/local/webwork/system/scripts:${PATH}"

Log out and log back in again to add the new path. Now we'll run these scripts. As a normal user:

> cd /usr/local/webwork/courses/demoCourse/templates
> import_classlist-database.pl demoCourse demoCourse.lst
> setProfPermissions.pl demoCourse apizer

There. You've finished the demoCourse setup. To verify that you've set everything up properly, view the following URL in your browser: http://servername/webwork/demoCourse

If this works, click the Login button and enter the following information:

login:    apizer
password: 111-11-1111

Click Enter Professor's Page. You should now be logged in as the professor. Even though this is only the demo course, it's a good idea to change your password to prevent unauthorized access.

While we're here, we can test to make sure that all of the problem rendering methods work. Here is an excerpt from the general WeBWorK installation document detailing how to do this:

Click Enter Build Problem Set Page (the only choice you should see)

Select all the sets and then click Build Problem Set(s) You will see a list of the sets which have been built. Now build some problem sets. You will see a list of the sets which have been built. At the bottom of the page click Problem Sets

Select a set, e.g set Algebra1RealNumbers, select PDF form, and click Get_Hard_Copy. After a short wait (since this is the first time TeX has probably been run, fonts may have to be created, etc), Acobat should start and you should see a copy of the set. You can select postscript output if your client computer can display that (e.g using Ghostview). Note: the first few times you use Get_Hard_Copy it may take quite some time as the computer probably has to run Metafont to create TeX fonts. The second time you run Get_Hard_Copy on the same problem set will give you a better idea of how fast your system will usually respond.

Next click Do Problem Set and view a few problems. Use the selected mode which, at present, is TEXT which means TeX source code. Next for say problem 2, select "formatted-text", and hit submit answers. This uses tth and which should be working. With this mode math symbols appear on the screen composed of ascii characters. Note "typeset" mode will not be working yet. Go to problem 10, enter 12/23 and hit Preview Answers. You should see the type set fraction 12 over 23.

At this point you should have a functioning course. You can login as a practice user (username practice1, ..., practice4), apizer with password 111-11-1111, gage with password 444-44-4444, etc. All usernames and initial passwords are lised in /www/webwork/courses/demoCourse/templates/demoCourse.lst. The first entry of a record is the userid which is the initial password and the last entry of a record is the username. Actually the users are taken from the classlist database which you can view from the Classlist page.

Note that demoCourse is a dynamic functing course. Since this is used as a template to setup other courses, you may want to copy demoCourse into a new course, say templateCourse, check that templateCourse functions properly, and then freeze it (turning it into a non functioning course) by doing a chmod -R 444 templateCourse . That way you could use the templateCourse in setting up new courses and you will know that it has not been changed by any users.

So now you're done.

Step 5: Obtaining Additional Support

Online support is available at: http://webwork.math.rochester.edu/docs/

<| Post or View Comments |>