Installing WeBWorK on a Linux System

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

This document will guide you through the installation of WeBWorK and its support packages. I assume the reader has prior experience with UNIX system administration tasks such as compiling software, configuring the Apache server, etc.

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 Perl

On most Linux distributions, the distribution version of perl is adequate for use with WeBWorK. In particular, perl must be compiled with GDBM database support. Whether this is so can be determined in one of two ways:

For static linkage, check the libs= line in the perl version information. You should see an item -lgdbm. For dynamic linkage, check the output of ldd for perl. You should see an item libgdbm.

> perl -V | grep libs=
> ldd `which perl`

If GDBM is not present in either of these outputs, perl needs to be recompiled with GDBM support. The perl compilation process will automatically compile GDBM support if GDBM the libraray is detected. Most Linux distributions come with the GDBM library. It is called libgdbm and is usually found in /usr/lib or /usr/local/lib. Please refer to the perl source code distribution site for information about compiling and installing perl.

Please note that if you recompile perl, you may have to be careful about maintaining two copies of perl on your system. In particular, make sure that when you type perl at a command prompt, the version you just compiled is invoked. For convenience, you may want to remove the original version of perl. The perl install process will ask you if you want to do this.

Step 2: Installing additional packages

As root, use CPAN to install additional perl modules needed for WeBWorK. If this is the first time you're run CPAN, you will be required to configure it.

# perl -MCPAN -e shell
cpan> install GD HTML::Parser Net::SMTP MIME::Base64

CPAN may prompt you for configuration settings for the modules you are installing.

Next, you will need to install several support programs used by WeBWorK. Most distributions include packaged versions of these programs, but they are not always installed by default. Consult the documentation for your distribution to find out if you can use a prepackaged version. If you wish, you can also install from source:

• Apache: http://httpd.apache.org/
• C libarary headers: http://www.gnu.org/software/libc/
• GCC: http://gcc.gnu.org/
• Ghostscript: http://www.cs.wisc.edu/~ghost/
• LaTeX2HTML: http://saftsack.fs.uni-bayreuth.de/~latex2ht/
• a TeX distribution, such as TeTeX: http://www.tug.org/teTeX/

LaTeX2HTML

LaTeX2HTML has some dependancies of its own. Consult the LaTeX2HTML Requirements Page for more information.

Only LaTeX2HTML version 96.1 and 98.1p1 have undergone extensive testing with WeBWorK. WeBWorK ships with latex2html.init files for each if these versions. However, the init file for version 98.1p1 appears to work with later versions.

LaTeX2HTML may be broken with respect to the WeBWorK system when installed. To fix it, make sure the following configuration variables are set as follows in the LaTeX2HTML configuration file, which may be called latex2html.config or l2hconf.pm and may be located in /etc or in the LaTeX2HTML directory, depending on the version and how it was installed.

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

One of LaTeX2HTML dependancies is netpbm, which does not function properly in versions lower than 9.11. Either upgrade to version 9.11 or later, or apply the patches detailed at: http://webhost.math.rochester.edu/webworkdocs/discuss/msgReader$390

Step 3: Configuring Apache

Note: Since the locations of apache's document root and cgi-bin directories are distribution dependant, I will use $DOCUMENT_ROOT and $CGI_BIN to refer to these locations. If you wish, you can set these two variables in your shell so that you can type them directly.

Your apache configuration may need to be tweaked to allow WeBWorK to function properly. First, you must make sure that apache runs as a real system user and in a real system group, rather than as nobody in nogroup. This is becasue the WeBWorK scripts need to be able to modify certain course files on the disk. Some distributions of apache already run as a real system user. If you wish, you may skip the creation of a new user and group, and use the existing ones. If you need to change apache's user and group, first create a new user and group called webwork:

# useradd webwork
# groupadd webwork

You'll also want to add yourself to the webserver's group. As root:

# usermod -G webwork,<othergroups> <username>

Note: The usermod command will remove a user from any groups not specified with the -G switch. Make sure to list all the groups to which a user belongs when using this command. This manual uses user{add,mod,del} and group{add,mod,del} as these utilities are available on most linux systems. It is often easier to use a more user-friendly tool provided with your distribution, or edit the /etc/group file directly.

Then, in the apache configuration file httpd.conf, usually found in /etc/apache or /usr/local/etc/apache, find the following lines:

User nobody
Group nogroup

Change them so that they list webwork as the user and group:

User webwork
Group webwork

There are two ways that the webserver can be given access to WeBWorK files. The first is to add an explicit ScriptAlias to the WeBWorK cgi directory in your apache configuration. The second is to create a symlink pointing from your existing cgi-bin directory to the WeBWorK cgi directory. Even if you chose to use symlinks, you will have to make sure that the FollowSymLinks option is on for the document root and cgi-bin directories.

In either case, your document root must have FollowSymLinks turned on. In one of your apache configuration files, find the direcotry stanza for the document root. It will look roughly like this:

<Directory $DOCUMENT_ROOT>
	Options FollowSymLinks Indexes Includes
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

The important line is Options FollowSymLinks. Make sure that that is present. It is okay if other options are present too. If you chose to symlink to the WeBWorK cgi-bin directory, also make sure that the directory stanza for your cgi-bin directory has FollowSymLinks turned on:

<Directory $CGI_BIN>
	Options FollowSymLinks ExecCGI
	AllowOverride None
	Order allow,deny
	Allow from all
</Directory>

If you chose to use a ScriptAlias to link apache to the WeBWorK cgi-bin directory, you will need to add the following to your apache configuration:

ScriptAlias /cgi-bin/webwork/system/ "/usr/local/webwork/system/cgi/"
<Directory /usr/local/webwork/system/cgi/>
	Options FollowSymLinks
</Directory>

Make sure that these lines go before any existing ScriptAlias directives. Remember to restart apache after making these changes.

Step 4: 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

The webwork archive contains the webwork system files and the blankCourse. The templates archive contains the problem set templates, and is updated more often than the webwork archive is.

As a normal user, download the latest versions of the webwork archive. 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:

# mv webwork /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:

# groupadd wwadmin
# usermod -G wwadmin,<othergroups> <username>

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 a webwork directory in apache's document root to contain a symlink to each course. We'll also give you ownership of this directory so you can add courses later without becoming root. As root, type the following:

# mkdir $DOCUMENT_ROOT/webwork
# chown <username>.wwadmin $DOCUMENT_ROOT/webwork

If you chose not to add a ScriptAlias directive to your apache configuration, you also need to add a webwork directory to apache's cgi-bin directory.

# mkdir $CGI_BIN/webwork
# chown <username>.wwadmin $CGI_BIN/webwork

We need to allow apache access to WeBWorK's html directory. As root, type:

# ln -s /usr/local/webwork/system_html $DOCUMENT_ROOT/webwork_system_html

Again, if you didn't add a ScriptAlias directive to your apache configuration, you also need to allow apache access to WeBWorK's cgi directory:

> ln -s /usr/local/webwork/system/cgi $CGI_BIN/webwork/system

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 permissions are very lax, but that will be fixed when we run the setup script. As a normal user:

> cd /usr/local/webwork/system
> perl 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 given in brackets, and can be accepted by pressing enter rather than typing a response.

In order to use logging, you need to give the web server write access to the logs directory. As root:

# chgrp -R webwork /usr/local/webwork/system/logs

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

Then, as root, install it.

# cp tth /usr/local/bin/

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

################################
# Local configuration settings #
################################

$legalAddress
A perl regular expression which email addresses must in order
to be considered valid.
$feedbackAddress
$webmaster
Addresses used in script output.
$defaultfrom
$defaultreply
Addresses used in professor email sending functionality.
$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.
For UNIX systems this should be set to "/".

###########################
# Local external programs #
###########################

$externalTTHPath
The path to TTH. Usually "/usr/local/bin/tth".
$externalLaTeX2HTMLPath
The path to LaTeX2HTML. Usually "/usr/local/bin/latex2html".
$externalLaTeX2HTMLVersion
The version of LaTeX2HTML installed. This controls what
switches are sent to the program. For version 98.1p1 or
later, use "98.1p1". For earlier versions, use "96.1".
$externalLaTeX2HTMLInit
The path to the LaTeX2HTML init file. You can leave this
as is.

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

Step 5: Installing the problem set template files

Before WeBWorK can be functional, problem set template files must be present. Download the templates archive from the WeBWorK web site, as you did with the WeBWorK archive.

templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz

Move the templates archive to the WeBWorK directory and untar it.

> mv templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz /usr/local/webwork
> tar -xzf templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz
> rm templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz

The problem set templates are not accessed directly from this location. They are instead copied into each course which is created. This allows professors to modify their local copies without disturbing other courses.

Step 6: Creating a course

To test your installation of WeBWorK, you must now create a course. The template you will use to create this course is located in /usr/local/webwork/courses/blankCourse. The course we are going to create now will be called demoCourse.

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 system user under which the web server runs, webwork. The convention on Rochester's installation of WeBWorK is to name each group after the course it represents, only using capital letters. However, some Linux distributions disallow uppercase group names. Use your own judgement.

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:

# groupadd DEMOCOURSE
# usermod -G DEMOCOURSE,<othergroups> webwork
# usermod -G DEMOCOURSE,<othergroups> <username>
# apachectl restart

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

Next, you will need to make a copy of blankCourse called demoCourse and add some problem set templates to it. As a normal user:

> cd /usr/local/webwork/courses
> cp -R blankCourse demoCourse
> cd demoCourse/templates
> cp -R /usr/local/webwork/templates/set0 .
> cp /usr/local/webwork/templates/set0.def .

Repeat the last two commands for any other sets you wish to import into the demo course. A popular option is to import all of the sets. To do this, type:

> cp -R /usr/local/webwork/templates/set* .

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
> /usr/local/webwork/system/scripts/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

To let the WeBWorK system know that it has a new course, add a symlink to demoCourse to the system/courses directory. If you do not do this, the WeBWorK system will not be able to access the course this is a good way to "turn off" a course.

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

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 $DOCUMENT_ROOT/webwork/demoCourse

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
> import_classlist-database.pl demoCourse defaultClasslist.lst
> setProfPermissions.pl demoCourse professor

There. You've finished the demoCourse setup. The process for setting up additional courses is identical to this. To verify that you've set everything up properly, view the following URL in your browser: http://your.server.name/webwork/demoCourse

You should see your newly-generated course index page. If this works, click the Login button and enter the following information:

login:    professor
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. First, click Enter Build Problem Set Page. Then, select one or more problem sets from the list and click Build Problem Set(s). WeBWorK will report that the problem sets have been built. At the bottom of the resulting page, click Problem Sets.

Now that the sets have been built, you can test various methods of displaying them. Select a set, select PDF form and click Get_hard_copy. After a moment, WeBWorK will send you a PDF file. Acrobat may open automatically, or you may have to wrestle with your browser a bit to see it.

Next, we can check onscreen display. Select a problem set and click Do_problem_set. View several problems from the set on all three display modes: text, raw TeX source code, formatted-text, TTH output, and typeset, LaTeX2HTML output. Typeset mode takes quite some time on the first view of any problem as it has to generate images for the equations. However, subsequent views take advantage of cached temp files.

Step 7: 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 set up WeBWorK this 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 course symlinks in /usr/local/webwork/system/courses. After you make these modifications, you no longer need to do this.

Step 8: Obtaining Additional Support

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

<| Post or View Comments |>